Create Skill

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:

Example — injecting live context. In a skill body, write lines like:

• Current branch: !\git branch --show-current\
• Recent commits: !\git log --oneline -5\
• Changed files: !\git diff --name-only\

Then add directives like "Summarize this pull request..."

These commands run when the skill is invoked. The model sees only the output — no tool calls needed. Use this for infallible probes (git status, env vars, file trees, process output) where failure is rare and the output is informational. Do not use for commands that may fail or need exit-code branching — those require Bash tool calls so the model can handle errors.

Note: The backslashes above escape the backticks so this documentation

doesn't execute — in a real skill, write !\cmd\ without the backslashes.

Step 5 — Script opportunity scan

Read ${CLAUDE_PLUGIN_ROOT}/skills/create-skill/references/script-patterns.md and apply the five signal patterns to every workflow step in the skill being generated:

For each identified script candidate: 1. Choose the archetype from references/script-patterns.md (init/validate/transform/package/query) 2. If the interface is non-trivial, delegate to claude-skills:create-cli skill to design it 3. Scaffold the script in scripts/ using the Python template from references/script-patterns.md 4. Wire it into SKILL.md with: trigger condition, exact invocation, output interpretation

Wiring rule: A script reference must state when to invoke (trigger condition), how to invoke (exact command with flags), and what to do with the result (exit code handling, which output fields matter).

Step 6 — Check delegation

Scan for existing resources before finalizing:

Review available: skills, commands, agents, MCPs
For each workflow step, ask: "Do we already have this?"

Common delegation patterns:

• Git commits → Skill: claude-coding:commit

Always use fully qualified names:

• Skill: plugin-dev:hook-development (not just "hook-development")
• SlashCommand: /plugin-dev:create-plugin (not just "create-plugin")
• Task: subagent_type=plugin-dev:agent-creator

Step 7 — Validate

python3 ${CLAUDE_PLUGIN_ROOT}/skills/create-skill/scripts/validate_skill.py <skill-directory> --output json

Exit 0 = proceed to Phase 2. Exit 1 = parse the errors array; each entry has field, message, severity. Resolve all critical and major items before writing to disk.

Phase 2: Deliver

Output Paths

Write and Confirm

Before writing:

Writing to: [path]
This will [create new / overwrite existing] file.
Proceed?

Explain Your Choices

When presenting the generated skill/command to the user, briefly explain:

• What you set and why — "Added allowed-tools to scope Bash to git commands only, since the skill only needs git for commits"
• What you excluded and why — "hooks omitted (no validation needed), disable-model-invocation left unset (auto-triggering is appropriate)"
• Add more trigger phrases if routing misses expected inputs

Package for Distribution

Only when user explicitly requests a distributable file, run:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/create-skill/scripts/package_skill.py <skill-directory> [output-dir]

Exit 0 = .skill file created at output path. Exit 1 = validation failed; read stdout for details.

After Creation

Summarize what was created:

• Name and type
• Path
• How to invoke/trigger
• Suggested test scenario

Phase 3: Structural Lint

After writing the skill to disk, invoke the skill-lint agent to run a structural audit:

Use Task tool with subagent_type=claude-skills:skill-lint:
"Lint the skill at <path-to-skill-directory>. Auto-apply critical and major fixes, report
minor findings for user decision."

Wait for the agent to complete. If it auto-applied fixes, note them in the Phase 4 summary. If it reports minor findings, include them in the evaluation output for the user to decide.

Proceed to Phase 4 when the lint agent returns.

Phase 4: Evaluate

Score the generated skill/command:

Target: 9.0/10.0. If below, refine once addressing the weakest dimension, then deliver.

Before finalizing, load ${CLAUDE_PLUGIN_ROOT}/skills/create-skill/references/generation-standards.md and verify the validation checklist passes.

---

Execute phases sequentially.

Frontmatter Options & Patterns Reference

Authoritative source for skill/command frontmatter. Keep current with Claude Code releases — this file is the single source of truth used by create-skill. No live documentation fetch is performed; accuracy depends on this file being maintained.

Load before writing frontmatter in Phase 1, Step 2. Contains the full field catalog, description patterns, execution modifiers, tool selection framework, and progressive disclosure patterns.

---

Essential Frontmatter

