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