Create Skill

Call EnterPlanMode immediately before doing anything else.

You are creating a new Claude Code skill for the Claude_Skills collection. Gather requirements, design the skill following every convention documented below, present the plan for approval, and — after user approval — generate the skill files, validate, and install.

ARGUMENTS: The user may provide a description of what the new skill should do (e.g., "security audit for C# codebases" or "API documentation generator"). If no argument is provided, ask the user what skill they want to create.

IMPORTANT: Always quote the user-supplied argument in double quotes when passing it to shell commands.

Skill Creation Reference

This section is the authoritative specification for creating Claude Code skills in this project. It documents every convention — both the rules defined in CLAUDE.md and the patterns observed across all existing skills. Use it as the single source of truth when designing and generating new skills.

Before designing the new skill, read CLAUDE.md at the project root to verify these rules are still current. If any rule below conflicts with CLAUDE.md, defer to CLAUDE.md.

R1: Frontmatter

Every SKILL.md must begin with YAML frontmatter between --- delimiters.

Required fields (enforced by lint.sh):

Standard fields (used by every existing skill):

Optional fields:

The model aliases are opus, sonnet, haiku, fable, inherit; the schema rejects full model IDs so nothing in the repo hardcodes a version. Body substitutions: $ARGUMENTS, $0/$1 (or $ARGUMENTS[N]), $<name>, \$ to escape a literal dollar, ${CLAUDE_SESSION_ID}, ${CLAUDE_EFFORT}, ${CLAUDE_SKILL_DIR}, ${CLAUDE_PROJECT_DIR}, and !`<command>` dynamic context injection (see CLAUDE.md).

R2: Tool Selection

Follow the minimal permissions principle — only request tools the skill actually needs.

Base set (every skill that uses plan mode includes these):

Read, Grep, Glob, Bash, EnterPlanMode, ExitPlanMode

Add Agent, Workflow only if the skill genuinely fans out to subagents (see R4 — default is NO subagents). They travel together: Workflow runs the default 3-agent orchestration, Agent backs the fallback when the Workflow tool is unavailable.

Add based on capability:

Decision tree:

• Does the skill only analyze/report? → Base set only (+ AskUserQuestion if it needs to clarify scope)
• Does the skill modify existing files after analysis? → Add Edit
• Does the skill create new files? → Add Write
• Does the skill need to look up external information? → Add WebSearch, WebFetch
• Does the execution phase loop through many independent units of work (multiple PRs, file edits, update groups)? → Add TaskCreate, TaskUpdate for live progress visibility
• Does the skill spawn long-running shell commands (slow test suites, deploys) where polling output makes sense? → Pair Bash (run_in_background: true) with Monitor
• Does the skill naturally chain into another /skill for follow-up work? → Add Skill

R3: Body Structure

The body follows this order after the frontmatter:

1. Opening instruction (always the first line):

   Call `EnterPlanMode` immediately before doing anything else.
   

2. Mission statement — 1-3 sentences describing what the skill does and its approach.

3. ARGUMENTS line (only if argument-hint is declared):

   **ARGUMENTS:** The user may provide an optional <description of what the argument can be>. If no argument is provided, <fallback behavior>.
   

4. IMPORTANT: Quoting (only if argument-hint is declared):

   **IMPORTANT:** Always quote the user-supplied argument in double quotes when passing it to shell commands.
   

5. --- separator

6. Steps — numbered ## Step N: <Title>, separated by --- horizontal rules.

Standard step flow (adapt as needed):

Not every skill needs all 4 steps. Analysis-only skills may have 3 steps. Skills with verification may have 5.

R4: Subagents (optional — default NO)

Default to NO subagents. Many useful skills work as a single linear workflow without delegating to parallel investigators. github-ship is the strongest example of this pattern in the collection — it's a deterministic state-detect → present-plan → execute flow with no agent fan-out, and it's all the better for it.

Decision gate. Before adding subagents, ask out loud:

"What three orthogonal dimensions does this skill analyze?"

