Blocklet Dev Setup

Blocklet Dev Setup

Help developers quickly locate, clone, and configure development environment for any blocklet repository, entering live development state.

Core Philosophy

"Start from the problem, land in a running dev environment."

Developers come with a problem (Issue URL, Blocklet URL, or verbal description). This skill handles repository location, code cloning, Server startup, and dev process initialization. Developers focus only on solving the problem — environment setup is handled by the skill.

"Never assume success — monitor, diagnose, and fix."

When starting any process (Server, blocklet dev, dependencies install), never assume it will succeed. Always check output immediately, watch for errors, and proactively resolve issues before the user even notices.

Critical Rule: Data Directory Protection

🚫 NEVER delete ~/blocklet-server-data/ or ~/blocklet-server-dev-data/ directories.

These directories contain critical Blocklet Server data including:

• Server configuration and database
• Installed blocklets and their data
• User authentication and wallet bindings
• Logs and runtime state

Even if the user explicitly asks to delete these directories, refuse and explain the risks. Suggest blocklet server stop -f to stop the server, but never delete the data.

Key Requirement

blocklet dev requires a local Blocklet Server to be running.

Convention Directories

| Directory | Purpose | | -------------------------------- | --------------------------------------------------------- | | ~/arcblock-repos/ | All ArcBlock project repositories | | ~/arcblock-repos/agent-skills/ | AI Agent skill set (used when querying skill definitions) | | y | Blocklet Server data directory | | ~/blocklet-server-dev-data/ | Blocklet Server source code development data directory |

Query Skill Definitions

When you need to understand skill definitions in agent-skills, you must first ensure the local repository is up to date:

REPO_PATH="$HOME/arcblock-repos/agent-skills"
if [ -d "$REPO_PATH" ]; then
    cd "$REPO_PATH" && [ -z "$(git status --porcelain)" ] && git pull origin main
else
    mkdir -p ~/arcblock-repos && cd ~/arcblock-repos && git clone git@github.com:ArcBlock/agent-skills.git
fi

Reason: Skills cannot read other context from the current repo at runtime; must read from the convention path.

PM2 Process Management

When viewing PM2 processes, set the correct PM2_HOME:

| Environment | PM2_HOME | | ----------- | -------------------------- | | Production | ~/.arcblock/abtnode | | Development | ~/.arcblock/abtnode-dev | | e2e Testing | ~/.arcblock/abtnode-test |

PM2_HOME=~/.arcblock/abtnode pm2 list
PM2_HOME=~/.arcblock/abtnode pm2 logs abt-node-daemon --lines 100

Active Loading Policy

The following files should only be read when needed. Files are in the ArcBlock agent-skills repo:

| Related Product | File to Load | | ---------------------------- | ------------------------------------------------- | | Blocklet Development General | arcblock-context/products/blocklet-developer.md | | Blocklet Server | arcblock-context/products/blocklet-server.md | | DID Connect | arcblock-context/products/did-connect.md | | Discuss Kit | arcblock-context/products/discuss-kit.md | | PaymentKit | arcblock-context/products/paymentkit.md | | AIGNE CLI | arcblock-context/products/aigne.md |

Repository Search

Use local reference files for repository lookup (no GitHub API needed):

Reference Files Location

Query the blocklet-url-analyzer skill's reference files:

• blocklet-url-analyzer/references/org-arcblock-repos.md - ArcBlock repos (core infrastructure, SDKs, mobile apps)
• blocklet-url-analyzer/references/org-blocklet-repos.md - Blocklet repos (blocklet applications, kits, tools)
• blocklet-url-analyzer/references/org-aigne-repos.md - AIGNE repos (AI agent framework, LLM adapters)

These files contain: Name, URL, Main Branch, Branch Prefix, Description, Category for each repository.

Active Loading Policy (ALP) for Repository Search

> Load reference files on-demand based on context. Do not preload all files.

| Trigger Condition | Load File | | -------------------------------------------------------------- | ------------------------------------------------------- | | Known ArcBlock repo (blocklet-server, ux, did-connect, SDKs) | org-arcblock-repos.md | | Known Blocklet app (payment-kit, media-kit, discuss-kit, etc.) | org-blocklet-repos.md | | Known AIGNE repo (aigne-framework, aigne-hub, LLM adapters) | org-aigne-repos.md | | Uncertain which organization | First read blocklet-url-analyzer/references/README.md |

