Skill Builder

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):

| Decision on the table | Read |

|---|---|

| Skill vs. agent vs. hook | plugin-entity-taxonomy.md |

| Use cases, trigger phrases, test cases | skill-building-guidance/use-case-planning.md |

| Directory name, file name, dependency prefix | skill-building-guidance/naming-conventions.md |

| The description field (four components, boundaries) | skill-building-guidance/skill-description-frontmatter.md, skill-building-guidance/skill-description-length.md |

| Which frontmatter fields to set | skill-building-guidance/skill-frontmatter-fields.md |

| Where content lives (body vs. references vs. scripts vs. assets) | skill-building-guidance/progressive-disclosure.md, skill-building-guidance/skill-reference-files.md |

| Step structure and workflow shape | skill-building-guidance/workflow-patterns.md, skill-building-guidance/writing-effective-instructions.md |

| allowed-tools, Bash permission granularity | skill-building-guidance/allowed-tools-bash-permissions.md, skill-building-guidance/allowed-tools-AskUserQuestion.md |

| Reading config / runtime data | skill-building-guidance/context-injection-commands.md, skill-building-guidance/dynamic-project-discovery.md |

| Running scripts | skill-building-guidance/script-execution-instructions.md |

| Dispatching agents from the skill | skill-building-guidance/agent-dispatch-namespacing.md, plus agent-building-guidelines/multi-agent-economics.md |

| Degraded environments (no git, missing tools) | skill-building-guidance/graceful-degradation.md, skill-building-guidance/optional-git-repositories.md |

| Frontmatter safety (angle brackets, YAML types) | skill-building-guidance/security-restrictions.md |

| Hardening fuzzy steps into deterministic ones | skill-building-guidance/hardening-fuzzy-vs-deterministic.md |

| Splitting or composing skills | skill-building-guidance/skill-decomposition.md, skill-building-guidance/skill-composition.md |

| Defining success and tests | skill-building-guidance/success-criteria-and-testing.md |

| New plugin needed (plugin.json, marketplace.json) | claude-marketplace-and-plugin-configuration/ and templates/ |

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.

• 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?

• 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?

• 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)?

• 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?

• 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:

• 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.

• 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.

• 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.

• 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.

Step 5: Write the Skill

Create the skill directory and write the files:

• Create {plugin}/skills/{skill-name}/ (use mkdir). The directory name is

the slash command and must match the frontmatter name.

• Write SKILL.md with:
• Frontmatter: name (matching the directory), the description settled in

the interview, allowed-tools, and any other settled fields. **Never put

AskUserQuestion in allowed-tools.** No XML angle brackets in any

frontmatter value.

• A body of numbered process steps following the chosen workflow pattern.

Be specific and actionable, embed reasoning in constraints

(Always/Never X BECAUSE Y), include error handling for tool-dependent

steps, and reference any bundled resource by exact path.

• Create references/, scripts/, or assets/ and their files only if a use

case needs them. Domain knowledge (templates, checklists, matrices) goes in

references/; deterministic operations go in scripts/; output-only files

go in assets/. Do not create empty or speculative folders.

• If the skill belongs in a brand-new plugin, create the plugin scaffold

(.claude-plugin/plugin.json, and a marketplace entry if the repo uses one)

per the claude-marketplace-and-plugin-configuration/ guidance and the

templates/.

Step 6: Full Guidance-Conformance Review

This is the review pass the skill commits to. Re-read each governing document

that applies to what you built and verify the finished files against it,

applying every fix directly. Do not summarize problems for the user without

fixing them. Cover at minimum:

• Entity fit (plugin-entity-taxonomy.md) — the skill is genuinely a

flowchartable process, not a judgment layer that should be an agent.

• Description (skill-description-frontmatter.md, skill-description-length.md)

— third person; covers what, when, boundary, and trigger breadth; weaves

trigger words into prose rather than appending a keyword list; names sibling

skills in boundary clauses; disambiguates in both directions (update the

sibling's description if a one-way gap exists); within 1024 characters.

• Naming (naming-conventions.md) — directory name matches name, is a

process/gerund name when the output is a plan or doc, carries a dependency

prefix when an external tool is required, no README.md in the skill folder,

SKILL.md cased exactly.

• Progressive disclosure (progressive-disclosure.md, skill-reference-files.md)

— body is process only and under 500 lines; domain knowledge is in

references/; scripts hold deterministic work; nothing the toolchain already

enforces is restated.

• Instruction quality (writing-effective-instructions.md, workflow-patterns.md)

— steps are specific and actionable; constraints embed reasoning; error

handling is present; human gates sit only at irreversible actions; the most

critical item in each list is placed last.

• Tools and safety (allowed-tools-bash-permissions.md,

allowed-tools-AskUserQuestion.md, security-restrictions.md) — Bash

permissions are scoped correctly with separate entries; AskUserQuestion is

absent from allowed-tools; no angle brackets or non-standard YAML in

frontmatter.

• Discovery and degradation (dynamic-project-discovery.md,

graceful-degradation.md, optional-git-repositories.md) — the skill

discovers project specifics dynamically rather than hardcoding them, and

degrades gracefully when a tool or git is absent, where relevant.

• Dispatch (agent-dispatch-namespacing.md) — if the skill dispatches

agents, every dispatch uses the qualified defining-plugin:agent-name, and

the agents actually exist in an installed plugin.

• Tests (success-criteria-and-testing.md) — each use case maps to a

triggering and functional test the user can run.

Apply the YAGNI discipline throughout: every step, reference file, tool

permission, and frontmatter field must earn its place against a real use case.

Cut anything added "for completeness" or "for future flexibility."

Step 7: Present and Hand Off

Summarize for the user:

• The files written (paths), and what each contains.
• The decisions settled by evidence versus by user input.
• The fixes the Step 6 review applied, citing the guidance document behind each.
• The triggering and functional tests derived from the use cases, so the user

can validate the skill against the model tier it targets.

Note that plugin entities rarely land in one pass: per

iterative-plugin-development.md, plan for 3-5 iterations. Ask whether the user

wants to iterate on specific steps or considers the skill ready to test.