If you can't name three independent lenses that genuinely benefit from parallel investigation, do not add subagents — put the work directly in the skill body. Three near-duplicate "agents" that all read the same files and produce overlapping findings is the failure mode the simplicity bias exists to prevent.

If the answer is yes — three genuinely orthogonal lenses (e.g., vet's correctness / security / performance / conventions split, or refactor's correctness-security / performance / structure split) — then proceed with the rest of this rule.

Orchestration (mandatory when using subagents): the default fan-out is a Workflow of exactly 3 read-only Explore agents in parallel, with the Agent tool as the fallback when the Workflow tool is unavailable. Declare both Agent and Workflow in allowed-tools. A skill body instructing the call is the documented opt-in the Workflow tool requires, so no ultra argument is needed for this default tier — but keep it to exactly three agents and a single round; anything heavier (verify panels, loop-until-dry, worktrees) belongs behind an explicit ultra tier (see CLAUDE.md → Opt-in orchestration tier).

Configuration on each path:

Workflow script:   agent(prompt, { agentType: 'Explore' })     // omit model — inherits the session model
Agent-tool fallback: subagent_type: "Explore", model: "opus"

• Explore agents are read-only — Edit and Write are denied at the agent level. This is the safety mechanism that prevents analysis agents from modifying the project, on both paths.
• Inside the Workflow script, omit model — each agent inherits the session model (Explore is capped at Opus on the Claude API), so an Opus session gets Opus agents automatically.
• On the Agent-tool fallback, model: "opus" pins the fan-out to the latest Opus even when a cheaper default subagent model is configured.
• Never use general-purpose agents during analysis phases.

Required IMPORTANT block (include verbatim in the analysis step):

**IMPORTANT:** All subagents MUST be launched with `agentType: 'Explore'` inside the `Workflow` script (omit `model` — each agent inherits the session model), or, on the `Agent`-tool fallback, with `subagent_type: "Explore"` and `model: "opus"` (resolves to the latest Claude Opus, the most capable model). The Explore agent is read-only by design (Edit and Write are denied at the agent level). This ensures no subagent can accidentally modify the project during analysis. The explicit `model: "opus"` on the `Agent` path pins the fan-out to the latest Opus even when a cheaper default subagent model is configured, so the analysis never silently runs on a smaller model. Never use general-purpose subagents in this skill.

