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-setup or /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