create-skill

What this skill does

## Critical Rules

- ALWAYS use AskUserQuestion for decisions — never ask in plain text
- ALWAYS read shared knowledge base from `${CLAUDE_PLUGIN_ROOT}/shared/` before generating
- ALWAYS follow templates from `${CLAUDE_PLUGIN_ROOT}/shared/templates/`
- ALWAYS write contract.md, spec.md, and learnings.md to {skill-dir}/docs/ before generating skill artifacts
- Generated SKILL.md files must be <=500 lines with progressive disclosure
- Descriptions must be third-person with trigger phrases and negative cases
- Agent model assignments must be right-sized:
  - opus (`claude-opus-4-7`): complex generation, multi-step reasoning
  - sonnet (`claude-sonnet-4-6`): research, analysis, moderate tasks
  - haiku (`claude-haiku-4-5-20251001`): scaffolding, validation, simple writes
- For progress tracking use `TaskCreate`/`TaskUpdate` — never recommend `TodoWrite` (deprecated, disabled by default v2.1.142+)
- For hooks, prefer the `if` permission-rule filter over runtime stdin parsing; pick the lightest handler type that fits (`command` for deterministic checks, `prompt`+haiku for soft policy, `mcp_tool` for delegated checks)
- Embed a checkpoint warning in any generated skill that uses Bash to modify files — see `${CLAUDE_PLUGIN_ROOT}/shared/checkpointing.md`
- Prefer `userConfig` in `plugin.json` for any install-time prompt; reserve `$XDG_CONFIG_HOME` env-file pattern for existing external config

## Step 1 — Intake & Analysis

Accept the brain dump from `$ARGUMENTS` or from the conversation context (if invoked from `forge-skill` command or by the user directly describing what they want).

Spawn the `skill-forge:intake-analyst` agent via the Agent tool, passing:

- The full brain dump text
- The current working directory path

The agent returns a structured classification containing:

- Skill type: `command-only` | `skill-only` | `command+skill` | `multi-skill-plugin`
- Workflow pattern (one of the 5 canonical types)
- Primitives needed
- Agent needs (count, roles, model assignments)
- Complexity estimate
- Similar/conflicting existing skills
- Retrospective recommendation: `full` | `lightweight` | `none`

Store this classification — it drives all subsequent steps.

## Step 2 — Target + Name Selection

Use AskUserQuestion with the following options:

> Where should this skill be installed?
>
> 1. **Project skill** — `.claude/skills/` in the current working directory (available only in this project)
> 2. **Global skill** — `~/.claude/skills/` (available in all projects)
> 3. **Marketplace plugin** (Recommended) — published to a personal plugin marketplace repo

Include this context in the description:

> **Important limitations of project/global skills:**
>
> - No slash commands (`/command`) — commands only work in plugins
> - No custom agents — agent definitions require plugin.json
> - No hooks — hooks require `hooks/hooks.json` in a plugin directory
> - No shared files across skills — plugins provide `${CLAUDE_PLUGIN_ROOT}` for shared resources
>
> If the intake analysis identified commands, agents, hooks, or shared references, marketplace is the only viable target.

Based on selection:

- **Project** or **Global**: generate skill directory only (SKILL.md + `references/` subdirectory if needed). If the intake analysis requires commands, agents, or hooks, warn that these components will be omitted and recommend switching to marketplace.
- **Marketplace**: use AskUserQuestion to ask for the absolute path to the marketplace repo root (e.g. `~/Code/me/claude-plugins`). Store this as `$MARKETPLACE_ROOT`.

After target selection, present the skill name via AskUserQuestion:

> **Proposed skill name:** `{kebab-case-name-from-intake}`
>
> This name determines the skill directory path and all internal references.
>
> 1. Confirm this name
> 2. Use a different name (provide your preferred name)

Derive the skill name from the intake classification (converted to kebab-case). The user confirms or adjusts.