Launch boilerplate (the script keeps each ### Agent N section as the single source of truth for its brief — never duplicate the checklists inside the script):

Run the analysis as a **`Workflow` of exactly 3 read-only Explore agents in parallel** — one per lens below. Call the `Workflow` tool with a script along these lines, substituting the context resolved in Step 1 and each agent's brief verbatim from its `### Agent N` section:

```js
export const meta = {
  name: '<skill-name>-analysis',
  description: 'Three-lens <domain> analysis: <lens 1>, <lens 2>, <lens 3>',
  phases: [{ title: 'Analyze' }],
}

const CONTEXT = `<the context items resolved in Step 1>`
const FORMAT = `<the "Each agent must return findings in this structured format" list below, plus the Looks Good requirement>`

const LENSES = [
  { key: '<lens-1-slug>', brief: `<Agent 1 brief, verbatim>` },
  { key: '<lens-2-slug>', brief: `<Agent 2 brief, verbatim>` },
  { key: '<lens-3-slug>', brief: `<Agent 3 brief, verbatim>` },
]

const reports = await parallel(LENSES.map(l => () =>
  agent(`Analyze the target through the ${l.key} lens. Read the FULL target files, not just snippets.\n${CONTEXT}\n\n${l.brief}\n\n${FORMAT}`,
    { label: `analyze:${l.key}`, phase: 'Analyze', agentType: 'Explore' })))

return { lenses: LENSES.map((l, i) => ({ key: l.key, report: reports[i] })) }
```

Wait for the Workflow's completion notification before continuing — never synthesize from partial results. A `null` report means that agent was skipped or failed; say so in the report header rather than silently dropping the lens.

**Fallback.** If the `Workflow` tool is not available in this session, launch the same three briefs as **3 Explore subagents in parallel** via the `Agent` tool (`subagent_type: "Explore"`, `model: "opus"`).

Provide each agent with:
- <context item 1>
- <context item 2>
- <context item 3>

Notes on the script: parallel() is correct here (not pipeline()) because the synthesis step needs all three reports together to deduplicate across lenses. When the finding shape is regular (a fixed set of fields per finding plus "Looks Good" callouts), replace FORMAT with a FINDINGS JSON Schema that mirrors the structured-format list and pass schema: FINDINGS on each agent() call — the harness then validates every return (vet, refactor, docstring-check, idiom-check are the references; copy vet's FINDINGS object and rename the fields). Keep FORMAT (text return) only for heterogeneous digests such as enhance's reconnaissance. lint.sh fails a body that embeds a script without declaring Workflow, and warns if the script never passes agentType: 'Explore'.

Agent naming: Use ### Agent N: <Title> as subheadings under the analysis step.

Full file reading instruction (include when agents analyze code):

**IMPORTANT:** Instruct each agent to read the **full target files** (not just snippets) so they understand the complete code structure, how functions relate to each other, and whether a proposed change would break callers or dependents.

Structured return format: Every agent must return findings in a defined format. Specify the exact fields for the skill's domain. Common fields:

• ID: agent-local identifier (e.g., X1, X2)
• File: exact file path and line number
• Title: short description (under 80 characters)
• Description / Rationale: why this matters
• Fix / Proposed change: concrete suggestion with code

Positive callouts: Require each agent to return 2-3 things the code does well that should NOT be changed. This prevents over-engineering and acknowledges good practices.

R5: Finding IDs

Each skill uses a unique single-letter prefix for its findings:

Choose a letter that represents the new skill's domain and is not already taken. IDs are sequential: [X1], [X2], [X3].

Format in reports: Always bold bracket notation — **[X1]** — followed by backtick file:line reference.

R6: Report Format

Every skill defines an explicit markdown template for its final output. Common elements:

Header line (pipe-separated bold stats):

**Scope**: <description> | **Findings**: <count breakdown>

Sections separated by --- horizontal rules.

Finding detail pattern:

**[X1]** `path/to/file.ext:42` — <Title>
<Description of the issue and why it matters>
**Fix:** <Concrete suggestion or code snippet>

Omit empty sections — if a category has no findings, don't include its heading.

R7: Plan Mode Flow

Every skill follows this bracket pattern:

EnterPlanMode          ← first instruction
  |
  [All analysis: scope resolution, agent launches, report synthesis]
  |
ExitPlanMode           ← after presenting report
  |
  Action offer question ← ask user what to do
  |
  [Execution: apply changes, verify results]

Plan mode is the boundary between read-only analysis and write operations. All file modifications happen AFTER ExitPlanMode and AFTER user approval.

ExitPlanMode placement: Call it after presenting the full report, before the action offer question:

After presenting the <report/plan>, call `ExitPlanMode`, then ask:

> **<Action question>?** (e.g., "<example 1>", "<example 2>")

R8: Action Offer

After exiting plan mode, ask the user what to do. The question must be:

• Bold formatted
• Include example responses in parentheses
• Reference the skill's finding IDs in examples

Pattern:

> **<Verb> <object>?** (e.g., "<example with finding IDs>", "<another example>")

Conditional skip: If the analysis found nothing actionable, skip the action offer and state that clearly.

R9: Argument Resolution Cascade

Skills that accept an argument (declare argument-hint) resolve it in a priority order. The standard cascade:

1. File path — test -f "<arg>"
2. Directory path — test -d "<arg>"
3. Code identifier (function/class name) — grep for it
4. Git ref (branch/tag) — git rev-parse --verify "<arg>"
5. Commit range — if argument contains ..
6. Natural language — interpret as description, search, confirm with user
7. Failure message — inform user with usage examples

Auto-detection fallback (when no argument given):

1. Staged changes:   git diff --cached --name-only --diff-filter=ACMR
2. Unstaged changes:  git diff --name-only --diff-filter=ACMR
3. Branch diff:      git diff "$default_branch"...HEAD --name-only --diff-filter=ACMR
4. Nothing found:    inform user and stop

Default branch detection snippet (used by all skills with auto-detect):

default_branch=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
[ -z "$default_branch" ] && git rev-parse --verify main >/dev/null 2>&1 && default_branch=main
[ -z "$default_branch" ] && git rev-parse --verify master >/dev/null 2>&1 && default_branch=master

Not every resolution step is needed for every skill. Include only the steps relevant to the skill's domain.

R10: Synthesis Rules

When combining findings from multiple agents, the synthesis step must follow these rules:

1. Deduplicate — merge findings from different agents that flag the same code
2. Prioritize — sort by severity/impact, highest first
3. Be specific — every finding must have a file path and line number
4. Be actionable — every finding must include a concrete fix or change
5. Omit empty sections — don't include headings for categories with no findings

R11: README Sections

Every skill's README.md must contain these sections in this order:

1. Title — # <Skill Name> followed by a one-line description that matches the SKILL.md description field verbatim.
2. What It Does — describe the workflow and phases. The intro sentence uses the canonical wording:
   • For step-numbered skills: "…, delivered in N steps:"
   • For phase-numbered skills: "Runs a strategic N-phase analysis…" or "Runs an N-phase audit…"
3. Requirements — model access, dependencies, prerequisites
4. Usage — how to invoke (e.g., /<skill-name> or /<skill-name> <argument>). Examples MUST use the skill's actual name in the slash command.
5. Example — a 1-line scenario, the exact invocation, and a faithful abbreviated transcript wrapped in <details><summary>Sample output</summary>…</details>. Use the skill's real format strings (verdict banners, finding-ID prefix, report headings) so users can recognize the output before they install. Avoid ## Usage-style slash-command lines that reference OTHER skills inside ## Usage (the linter scans Usage for cross-skill references); ## Example is exempt from that check by design. Keep the visible part under ~25 lines.
6. Configuration — table of frontmatter settings. Required rows: Model, Effort, Argument hint, Allowed tools. The Allowed tools row must list the SAME tools as the SKILL.md allowed-tools frontmatter (including EnterPlanMode/ExitPlanMode if they're there). The Argument hint row should mirror the SKILL.md argument-hint value, or say No for skills that take no argument.
7. Safety — bullet points with bold labels describing what the skill can and cannot do

The Safety section uses this pattern:

- **<Bold label>**: <description>

Common safety bullets:

• Read-only analysis: All analysis agents use the Explore subagent type, which cannot modify files — the Workflow spawns them with agentType: 'Explore', the Agent-tool fallback with subagent_type: "Explore"
• User approval gate: No code is modified until the user reviews and approves
• No commits or pushes: The skill never commits, pushes, or publishes

R12: Post-Execution Patterns

After applying changes:

• Test verification: If the project has a test runner, run it after changes and report results
• Rollback support: If tests fail, offer to revert (e.g., git stash pop or git checkout -- <files>)
• Change reporting: After each applied change, state what was done:

  > **[X1]** Applied: <description> (`file:line`)
  

• Summary: After all changes, summarize the total applied

R13: Project Integration

After creating a new skill, these project files must also be updated:

• Root README.md — add a row to the skills table:

  | [<name>](skills/<name>/) | <description> | Opus | xhigh |
  

  And add a usage example in the Quick Start section.

• CHANGELOG.md — add an entry under [Unreleased]:

  ### Added
  - `<name>` skill: <description>
  

• Validation — run ./lint.sh <name> to verify the skill passes all checks.

• Installation — run ./install.sh <name> to create the symlink from ~/.claude/skills/<name>.

Step 1: Gather Requirements

If an argument was provided, parse it as a description of the desired skill's purpose. Otherwise, ask the user what skill they want to create (an inline plain-text question is fine here — the answer is freeform).

Read the existing skills directory to check for name conflicts before suggesting one:

ls skills/

Then collect the structured requirements. Issue a single AskUserQuestion call with up to 4 batched questions (skip any that are already answered by the argument):

1. Argument behavior — single-select, options:

   • No argument (skill always runs the same way)
   • Optional argument (auto-detect when missing)
   • Required argument (skill stops if missing)

2. Capabilities needed — multi-select, options:

   • Modify existing files (adds Edit)
   • Create new files (adds Write)
   • Internet access (adds WebSearch, WebFetch)
   • Track multi-step progress (adds TaskCreate, TaskUpdate)
   • Hand off to another skill (adds Skill)
   • Background commands + streaming output (adds Monitor)

3. Subagent fan-out — single-select (per R4's decision gate), options:

   • No subagents — single linear flow (default; mirrors github-ship)
   • 3-agent Workflow — three orthogonal analysis lenses (read-only Explore agents, Agent-tool fallback; mirrors vet, refactor)

For the freeform requirements that don't fit multiple-choice (skill name, workflow design, output format, finding-ID letter), follow up with plain-text questions or batch them into a second AskUserQuestion call if structured options are appropriate. Specifically still gather:

• Name — suggest a name following the existing pattern (lowercase, hyphenated, concise). The name must be unique among existing skills.
• Workflow — what is the core workflow? If subagents were selected, what are the three orthogonal lenses?
• Output — what does the final report look like? What finding ID prefix should be used (per R5)?

State the gathered requirements clearly before proceeding.

Step 2: Design the Skill

Based on the requirements from Step 1, design the complete skill. Read 1-2 existing skills that are closest in nature to the new skill for structural inspiration.

Design decisions to make:

1. Allowed tools — assemble from the base set + capability additions per R2.

2. Argument resolution — which steps from the R9 cascade are relevant? Design the resolution logic.

3. Subagent structure — apply R4's decision gate first. If the skill does not have three orthogonal analysis lenses, skip subagents entirely and design a single linear workflow. Only if the decision gate passes (yes, three independent dimensions), design the 3 analysis agents that the Workflow script will run:

   • What dimension does each agent cover?
   • What specific checklist items does each agent evaluate?
   • What structured format does each agent return?
   • What positive callouts should each agent provide?

4. Finding IDs — choose an unused letter prefix per R5.

5. Report format — design the markdown template per R6:

   • What sections does the report have?
   • What table columns are needed?
   • What detail format for each finding?

6. Action offer — design the post-report question per R8:

   • What verb? (fix, apply, generate, implement)
   • What example responses?
   • What conditional skip logic?

7. Post-execution — what happens after changes are applied per R12?

Present the complete design as a structured summary before proceeding to Step 3.

Step 3: Present the Plan

Generate the full content of both files and present them for review:

1. SKILL.md — complete frontmatter + body following all conventions from the reference above
2. README.md — all 6 sections per R11

Also show the planned changes to: 3. Root README.md — the new skills table row and usage example 4. CHANGELOG.md — the new Unreleased entry

After presenting the full plan, call ExitPlanMode, then ask:

Ready to create this skill? (e.g., "yes", "change the name to X", "add Y to agent 2", "use a different finding prefix")

Step 4: Generate, Validate, and Install

After the user approves the plan, execute in this order:

1. Create the skill directory:

   mkdir -p skills/<name>
   

2. Write the SKILL.md using the Write tool.

3. Write the README.md using the Write tool.

4. Update root README.md using the Edit tool — add the skills table row and usage example.

5. Update CHANGELOG.md using the Edit tool — add the entry under [Unreleased].

6. Validate:

   ./lint.sh <name>
   

   If any check fails, fix the issue and re-run.

7. Validate all skills (no regressions):

   ./lint.sh
   

8. Install:

   ./install.sh <name>
   

9. Report success:

   Skill created and installed. /<name> is ready to use.

   Files created:

   • skills/<name>/SKILL.md
   • skills/<name>/README.md

   Files updated:

   • README.md (skills table)
   • CHANGELOG.md (Unreleased section)

   Run /<name> to try it out.