/create-skill

name: create-skill
description: >
  This skill should be used when the user asks to "create a skill" or "make a command".
  Make sure to use this skill whenever the user mentions skill creation, command authoring,
  slash commands, or building Claude extensions — even if they don't explicitly say
  "create-skill". Not for repairing or auditing existing skills — use repair-skill.
argument-hint: "[skill|command] [name] - or leave empty to interview"

Skill & Command Generator

Generate well-structured skills or slash commands. Both are markdown files with YAML frontmatter—they share the same structure but differ in how they're triggered and described.

Phase 0: Understand Requirements

Parse `$ARGUMENTS` for type hint. If `$ARGUMENTS` is empty or insufficient, use AskUserQuestion to gather requirements — users are often unclear on what type of artifact they need or what the best design is.

Use AskUserQuestion to collect: 1. **Primary objective** — What should this do? 2. **Trigger scenarios** — When should it activate? 3. **Inputs/outputs** — What does it receive and produce? 4. **Complexity** — Simple, standard, or complex? 5. **Execution needs** — Isolated context? Delegated to specialized agent? Proceed to Phase 1 when at minimum Objective and Trigger Scenarios are established. Remaining dimensions can be resolved during generation.

Phase 1: Generate

Apply these principles throughout generation: use imperative voice and terse phrasing because every token in a generated skill body costs budget on every invocation, and Claude extrapolates well from precise nudges. Prefer instruction over example — state the rule with its reasoning so it generalizes to every input.

**If creating a new skill directory (not editing an existing file):**

python3 ${CLAUDE_PLUGIN_ROOT}/skills/create-skill/scripts/init_skill.py <name> --path <dir> [--resources scripts,references,assets] [--examples]

Exit 0 = directory created, proceed to Step 1. Exit 1 = naming collision; ask user whether to overwrite or rename.

Step 1 — Choose type

• **Skills:** Trigger-rich, third-person description ("This skill should be used when..."); auto-triggered by routing
• **Commands:** Concise, verb-first description, under 60 chars; user-invoked via `/` menu

Step 2 — Write frontmatter

Read `${CLAUDE_PLUGIN_ROOT}/skills/create-skill/references/frontmatter-options.md` for the full field catalog, description patterns, tool selection framework, and execution modifiers.

**Description density rules:** Keep descriptions under 150 tokens (200 absolute max) — they load every session. Descriptions over 250 characters are truncated in the skill listing. Derive trigger phrases from the user's actual words in Phase 0, not paraphrases. See the token budget, pushy routing pattern, and trigger derivation principles in `frontmatter-options.md`.

**Intensional over extensional — apply to all generated content.** State the rule directly with its reasoning rather than listing examples that imply the rule. An intensional rule ("quoted phrases must be verbatim user speech *because* routing matches on literal tokens") generalizes to every input the skill will encounter. An extensional approach requires the reader to reverse-engineer the rule — two reasoning hops instead of one, covering only the shape of those specific examples. Since this skill generates instructions that will themselves guide further generation, the quality of reasoning propagates.

Step 3 — Validate description discoverability

Before writing the body, verify the description will route correctly. Mentally generate:

1. **3 should-trigger prompts** — realistic user messages that should activate this skill. Include at least one naive phrasing from a user who has never heard of the skill. 2. **3 should-NOT-trigger prompts** — messages in adjacent domains that are close but should not activate. These test whether the description is too broad.

Evaluate: does the description cover all should-trigger prompts? Would it plausibly reject the should-NOT-trigger prompts? If coverage is weak, revise the description — add missing trigger phrases, tighten language to exclude adjacent domains, or add a negative trigger ("Not for X").

This step catches routing misses before the rest of the skill is built. Proceed when description coverage is adequate.

Step 4 — Write body

**Construction rules:**

• State objective explicitly in first sentence
• Use imperative voice ("Analyze", "Generate", "Identify") — no first-person ("I will", "I am")
• Context only when necessary for understanding
• XML tags only for complex structured data
• No "When to Use This Skill" section — body loads only after triggering; routing guidance there is never read by the routing decision
• Avoid headers deeper than H3 — deep nesting signals content that belongs in `references/`, not `SKILL.md`
• Use bang-backtick syntax for dynamic context injection when real-time data (git status, file list, env vars) improves the skill without requiring a tool call
• **Preserve variable bindings when collapsing code blocks to prose.** Code blocks serve

two purposes: illustrating an operation and establishing workflow state. When a code block assigns variables (`BASE=...`, `BRANCH=...`) that later steps reference, collapsing it to prose without preserving the bindings leaves downstream `$VAR` references unbound. Add a "derive working variables" preamble that explicitly binds each variable in prose before the steps that use them

Both skills and commands follow the same body pattern:

# Name

Brief overview (1-2 sentences).

## Process
1. Step one (imperative voice)
2. Step two
3. Step three

**Dynamic Content:**

| Syntax | Purpose | |--------|---------| | `$ARGUMENTS` | All arguments as string | | `$1`, `$2`, `$3` | Positional arguments (shell-style quoting for multi-word values) | | `@path/file` | Load file contents | | `@$1` | Load file from argument | | Exclamati