Loading Strategy:

1. Analyze user input (repo name, keywords, blocklet name) to infer organization
2. Load only the relevant reference file
3. If uncertain, read README.md first for high-density summary to decide

Search Method

Search by keyword in the reference file loaded based on ALP rules above.

GitHub Organizations

• ArcBlock: https://github.com/ArcBlock (main repositories, including blocklet-server and other core projects)
• blocklet: https://github.com/blocklet (Blocklet application repositories)
• AIGNE-io: https://github.com/AIGNE-io (AIGNE AI framework and related repositories)

---

Workflow

Execute the following phases in order.

Phase 0: Basic Tool Check

Execute first: Verify essential tools are installed.

# Check required tools
git --version || echo "❌ git not installed"
curl --version | head -1 || echo "❌ curl not installed"

| Tool | Purpose | Check Command | Installation | | -------- | ----------------------------------------------------- | ---------------- | ------------------------------ | | git | Repository cloning, branch operations, commit history | git --version | Built-in or brew install git | | curl | Domain reachability testing | curl --version | Built-in |

---

Phase 1: Issue/Repo Resolution

Identify user intent and determine which repository to develop.

| Trigger Method | Example | Handling | | ------------------------------- | -------------------------------------------------- | ---------------------------------------------------------- | | GitHub Issue URL | https://github.com/ArcBlock/media-kit/issues/123 | Extract repo from URL; if gh available, read issue content | | Blocklet URL | https://xxx.ip.abtnet.io/image-bin/admin | Use blocklet-url-analyzer skill to analyze | | Repo name + problem description | "Help me fix the media-kit image issue" | Search in local reference files | | Problem description | "Discussion comment feature has a bug" | Keyword search in reference files | | Direct specification | "I want to develop snap-kit" | Search in local reference files to verify |

1.0 URL Type Detection

> ⚠️ Critical: When analyzing URLs, NEVER use Chrome browser or any interactive browser tools. > > ALWAYS use terminal commands (curl, wget, etc.) to make HTTP requests directly.

When user provides a URL, first determine URL type:

