ArcBlock Blocklet Getting Started
An interactive Q&A guide for developers who are new to ArcBlock's Blocklet ecosystem and don't know what questions to ask.
Core Philosophy
"Guide through questions, answer from skills."
This skill maintains a curated list of questions. When user selects a question, AI reads the relevant skill files in plugins/blocklet/skills/ to understand the context and provide accurate answers.
"If users knew what to ask, they wouldn't need this skill."
Users who know their questions can ask AI directly. This skill is for those who need guided discovery.
Workflow
Phase 0: Language Selection
First, use AskUserQuestion to determine the user's preferred language:
Which language do you prefer? / 请选择您的语言 / 言語を選択してください
Options:
A. English
B. 中文 (Chinese)
C. 日本語 (Japanese)
After user selects a language, ALL subsequent communication must be in that language.
Phase 1: Present Questions (Loop)
Use AskUserQuestion to present questions.
Due to UI constraints (max 4 options), present 3 questions + 1 special option:
- 3 questions from different categories (maximize user choice)
- "Start my first environment setup" - Redirect to
/blocklet-dev-setupor/blocklet-server-dev-setup
After answering each question, return to Phase 1 and present the next set of questions (pick different ones).
Question Catalog
Questions are organized by category. When presenting questions, pick 3 from different categories to give variety. Track which questions have been asked to avoid repetition.
Category: Getting Started (GS)
| ID | Question | Answer Source |
|---|---|---|
| GS-1 | What's the difference between developing a Blocklet vs developing Blocklet Server? | Read blocklet-dev-setup/SKILL.md and blocklet-server-dev-setup/SKILL.md, compare their purposes |
| GS-2 | Which skill should I use to start development? | Analyze user's goal, recommend blocklet-dev-setup or blocklet-server-dev-setup |
| GS-3 | What is the complete development workflow from setup to PR? | Read blocklet-dev-setup/SKILL.md Phase 1-7, blocklet-pr/SKILL.md |
| GS-4 | What prerequisites do I need before starting? | Read blocklet-dev-setup/SKILL.md Phase 0 and Phase 3 |
| GS-5 | How do I know if my environment is ready? | Read blocklet-dev-setup/SKILL.md Phase 3 (Prerequisites Check) |
Category: Convention Directories (CD)
| ID | Question | Answer Source |
|---|---|---|
| CD-1 | Why do we use convention directories like ~/arcblock-repos/? | Read blocklet-dev-setup/SKILL.md Convention Directories section |
| CD-2 | What are all the convention directories and their purposes? | Read blocklet-dev-setup/SKILL.md Convention Directories table |
| CD-3 | What happens if I don't follow the convention directories? | Explain: AI cannot auto-discover repos, cross-project analysis fails |
| CD-4 | How do I migrate my existing repos to convention directories? | Provide migration commands (move or symlink) |
| CD-5 | Where should I put my Blocklet Server data? | Explain ~/blocklet-server-data/ vs ~/blocklet-server-dev-data/ |
Category: Server Modes (SM)
| ID | Question | Answer Source |
|---|---|---|
| SM-1 | What's the difference between blocklet server, source development, and blocklet dev? |
Read blocklet-dev-setup/SKILL.md Phase 4, blocklet-server-dev-setup/SKILL.md |
| SM-2 | When should I use blocklet server start vs source development? |
Explain: CLI for blocklet apps, source for Server core changes |
| SM-3 | Can I run CLI Server and Source Server at the same time? | No, they use same ports. Read blocklet-dev-setup/SKILL.md Phase 4.0 |
| SM-4 | What is bn-dev and when do I use it? |
Read blocklet-dev-setup/SKILL.md Phase 4.1.1 |
| SM-5 | How do I switch between production and source development mode? | Read blocklet-dev-setup/SKILL.md Phase 4.1 |
Category: tmux Process Management (TM)
| ID | Question | Answer Source |
|---|---|---|
| TM-1 | Why do we use tmux to manage blocklet dev processes? | Explain: AI can read logs via tmux capture-pane, monitor without blocking |
| TM-2 | How do I see what tmux sessions are running? | Command: tmux ls |
| TM-3 | How do I attach to a tmux session to see output? | Command: tmux attach -t {session-name} |
| TM-4 | How do I exit tmux without stopping the process? | Key: Ctrl+B, then D |
| TM-5 | How do I scroll up to see old output in tmux? | Key: Ctrl+B, [, then arrow keys, q to exit |
| TM-6 | How do I switch between windows in a tmux session? | Key: Ctrl+B, n (next) / p (previous) / 0-9 (specific) |
| TM-7 | How do I stop a blocklet dev process? | Command: tmux kill-session -t blocklet-dev-{repo} |
| TM-8 | What's the tmux session naming convention? | blocklet-dev-{repo} for apps, blocklet for Server source |
Category: Repository & Branch (RB)
| ID | Question | Answer Source |
|---|---|---|
| RB-1 | How does AI find and clone repositories automatically? | Read blocklet-dev-setup/SKILL.md Phase 1 and Repository Search section |
| RB-2 | What inputs can I provide to start development? | GitHub Issue URL, Blocklet URL, repo name, problem description |
| RB-3 | How does AI determine which branch to use? | Read blocklet-branch/SKILL.md |
| RB-4 | How does AI create feature branches? | Read blocklet-branch/SKILL.md branch naming conventions |
| RB-5 | What are the GitHub organizations for ArcBlock projects? | ArcBlock (core), blocklet (apps), AIGNE-io (AI framework) |
Category: Development Workflow (DW)
| ID | Question | Answer Source |
|---|---|---|
| DW-1 | How do I start developing a specific blocklet? | Read blocklet-dev-setup/SKILL.md Phase 1-6 |
| DW-2 | How do I access my blocklet after starting dev server? | Read blocklet-dev-setup/SKILL.md Phase 6.1.2 (parse URLs from output) |
| DW-3 | What's the difference between Server Admin and Service Admin URLs? | /.well-known/server/admin vs /.well-known/service/admin |
| DW-4 | How do I create commits following conventions? | Use /commit skill |
| DW-5 | How do I create a PR after development? | Use /blocklet-pr skill, requires gh CLI |
| DW-6 | What checks run before PR creation? | Read blocklet-pr/SKILL.md (lint, tests, version bump) |
Category: Troubleshooting (TS)
| ID | Question | Answer Source |
|---|---|---|
| TS-1 | Why can't I access *.did.abtnet.io or *.ip.abtnet.io domains? | DNS issue, set DNS to 8.8.8.8. Read blocklet-dev-setup/SKILL.md Error Handling |
| TS-2 | Why does Blocklet Server fail to start with "worker_connections NaN"? | Set ulimit -n 65536. Read blocklet-dev-setup/SKILL.md Phase 3.6 |
| TS-3 | Why do I get EACCES error on port 80/443? | No permission for privileged ports, use 8080/8443. Read Phase 3.7 |
| TS-4 | Why does blocklet dev fail with "Blocklet Server is not running"? | Start Server first. Read blocklet-dev-setup/SKILL.md Phase 4 |
| TS-5 | How do I check Blocklet Server logs? | PM2_HOME=~/.arcblock/abtnode pm2 logs abt-node-daemon --lines 100 |
| TS-6 | How do I completely stop all blocklet development processes? | Read blocklet-dev-setup/SKILL.md "Stop Blocklet Dev Process" section |
Category: Advanced Topics (AT)
| ID | Question | Answer Source |
|---|---|---|
| AT-1 | How do I analyze a Blocklet URL to find its source repository? | Use /blocklet-url-analyzer skill |
| AT-2 | How do I handle multi-repository issues? | Read blocklet-dev-setup/SKILL.md Phase 1.3 |
| AT-3 | How do I create a new release/version of my blocklet? | Use /blocklet-updater skill |
| AT-4 | What is first-time wallet binding and why is it required? | Read blocklet-dev-setup/SKILL.md Phase 4.5 |
| AT-5 | How do I convert an existing project to a blocklet? | Use /blocklet-converter skill |
How to Answer Questions
When user selects a question:
- Read the Answer Source - Load the referenced skill file(s) from
plugins/blocklet/skills/ - Extract relevant information - Find the specific section mentioned
- Provide a clear, concise answer - Explain in user's selected language
- Include practical examples - Commands, code snippets when relevant
- Return to Phase 1 - Present next set of questions
Presenting Questions
Default: Show 3 Questions + 1 Special Option
Pick 3 questions from different categories, plus 1 special option (max 4 total):
What would you like to know?
A. What's the difference between developing a Blocklet vs developing Blocklet Server?
B. Why do we use convention directories like ~/arcblock-repos/?
C. Why can't I access *.did.abtnet.io domains?
D. Start my first environment setup (ready to begin development)
After answering a question, pick 3 different questions for the next round.
When User Selects "Start My First Environment Setup"
Use AskUserQuestion to determine development target:
What do you want to develop?
A. Blocklet Application (Recommended)
- Examples: payment-kit, media-kit, discuss-kit, your own blocklet
- Applications that run ON Blocklet Server
B. Blocklet Server Core
- The Server runtime itself
- Contributing to Blocklet Server core functionality
| User Choice | Action |
|---|---|
| Blocklet Application | Redirect to /blocklet-dev-setup skill |
| Blocklet Server Core | Redirect to /blocklet-server-dev-setup skill |
Error Handling
| Situation | Handling |
|---|---|
| User asks question not in catalog | Try to answer from skill files, or add to catalog for future |
| Referenced skill file not found | Inform user, provide general guidance |
| User wants to start developing | Redirect to /blocklet-dev-setup or /blocklet-server-dev-setup |
| User provides Issue URL or Blocklet URL | Redirect to /blocklet-dev-setup directly |