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

| Field | Rule | |-------|------| | name | Must match the directory name exactly (e.g., my-skill for skills/my-skill/) | | description | One-line summary, verb-first ("Scans...", "Audits...", "Performs..."), ending with a period. Treat this as the marketing copy — it's what shows up in /help and the root README. | | allowed-tools | Comma-separated list of tools the skill may use |

Standard fields (used by every existing skill):

| Field | Value | Note | |-------|-------|------| | model | opus | Resolves to the latest Claude Opus, the most capable model | | effort | max | Maximum reasoning depth |

Optional fields:

| Field | Default | When to use | |-------|---------|-------------| | argument-hint | (none) | Set when the skill accepts an argument. Value is the autocomplete display string (e.g., [target] or [path \| identifier]). The README's Argument hint row must mirror this. Replaces the legacy repo-internal takes-arg field, which Claude Code never recognized. | | arguments | (none) | Optional named positional arguments for $name substitution in the body. With arguments: [target], the body can reference $target to inline the first argument. | | when_to_use | (none) | Additional trigger-phrase guidance for auto-invocation. Useful when description alone would mismatch user requests. | | paths | (none) | Glob patterns that auto-activate the skill when working with matching files (e.g., ["**/*.test.*"] for a testing skill). | | disable-model-invocation | false | Controls whether other models/skills may auto-invoke this skill via discovery/matching. Set true to keep the skill strictly user-triggered (the user must type / themselves). This does NOT prevent the skill from launching subagents via the Agent tool. Rarely needed — only enhance uses this in the current collection, to avoid being matched as a generic "improve the project" trigger. | | user-invocable | true | Set false to hide the skill from the / menu (background-knowledge skills only Claude should invoke). The inverse of disable-model-invocation. | | context | (none) | Set to fork to run the skill in a forked subagent context. The skill body becomes the subagent's prompt. | | agent | general-purpose | When context: fork is set, picks the subagent type (Explore, Plan, general-purpose, or any custom agent in .claude/agents/). |

---

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 only if the skill genuinely fans out to subagents (see R4 — default is NO subagents).

Add based on capability:

| Capability needed | Add these tools | |-------------------|----------------| | Launch parallel analysis subagents | Agent (only if R4's decision gate passes) | | Modify existing files | Edit | | Create new files | Write | | Internet access (web search, API lookups) | WebSearch, WebFetch | | Ask the user questions during execution | AskUserQuestion | | Track progress through a long multi-step execution phase | TaskCreate, TaskUpdate (optionally TaskList) | | Stream output from a long-running background process | Monitor (paired with Bash using run_in_background) | | Hand off to or invoke another installed skill | Skill | | Schedule recurring or one-off future runs | CronCreate, CronList, CronDelete (or ScheduleWakeup for in-conversation waits) | | Read symbol references / definitions via the language server | LSP |

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

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

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

`` **ARGUMENTS:** The user may provide an optional . If no argument is provided, . ``

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

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

1. --- separator

1. Steps — numbered ## Step N: , separated by --- horizontal rules.

Standard step flow (adapt as needed):

| Step | Purpose | Pattern | |------|---------|---------| | Step 1 | Resolve scope | Parse argument via resolution cascade, auto-detect from git, gather project context | | Step 2 | Parallel analysis | Launch 3 Explore subagents, each covering a distinct dimension | | Step 3 | Synthesize report | Deduplicate, prioritize, format structured report. Call ExitPlanMode, ask action question | | Step 4 | Execute | Apply changes after user approval, verify results |

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.

Configuration (mandatory when using subagents):

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.
• model: "opus" overrides the Explore agent's default (Haiku) to use the latest Opus, the most capable model, ensuring thorough deep analysis.
• Never use subagent_type: "general-purpose" during analysis phases.

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

**IMPORTANT:** All subagents MUST be launched 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 model override to Opus is required because Explore defaults to Haiku, which lacks the depth needed for this skill's thorough analysis. Never use general-purpose subagents in this skill.

Launch boilerplate:

Launch **3 Explore subagents in parallel** (`subagent_type: "Explore"`, `model: "opus"`).

Provide each agent with:
- 
- 
- 

Agent naming: Use ### Agent N: 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:

| Existing | Prefix | Meaning | |----------|--------|---------| | vet | C, W, S | Critical, Warning, Suggestion | | test-gen | T | Test | | diagnose | H | Hypothesis | | refactor | R | Refactoring |

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**:  | **Findings**: 

Sections separated by --- horizontal rules.

Finding detail pattern:

**[X1]** `path/to/file.ext:42` — 

**Fix:** 

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 , call `ExitPlanMode`, then ask:

> **?** (e.g., "", "")

---

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:

> ** ?** (e.g., "", "")

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 ""
2. Directory path — test -d ""
3. Code identifier (function/class name) — grep for it
4. Git ref (branch/tag) — git rev-parse --verify ""
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 — # 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…"

1. Requirements — model access, dependencies, prerequisites
2. Usage — how to invoke (e.g., / or / ). Examples MUST use the skill's actual name in the slash command.
3. Example — a 1-line scenario, the exact invocation, and a faithful abbreviated transcript wrapped in Sample output…. 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.
4. 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.
5. Safety — bullet points with bold labels describing what the skill can and cannot do

The Safety section uses this pattern:

- ****:

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [thijsvos](https://github.com/thijsvos)
- **Source:** [thijsvos/Claude_Skills](https://github.com/thijsvos/Claude_Skills)
- **License:** MIT
- **Homepage:** https://github.com/thijsvos/Claude_Skills#readme

Install and usage instructions live in the source repository linked above.