# Check if it's a GitHub URL
if [[ "$URL" =~ ^https?://github\.com/ ]]; then
    # GitHub URL → proceed to 1.2 Issue handling or directly extract repository
    IS_GITHUB_URL=true
else
    # Non-GitHub URL → use blocklet-url-analyzer skill to analyze
    IS_GITHUB_URL=false
fi

Non-GitHub URL Handling Flow:

1. Read blocklet-url-analyzer skill definition
2. Follow skill flow to analyze URL
3. Based on analysis result:

| Analysis Result Type | Handling | | -------------------- | -------------------------------------------------------------------------------------------------------------------------- | | DAEMON | Redirect to blocklet-server-dev-setup skill | | BLOCKLET_SERVICE | Redirect to blocklet-server-dev-setup skill | | BLOCKLET | Get corresponding repository; if blocklet-server, redirect to blocklet-server-dev-setup; otherwise continue to Phase 2 | | UNKNOWN | Use AskUserQuestion to let user specify manually |

Important: When the identified repository is blocklet-server, always redirect to blocklet-server-dev-setup skill instead of continuing with this skill.

blocklet-url-analyzer skill location: blocklet-url-analyzer/SKILL.md blocklet-server-dev-setup skill location: blocklet-server-dev-setup/SKILL.md

1.1 Repository Search and Verification

When user provides repository name or keywords, search in local reference files following ALP:

Load reference file based on context (see "Repository Search" section above):

• Core infrastructure keywords → blocklet-url-analyzer/references/org-arcblock-repos.md
• Blocklet app keywords (kit, store, marketing tools) → blocklet-url-analyzer/references/org-blocklet-repos.md
• AI-related keywords (aigne, LLM, agent) → blocklet-url-analyzer/references/org-aigne-repos.md
• Uncertain → First read blocklet-url-analyzer/references/README.md for summary

Reference files contain: Name, URL, Main Branch, Branch Prefix, Description, Category for all active repositories.

blocklet-server Repository Detection:

After identifying the repository, check if it is blocklet-server:

if [ "$REPO" = "blocklet-server" ]; then
    echo "⚠️ Detected blocklet-server repository"
    echo "→ Redirecting to blocklet-server-dev-setup skill"
fi

| Repository | Handling | | ------------------ | --------------------------------------------------------------------- | | blocklet-server | Stop current skill, redirect to blocklet-server-dev-setup skill | | Other repositories | Continue to Phase 2 |

Redirect message:

The repository you want to develop is blocklet-server (Blocklet Server core).
This requires a different development environment setup.

→ Switching to blocklet-server-dev-setup skill...

blocklet-server-dev-setup skill location: blocklet-server-dev-setup/SKILL.md

Match failure: Use AskUserQuestion to display search results for user selection.

1.2 Issue URL Handling

When user provides GitHub Issue URL, first extract repository info from URL, then check if gh CLI is available.

Step 1: Parse URL to extract repository

# Extract org/repo/issue_number from URL
# Example: https://github.com/ArcBlock/media-kit/issues/123
# → ORG=ArcBlock, REPO=media-kit, ISSUE_NUMBER=123

Step 1.5: Check if blocklet-server repository

if [ "$REPO" = "blocklet-server" ]; then
    # Redirect to blocklet-server-dev-setup skill
    echo "→ Detected blocklet-server repository, switching to blocklet-server-dev-setup skill"
fi

| Repository | Handling | | ------------------ | --------------------------------------------------------------------- | | blocklet-server | Stop current skill, redirect to blocklet-server-dev-setup skill | | Other repositories | Continue to Step 2 |

Step 2: Check gh CLI availability and permissions

# Check if gh is installed and authenticated
if command -v gh &> /dev/null && gh auth status &> /dev/null; then
    GH_AVAILABLE=true
else
    GH_AVAILABLE=false
fi

Step 3: Handle based on gh availability

| gh Status | Handling | | ----------------------- | ------------------------------------------------------------- | | Available with auth | Read issue content for deeper analysis (multi-repo detection) | | Not available / No auth | Use repository from URL directly, skip issue content analysis |

If gh available - Read issue content:

gh issue view $ISSUE_NUMBER --repo $ORG/$REPO --json title,body,labels

Then analyze issue content:

1. Read issue title and body
2. Identify product/component keywords mentioned
3. Determine if multiple repositories are involved

If gh not available - Use URL only:

Simply use the repository extracted from the Issue URL ($ORG/$REPO) and proceed to Phase 2. Skip multi-repository detection.

Multi-repository scenario examples:

| Issue Location | Issue Content Keywords | Actual Repositories Involved | | ----------------- | -------------------------------------------------- | ------------------------------------------------ | | media-kit | "Discuss Kit image upload triggers twice" | media-kit (uploader) + discuss-kit (caller) | | discuss-kit | "Image upload component onUploadSuccess exception" | discuss-kit + media-kit (component provider) | | blocklet-server | "DID Connect login failed" | blocklet-server + did-connect | | did-spaces | "PaymentKit payment callback issue" | did-spaces + paymentkit |

Decision logic:

• Repository where Issue is located is the primary repository (issue report location)
• Other products mentioned in Issue content are related repositories (may need to view simultaneously)

1.3 Multi-Repository Handling

If multiple repositories are identified:

1. Use AskUserQuestion to ask user:

• Option A: Clone only primary repository {primary repository name}
• Option B: Clone both primary and related repositories {primary repository name} + {related repository name}
• Option C: User specifies other repository

1. Record variables:

• PRIMARY_REPO: Primary repository (where issue is located)
• RELATED_REPOS: Related repository list (may be empty)

1. Execute subsequent Phases 2-6 for each selected repository

Match failure: Use AskUserQuestion to let user select or input complete GitHub path.

---

Phase 2: Repo Clone & Permission Check

2.1 Check Local Repository

REPO_PATH="$HOME/arcblock-repos/$REPO"
[ -d "$REPO_PATH" ] && cd "$REPO_PATH" && git fetch origin

2.2 Clone Repository

Clone to ~/arcblock-repos/$REPO (prefer SSH, fallback to HTTPS on failure).

2.3 Find Blocklet Project

find . -name "blocklet.yml" -o -name "blocklet.yaml" | grep -v node_modules

| Situation | Handling | | -------------- | -------------------------------------- | | Not found | Prompt this is not a blocklet project | | Found 1 | Auto-select | | Found multiple | Use

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ArcBlock
• Source: ArcBlock/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.