Skill Builder

Project Context

• personal config directory: !bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh" 2>/dev/null || echo "$HOME/.claude"
• project .han/config.md: !cat .han/config.md 2>/dev/null || echo ""

As your first action, use the Read tool on .han/config.md inside the personal config directory path above. A read that returns no file is no personal configuration: continue silently. When that file or the project .han/config.md probe supplies content, apply it per config-rule.md, which governs precedence between the two files, relative-path resolution, and what to do with a file that reads but cannot be used.

Guidance Location

The authoritative skill-authoring guidance ships in this plugin. Read the specific document a decision needs, when that decision is on the table — never read them all up front, because that defeats progressive disclosure and burns context on guidance the current skill does not touch.

• Plugin-building guidance root: ${CLAUDE_PLUGIN_ROOT}/skills/guidance/references/
• Skill-specific guidance: ${CLAUDE_PLUGIN_ROOT}/skills/guidance/references/skill-building-guidance/

Map from decision to governing document (read just-in-time):

Operating Principles

• Interview relentlessly, but explore first. Interview the user relentlessly about every aspect of the skill until you reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. If a question can be answered by exploring the repository — the target plugin's existing skills, sibling descriptions, plugin.json, conventions, the guidance documents above — explore instead of asking. Only surface questions that genuinely require the user's judgment.
• Ask one question at a time. Never batch questions. Settle one decision, let its answer resolve dependent decisions, then ask the next. Later answers routinely make earlier questions moot.
• Recommend, then ask. For every question surfaced to the user, provide a recommended answer with rationale grounded in evidence (existing skills, conventions, the guidance, the user's stated goal). The user can accept, amend, or redirect.
• Apply guidance as you go, then verify at the end. Consult the governing document when a decision is on the table (Step 4), and run a full guidance-conformance pass over the finished files at the end (Step 6). The interview gets each decision approximately right; the review pass makes the artifact correct.

Build a Skill

Step 1: Capture the Request and Confirm It Is a Skill

Read the user's argument and the conversation to extract what the skill should do. If the request is too thin to start (for example, just "build a skill"), ask the user for one or two sentences on what the skill should accomplish and what triggers it — nothing else yet.

Confirm the entity type before anything else. Read ${CLAUDE_PLUGIN_ROOT}/skills/guidance/references/plugin-entity-taxonomy.md and apply its decision heuristic. A skill is a deterministic, flowchartable process ("Can I flowchart every path?" → skill). If the work is really contextual judgment with no fixed flowchart, it is an agent — stop and recommend agent-builder. If it fires automatically on an event, it is a hook. If the request bundles a deterministic process and a judgment layer, recommend building them separately and composing them. Only proceed once a skill is the right entity.

Step 2: Discover Before Asking

Locate the target plugin and learn its conventions before asking the user anything beyond the framing. Use Glob, Grep, and find to gather:

• The target plugin directory and its .claude-plugin/plugin.json (name, description, version). If the user has not said which plugin, infer candidates from the repository and confirm the target in Step 4.
• Sibling skills in that plugin ({plugin}/skills/*/SKILL.md) — their descriptions, frontmatter, step structure, and the trigger space they already own. New descriptions must disambiguate against these siblings in both directions.
• CLAUDE.md, AGENTS.md, and any project-discovery.md — repository conventions, the documentation root, and how skills are catalogued.
• Whether the skill needs an external tool (gh, jq, an MCP server). External dependencies drive the directory-name prefix and a description mention.

Record what was found (file paths) and what was not. A missing convention is itself a finding that shapes the skill.

Step 3: Build the Design Tree

Enumerate the decisions the skill needs, in dependency order. Resolve foundational decisions before dependent ones; never ask a dependent question before its parent is settled.

1. Foundational — Which plugin owns it? What are the 2-3 concrete use cases (trigger phrase, workflow, tools, domain knowledge) per use-case-planning.md? What artifact or outcome does each use case produce?
2. Identity — What is the directory name (which becomes the slash command)? Does it follow the gerund/process-name and dependency-prefix rules? What does the description say across all four components (what, when, boundary, breadth), and how does it disambiguate against siblings in both directions?
3. Workflow — Which workflow pattern fits (sequential, iterative, context-aware, domain-specific, or a combination)? What are the numbered steps? Where do human gates belong (before irreversible or outward-facing actions only)?
4. Capabilities — What allowed-tools does each step need, at the right Bash granularity? Does the skill dispatch agents (and are they available in this plugin)? Does it run scripts? Does it read runtime config via context injection?
5. Layout — What belongs in the SKILL.md body (process), in references/ (templates, checklists, domain knowledge), in scripts/ (deterministic operations), and in assets/ (output files)? What other frontmatter fields apply (argument-hint, arguments, model, paths)?

Keep each node a concrete decision with a candidate answer. Do not pre-fill the tree with content the user has not confirmed.

Step 4: Interview Loop — One Branch at a Time

For each decision in dependency order:

1. Try to resolve it from evidence. Re-check the target plugin, sibling skills, conventions, and the governing guidance document for this decision (see the map above). If the evidence answers it, record the decision with its evidence and move on — do not ask.
2. If evidence is insufficient, draft a recommended answer grounded in the guidance and the evidence available. Read the governing document first so the recommendation is correct, not improvised.
3. Surface one question to the user, with the recommendation, the rationale, and the alternatives. State what changes depending on the answer. Wait for the answer before asking anything else.
4. Descend. Once a decision is settled, re-evaluate which dependent decisions the new answer resolves, and continue.

Keep the interview moving — do not stall on questions the evidence can answer, and do not batch.