Every skill needs these fields. Start here.

# Complete field catalog — most skills only need: name, description, allowed-tools
---
name: identifier                    # Required — unique skill identifier
description: >                      # How it's described/triggered (see patterns below)
  [See description patterns below]
allowed-tools:                      # Restrict available tools (see Tool Selection below)
  - Read
  - Grep
  - Bash(git:*)

# Lifecycle hooks (optional, scoped to this skill's lifetime)
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "scripts/validate-input.sh"
          timeout: 10
          statusMessage: "Validating..."
  PostToolUse:
    - hooks:
        - type: command
          command: "scripts/cleanup.sh"
  Stop:
    - hooks:
        - type: command
          command: "scripts/on-complete.sh"
          once: true                # Skills only: run once, then auto-remove

# Execution context
context: fork                       # Run in a subagent (isolates from conversation)
agent: Explore                      # Subagent type when context: fork (default: general-purpose)
effort: high                        # Override session effort: low | medium | high | max (max: Opus 4.6 only)
paths: "*.py,src/**/*.ts"           # Glob patterns limiting auto-activation to matching files
shell: bash                         # Shell for bang+backtick inline-command blocks: bash (default) or powershell

# Behavior modifiers
user-invocable: true                # Show in /command menu (default true)
disable-model-invocation: true      # Prevent programmatic invocation (commands only)
argument-hint: "[arg1] [arg2]"      # Document expected arguments; quote if value contains [...]
---