Establish the skill directory path now:

- **Project**: `{cwd}/.claude/skills/{skill-name}/`
- **Global**: `~/.claude/skills/{skill-name}/`
- **Marketplace**: `{$MARKETPLACE_ROOT}/plugins/{skill-name}/`

Store this as `$SKILL_DIR` — the spec and all artifacts write here.

## Step 3 — Spec Formation Loop

Score the current understanding across 5 dimensions (0-20 each):

| Dimension            | What it measures                           |
| -------------------- | ------------------------------------------ |
| Trigger Clarity      | Are the trigger phrases unambiguous?       |
| Workflow Definition  | Is the step-by-step process clear?         |
| Tool Requirements    | Are all needed tools identified?           |
| Output Specification | Is the expected output well-defined?       |
| Scope Boundaries     | Are in-scope and out-of-scope cases clear? |

**Threshold: >=90 / 100 to proceed.**

If below threshold:

1. Identify which dimensions are under-scored
2. Use AskUserQuestion to ask 2-4 targeted clarifying questions per round
3. Re-score after each round
4. Loop until >=90

### Codebase Research (during this loop)

If the target location already contains skills or related code, spawn the `skill-forge:skill-researcher` agent (Sonnet) during this loop, passing:

- The target installation path
- The intake classification from Step 1

Run the researcher while gathering clarifications so its findings inform the spec. If the target is empty or greenfield, skip the researcher.

### Spec Generation (when >=90)

Read templates from `${CLAUDE_PLUGIN_ROOT}/shared/templates/`:

- `contract-template.md`
- `spec-template.md`

Read relevant knowledge base docs from `${CLAUDE_PLUGIN_ROOT}/shared/`:

- `skill-anatomy.md` — structure rules (including the single-file plugin auto-loading pattern)
- `description-engineering.md` — description writing
- `anti-patterns.md` — what to avoid
- `agent-design.md` — agent definitions (modern frontmatter: `effort`, `maxTurns`, `isolation`)
- `workflow-patterns.md` — workflow structure
- `primitives-guide.md` — tool usage (`Task*`, `Monitor`, `LSP`, modern built-ins)
- `local-config-pattern.md` — if intake flagged config needs (compare against `userConfig`)
- `checkpointing.md` — when to embed Bash/checkpoint warnings in the generated skill

Write the following files to `{$SKILL_DIR}/docs/`:

1. **contract.md** — Design intent: problem statement, goals, success criteria, scope boundaries, design decisions. Follow `contract-template.md`.

2. **spec.md** — Execution plan containing:
   - Component manifest (every file to create with purpose and estimated size)
   - Skill architecture (workflow pattern, agent interactions, data flow)
   - Per-component details (for each file: sections, key decisions, dependencies)
   - Execution plan with phases and parallelization strategy
   - Retrospective configuration (based on intake analyst's recommendation: full/lightweight/none)
   - Validation strategy (structural checks, anti-pattern targets, build verification)

   Follow `spec-template.md`.

3. **learnings.md** — Start with a header explaining its purpose. The file begins empty and accumulates observations over time from retrospective runs.

### Spec Approval

Present the spec for approval via AskUserQuestion:

> **Spec is ready for review.**
>
> The contract and spec have been written to `{$SKILL_DIR}/docs/`.
> Review the spec's component manifest and execution plan.
>
> 1. **Approved** — proceed to generation
> 2. **Needs changes** — I'll edit the documents and re-present
> 3. **Missing scope** — the spec doesn't cover something important
> 4. **Start over** — discard and restart from intake

Handle responses:

- **Approved**: proceed to Step 4.
- **Needs changes**: use the Edit tool to update contract.md and/or spec.md based on user feedback. Re-present for approval. Loop until approved.
- **Missing scope**: ask targeted questions via AskUserQuestion, update the spec, re-present.
- **Start over**: discard the docs directory and return to Step 1.

This si