`argument-hint` quoting rule: Values containing [...] must be quoted ("[arg]"), because YAML treats unquoted [ as the start of a flow sequence. Values using only <...> do not need quoting.

Advanced Frontmatter

Use when needed — most skills don't require these.

# Lifecycle hooks (scoped to this skill's lifetime)
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "scripts/validate-input.sh"
          timeout: 10
          statusMessage: "Validating..."
  PostToolUse:
    - hooks:
        - type: command
          command: "scripts/cleanup.sh"
  Stop:
    - hooks:
        - type: command
          command: "scripts/on-complete.sh"
          once: true                # Skills only: run once, then auto-remove

# Execution context
context: fork                       # Run in a subagent (isolates from conversation)
agent: Explore                      # Subagent type when context: fork (default: general-purpose)
effort: high                        # Override session effort: low | medium | high | max (max: Opus 4.6 only)
paths: "*.py,src/**/*.ts"           # Glob patterns limiting auto-activation to matching files
shell: bash                         # Shell for bang+backtick inline-command blocks: bash (default) or powershell

# Behavior modifiers (commands)
disable-model-invocation: true      # Prevent programmatic invocation (commands only)

Hooks structure: Each hook event (PreToolUse, PostToolUse, Stop, SessionStart, etc.) accepts an array of entries. Each entry can have a matcher (filter by tool name) and a hooks array with handlers. Handler fields: type (command, http, prompt, agent), command, timeout (seconds), statusMessage (custom spinner text), once (skills only — run once then auto-remove). Hooks are scoped to the skill's lifetime and cleaned up when it finishes.

---

Description Patterns

For Skills (auto-triggered) — the two-layer model

Skill descriptions serve one purpose: helping the routing model decide when to trigger. They use a two-layer structure where a broad routing directive provides primary coverage and a few verbatim phrases anchor the intent.

Layer 1: Routing directive (primary coverage). A sentence at the end that tells the model to trigger broadly across an intent category. Format: "Make sure to use this skill whenever the user mentions [X, Y, Z] — even if they don't explicitly say '[skill name]'." X/Y/Z are intent categories and concept words (broad, generalizable), not verbatim query phrases. This is the main coverage mechanism — it catches the long tail of phrasings you can't anticipate.

Layer 2: Verbatim anchors (precision). 2–3 quoted phrases representing the exact words a user would type. These provide high-confidence matches for common cases. Derive them from real user language, not formalized paraphrases: "fix my skill" not "skill remediation". Cover the naive phrasing — what someone would say who has never heard of this skill.

The two layers are complementary, not interchangeable: verbatim phrases optimize for precision on known patterns; the routing directive optimizes for recall across unknown patterns.

Additional principles

• Third-person framing is a routing signal. "This skill should be used when..." reads as a condition to test. "Use this skill when..." reads as an instruction to execute. The routing model treats these differently.
• Include negative triggers for adjacent domains. Explicit exclusions sharpen the decision boundary. Add "Not for X" when the skill could plausibly false-trigger on a related domain.
• The description is always in context. Every session pays the token cost of every skill's description. Keep it dense — the routing directive eliminates the need for exhaustive trigger phrase lists.
• Keep descriptions under 150 tokens (200 absolute max). Anthropic's hard limit is 1024 characters (~250 tokens). Descriptions longer than 250 characters are truncated. The routing directive adds ~20-30 tokens — the budget accommodates it.
• Use `>` scalar, not `|`. Folded scalar (>) collapses newlines to spaces — correct for descriptions. Literal scalar (|) preserves newlines, which can break parsing.

# Correct — verbatim anchors, broad routing directive, negative trigger
description: >
  This skill should be used when the user asks to "create a hook"
  or "add lifecycle automation". Make sure to use this skill whenever
  the user mentions hook authoring, tool-event automation, or
  validation pipelines — even if they don't explicitly say "hook".
  Not for modifying existing hooks or debugging hook failures.

# Wrong — exhaustive trigger phrases, no routing directive
description: >
  This skill should be used when the user asks to "create a hook",
  "add validation", "implement lifecycle automation", "set up
  pre-tool hooks", "add post-tool cleanup", or "write hook scripts".

# Wrong — vague, no trigger phrases, not third-person
description: Provides guidance for hooks.

For Commands (user-invoked) — principles

• Verb-first, under 60 chars. The description appears as a single scannable line in the / menu — treat it as a menu label, not a sentence.
• Describe the action, not the tool. "Fix GitHub issue by number" orients by outcome. "GitHub issue fixer" orients by tool name. Users scan for what they want to accomplish.

description: Fix GitHub issue by number
description: Review code for security issues
description: Deploy to staging environment

---

Essential Field Reference

• `name` — Unique identifier. Required for all skills and commands.

• `description` — How the routing model decides when to trigger this skill, or the label shown in the / menu for commands. See Description Patterns below.

• `allowed-tools` — Restrict which tools the skill can use. Default is all tools. See Tool Selection below.

For hooks, context, effort, and paths — see Advanced Field Reference below.

• `shell` — Shell for inline !\cmd\ blocks and `! fenced blocks: bash (default) or powershell. Setting powershell runs inline shell commands via PowerShell on Windows. Requires CLAUDE_CODE_USE_POWERSHELL_TOOL=1 env var for inline bang-prefix commands to execute via PowerShell.

• `disable-model-invocation: true` — Commands only. Prevents Claude from auto-loading based on description. Has no effect on skills — use user-invocable: false instead.

• `user-invocable` — Whether the skill appears in the / command menu. Default true. Set to false for background-knowledge skills that should trigger automatically but not appear as slash commands.

• `argument-hint` — Shown in autocomplete when the user types the command. Documents expected arguments.

Advanced Field Reference

These fields add execution control, lifecycle hooks, and platform-specific behavior. Most skills don't need them.

• `hooks` — Run scripts at lifecycle events, scoped to this skill's lifetime. See the Advanced Frontmatter block above for the full structure (matcher, type, timeout, statusMessage, once).

• `context: fork` — Run the skill in an isolated subagent. The skill content becomes the subagent's prompt; it won't have access to conversation history. Use for task-type skills (deploy, generate, research) where isolation prevents accidental side effects. Pair with agent to choose the subagent type (Explore, Plan, general-purpose, or a custom agent from .claude/agents/).

• `effort` — Override session effort level for this skill. Options: low, medium, high, max (max is Opus 4.6 only). Use high/max for skills requiring deep reasoning; low for simple lookup skills.

• `paths` — Glob patterns (comma-separated or YAML list) limiting auto-activation. When set, Claude loads the skill automatically only when working with files matching the patterns. Use for language-specific or framework-specific skills.

• `shell` — Shell for inline !\cmd\ blocks and `! fenced blocks: bash (default) or powershell. Setting powershell runs inline shell commands via PowerShell on Windows. Requires CLAUDE_CODE_USE_POWERSHELL_TOOL=1 env var for inline bang-prefix commands to execute via PowerShell.

• `disable-model-invocation: true` — Commands only. Prevents Claude from auto-loading based on description. Has no effect on skills — use user-invocable: false instead for skills you want to hide from auto-triggering.

---

Tool Selection

Default generous, restrict only when needed. The principle: restrict tools that have destructive or side-effect potential, not tools that are read-only or purely generative.

YAML format: allowed-tools must be a YAML list — block sequence (- Tool) or flow sequence ([Tool, Tool]). Never comma-separated on one line (allowed-tools: Read, Glob, Edit) — YAML parses that as a single string, not a list.

---

Skill Content Lifecycle

When invoked, the rendered SKILL.md enters the conversation as a single message and stays for the rest of the session. Claude Code does not re-read the file on later turns — write guidance as standing instructions, not one-time steps.

Auto-compaction carries invoked skills forward within a token budget: the first 5,000 tokens of each skill are retained after compaction, and all recently invoked skills share a combined 25,000-token budget (filled most-recent-first). Skills exceeding 5,000 tokens lose their tail after compaction. Skills invoked long ago may be dropped entirely if the budget is exhausted. If a skill seems to stop influencing behavior, re-invoke it.

Design implications: keep SKILL.md under 500 lines. Front-load critical instructions within the first ~5,000 tokens. Move detailed reference material to separate files that are loaded on demand.

---

Progressive Disclosure

For complex skills, organize into subdirectories:

skill-name/
├── SKILL.md          # Core instructions (keep under 500 lines)
├── scripts/          # Executable code (Python/Bash)
├── references/       # Docs loaded into context as needed
├── examples/         # Working code examples users can copy directly
└── assets/           # Files used in output (templates, icons, fonts)

scripts/ — Deterministic, token-efficient. May be executed without loading into context. Use when the same code is rewritten repeatedly or reliability is critical.

references/ — Documentation Claude reads while working. Keeps SKILL.md lean. For files >100 lines, include a table of contents. Only load when needed.

examples/ — Working code examples: complete, runnable scripts, configuration files, template files, real-world usage examples. Users can copy and adapt these directly. Distinct from references (docs) and scripts (utilities).

assets/ — Files NOT loaded into context. Used in output: templates, images, fonts, boilerplate.

Pattern 1: High-level guide with references

# PDF Processing

## Quick start
Extract text with pdfplumber:
[code example]

## Advanced features
- **Form filling**: See references/forms.md
- **API reference**: See references/api.md

Claude loads references only when needed.

Pattern 2: Domain-specific organization

bigquery-skill/
├── SKILL.md (overview and navigation)
└── references/
    ├── finance.md (revenue, billing)
    ├── sales.md (pipeline, opportunities)
    └── product.md (API usage, features)

When user asks about sales, Claude only reads sales.md.

Pattern 3: Variant-based organization

cloud-deploy/
├── SKILL.md (workflow + provider selection)
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md

User chooses AWS → Claude only reads aws.md.

Generation Standards

Reference checklist and quality standards for evaluating generated skills and commands. Load during Phase 5 (Evaluate) before finalizing.

---

Degrees of Freedom

Match instruction specificity to the task's fragility and variability:

Quality Standards

Format Economy:

• Simple task → direct instruction, no sections
• Moderate task → light organization with headers
• Complex task → full semantic structure

Balance Flexibility with Precision:

• Loose enough for creative exploration
• Tight enough to prevent ambiguity

Remove ruthlessly: Filler phrases, obvious implications, redundant framing, excessive politeness

Validation Checklist

Before finalizing a skill or command:

Structure:

• [ ] SKILL.md file exists with valid YAML frontmatter
• [ ] Frontmatter has name and description fields
• [ ] Markdown body is present and substantial
• [ ] Referenced files actually exist

Description Quality:

• [ ] Uses third person ("This skill should be used when...")
• [ ] Includes specific trigger phrases users would say
• [ ] Trigger phrases derived from user's actual words, not formalized paraphrases
• [ ] Under 100 tokens (150 absolute max)
• [ ] Negative triggers present if adjacent skills could false-trigger
• [ ] Lists concrete scenarios ("create X", "configure Y")
• [ ] Not vague or generic

Content Quality:

• [ ] Body uses imperative/infinitive form, not second person
• [ ] Body is focused and lean (1,500–2,000 words ideal, <5k max)
• [ ] Detailed content moved to references/
• [ ] Examples are complete and working
• [ ] Scripts are executable and documented
• [ ] Script opportunities identified via five signal patterns (references/script-patterns.md)
• [ ] Script references in SKILL.md include trigger condition, invocation, output handling
• [ ] Consistency-critical steps are scripted, not left to LLM re-generation

Progressive Disclosure:

• [ ] Core concepts in SKILL.md
• [ ] Detailed docs in references/
• [ ] Working code in examples/
• [ ] Utilities in scripts/
• [ ] SKILL.md references these resources

Testing:

• [ ] Skill triggers on expected user queries
• [ ] Content is helpful for intended tasks
• [ ] No duplicated information across files
• [ ] References load when needed

Error Handling

Script & CLI Patterns Reference

Intelligence for recognizing when a workflow step should be a script, how to design it as a proper CLI, and how to wire it into a skill. Load before auditing Dimension 4 or scanning for script opportunities during generation.

---

Signal Patterns: When a Step Should Be a Script

A workflow step is a CLI candidate when any of the following are true. The more signals present, the stronger the case for scripting.

Signal 1 — Repeated Generation

The step produces the same structure with different parameters across invocations. Examples: scaffolding a directory tree, generating a frontmatter block, creating a boilerplate file from a template. If Claude is re-generating the same code on every invocation, a parameterized script produces it once and runs reliably thereafter.

Test: Would two different users invoking this skill with different inputs cause Claude to write nearly identical code blocks with just the variable parts swapped? → Script it.

Signal 2 — Unclear Tool Choice

The step needs to do something but no standard Claude tool (Read, Grep, Bash, Edit, etc.) covers it cleanly without combining multiple tools in a fragile sequence. Example: "validate frontmatter YAML and report structured errors" requires reading a file, parsing YAML, and applying rules — awkward as a tool sequence, natural as a script.

Test: Does the skill body describe a multi-step procedure that would be done the same way every time, using tools as primitives? → The procedure is a script waiting to be named.

Signal 3 — Rigid Input/Output Contract

The step takes a specific input shape (a file path, a name + target directory) and produces a specific output shape (a scaffolded directory, a JSON report, a validation result). Rigid contracts are the shape of good CLIs — the interface is clear enough to parameterize immediately.

Test: Can you write the --help text for this step right now, without ambiguity? If yes, it's a CLI. If the args feel unclear, it's still agentic reasoning.

Signal 4 — Dual-Use Potential

The step would be useful to run independently, outside the skill workflow. Example: a validation script is useful during skill creation, during repair, and as a standalone pre-commit check. A scaffolding script is useful both when the skill generates a new artifact and when a user wants to scaffold manually.

Test: Would a user want to run this from the terminal directly, without triggering the full skill? → Design it as a proper CLI from the start, not an internal helper.

Signal 5 — Consistency Critical

The step must produce identical output for identical inputs — not "similar" output, but bit-for-bit reproducible results. LLM generation has variance; scripts don't. File naming conventions, path construction, structural templates — anything where variance causes downstream breakage should be scripted.

Test: Would a subtle difference in output (different field order, different whitespace, slightly different file name) break something? → Deterministic script, not LLM generation.

---

CLI Design for Skill Context

A script in a skill directory is also a CLI. Design it to be invoked both by Claude during a workflow and by users from the terminal.

Interface Design

Positional arguments — use for required, ordered inputs where the meaning is unambiguous from context. Best for 1–2 inputs: init_skill.py <name> <target-dir>.

Named flags — use for optional inputs, boolean toggles, and anything where the label clarifies meaning: --model sonnet, --dry-run, --output json.

Flag for output format — always add --output [text|json] when the script produces structured data. Claude parses JSON efficiently; humans prefer text. Defaulting to text with --output json as the machine-readable mode covers both callers.

Stdin input — use when the script is meant to be piped to: cat file | script.py. Useful for transform scripts. Use sys.stdin.read() with a flag fallback for file paths.

Explicit help text — every script needs -h/--help output. This is documentation that Claude reads when deciding how to invoke the script, and that users see when running it manually. Include: what the script does, each argument/flag with type and default, and an example invocation.

Output Conventions

Stdout for result data — the primary output goes to stdout. Claude captures stdout.

Stderr for diagnostic messages — progress notes, warnings, verbose logging go to stderr. Claude ignores stderr by default; it doesn't pollute the captured result.

Exit codes — 0 for success, 1 for usage errors (wrong args), 2 for runtime errors (file not found, parse failure). Claude checks exit codes implicitly; a non-zero exit signals failure and stops the workflow.

Structured output for multi-field results — if the script returns more than one piece of data, output JSON on stdout. A script that returns {"valid": true, "errors": []} is easier for Claude to parse than "Validation passed with 0 errors."

Script Anatomy (Python template)

#!/usr/bin/env python3
"""
One-line description of what this script does.

Usage:
  script.py <required-arg> [--flag value]

Examples:
  script.py input.yaml --output json
"""

import argparse
import json
import sys

def main():
    parser = argparse.ArgumentParser(description=__doc__,
                                     formatter_class=argparse.RawDescriptionHelpFormatter)
    parser.add_argument("input", help="Description of required input")
    parser.add_argument("--output", choices=["text", "json"], default="text",
                        help="Output format (default: text)")
    parser.add_argument("--dry-run", action="store_true",
                        help="Show what would happen without making changes")
    args = parser.parse_args()

    # Core logic here
    result = process(args.input, dry_run=args.dry_run)

    if args.output == "json":
        print(json.dumps(result))
    else:
        print(format_text(result))

    sys.exit(0 if result["success"] else 1)

if __name__ == "__main__":
    main()

---

Common Script Archetypes

These archetypes cover most script candidates that appear in skill workflows.

Init — Scaffold a structure

Creates a directory tree or file set from a template. Takes a name and target path; produces the scaffolded output. Should be idempotent with a --force flag for overwriting, or fail fast on collision by default.

Canonical args: init.py <name> [target-dir] [--force] [--output json]

Validate — Check preconditions

Reads an artifact (file, directory, config), applies a rule set, and reports violations. Output should be structured (list of {field, message, severity} objects). Exit 0 on clean, exit 1 on violations. Never modifies anything.

Canonical args: validate.py <path> [--strict] [--output json]

Transform — Convert input to output

Takes structured input, applies a deterministic transformation, produces structured output. The purest CLI form: one input, one output, no side effects unless --write is passed. Use stdin/stdout for pipeline composability.

Canonical args: transform.py <input-path> [--output-path path] [--dry-run]

Package — Assemble an artifact

Collects files or content from multiple sources and assembles a distributable artifact (zip, tarball, manifest). Should validate inputs before assembling and report what was included. Dry-run support is valuable here.

Canonical args: package.py <source-dir> [output-dir] [--dry-run] [--output json]

Query — Read state, return structured result

Reads from a data source (DB, file, API) and returns structured data. Never writes. The primary consumer is Claude reading the output during a skill workflow, but users should be able to run it for inspection.

Canonical args: query.py [--filter key=value] [--limit N] [--output json]

---

Wiring Scripts into a Skill

A script that isn't referenced in SKILL.md is invisible to Claude.

In SKILL.md body, reference each script with: 1. When to invoke it (the trigger condition — which phase, what signals) 2. The exact invocation with relevant flags 3. How to interpret the output (what to do with exit codes, what fields matter)

Example reference pattern:

**Validate before proceeding:**

~/.claude/skills/skill-name/scripts/validate.py "$PATH" --output json

Exit 1 = validation failed; parse the `errors` array and report to user before
continuing. Exit 0 = proceed to Phase 3.

Avoid vague references like "run the validation script if needed" — Claude won't know which script or when "if needed" applies. State the trigger condition explicitly.

---

Delegation Pattern

When a skill workflow step is identified as a script candidate, delegate interface design to the create-cli skill rather than designing it ad-hoc. create-cli covers argument structure, help text, output formats, error messages, exit codes, and config/env precedence in depth.

Invocation pattern from within a skill workflow:

Skill: create-cli
Args: "<description of what the script does and what inputs it takes>"

The generated CLI spec can then be scaffolded into scripts/ and referenced from SKILL.md. This ensures the script is designed for both Claude invocation and direct user use from the start.