command-skill-creator

Command Skill Creator

Create command-type skills - imperative prompts that guide Claude through phased execution of multi-step workflows. These are /slash-commands users invoke explicitly, not passive reference material.

Command skills live in project-level .claude/skills/<name>/SKILL.md and are invoked as /name [arguments].

When to use this vs skill-creator

• This skill: Commands that DO things - deploy, commit, migrate, sync, release, scaffold. Side effects, approval gates, phased execution.
• skill-creator: Knowledge that INFORMS Claude - coding standards, API references, framework guides. No side effects, auto-triggered by context.

Creation Workflow

Step 1: Understand Intent

Establish what the command automates. Ask (or extract from conversation context):

• What does this command do? What are the major phases?
• Which actions have side effects? (commits, deploys, file mutations, external APIs)
• Does it take arguments? What kind?
• Does it operate across multiple repos/projects?
• Are there approval gates needed before irreversible actions?
• What model complexity is needed? (most commands work with default; complex multi-phase reasoning may need opus)

If the user says "turn this into a command," extract the workflow from conversation history - tools used, sequence, corrections made.

Step 2: Design Frontmatter

Choose fields based on the command's nature. See the frontmatter reference table below.

Minimum viable frontmatter:

---
name: my-command
description: What it does and when to use it
disable-model-invocation: true
---

The reason disable-model-invocation: true is the default for command skills: commands have side effects by definition. If it had no side effects, it would be a knowledge skill instead. Setting this to true ensures the command only runs when the user explicitly invokes it, preventing Claude from autonomously deploying, committing, or mutating state.

Add more fields based on characteristics:

• Takes arguments → argument-hint: "[arg-name]"
• Needs strong reasoning → model: opus
• Should restrict tools → allowed-tools: Read, Bash(specific-cmd *)
• Self-contained exploration → context: fork + agent: Explore

Step 3: Structure Phases

Break the command into numbered phases with markdown headers (##). Claude follows numbered sequences with headers reliably - dense paragraphs get lost.

Common phase progression:

1. Pre-flight - validate preconditions, read config, check state
2. Research/Discovery - gather info for decisions (parallelize with subagents when possible)
3. Present/Approve - show recommendations, wait for explicit user approval
4. Execute - make the changes
5. Verify - smoke tests, health checks
6. Summary - report outcomes

Not every command needs all phases. A simple formatter might just be execute + verify.

Step 4: Add Safety

For each phase with side effects:

• Approval gate: "STOP and wait for user approval before proceeding."
• Error handling: "If X fails, stop and show the error. Do NOT proceed to Phase N."
• Rollback path: How to undo if something goes wrong
• Verification: Check that each action succeeded before moving on

These aren't bureaucracy - they prevent the command from autonomously deploying broken code or committing garbage. A 2-second approval pause costs nothing compared to rolling back a bad deploy.

Step 5: Write the SKILL.md

Generate the complete skill file. Keep it under 200 lines - command skills are prompts, not documentation. If the command needs extensive reference material, use supporting files.

Always start with the argument guard:

The target is: $ARGUMENTS

If no argument was provided, ask the user for one and stop.

Then: rules section, phases, summary template.

Step 6: Audit

Run through every item on the audit checklist below. Fix failures before finalizing. Present the audit results to the user.

Step 7: Place

Save the skill to the target project:

<project>/.claude/skills/<command-name>/SKILL.md

If supporting files are needed, they go alongside SKILL.md.

Frontmatter Reference

| Field | Type | Default | When to Use | |-------|------|---------|-------------| | name | string | dir name | Always. Lowercase, hyphens, max 64 chars | | description | string | required | Action-oriented: what it does + when to trigger | | model | string | inherit | Complex reasoning: opus. Cost savings: haiku | | disable-model-invocation | bool | false | Always true for command skills (they have side effects) | | argument-hint | string | none | If command takes args: [service-name], [model-id] | | allowed-tools | string | all | Restrict: Read, Bash(npm *), mcp__github__* | | context | string | inline | fork for isolated subagent (read-only exploration) | | agent | string | general | With context: fork: Explore, Plan | | user-invocable | bool | true | false hides from menu (background knowledge only) |

$ARGUMENTS

$ARGUMENTS is replaced with the user's full argument string. Positional access via $0, $1, or $ARGUMENTS[N] (0-based).

/deploy twitter staging
# $ARGUMENTS = "twitter staging", $0 = "twitter", $1 = "staging"

Don't over-specify argument parsing. Trust Claude to understand natural language - describe what you expect and let Claude validate, rather than writing brittle format parsers.

Path Variables

Never hardcode absolute paths. Use:

• ${CLAUDE_PROJECT_DIR} - project root
• ${CLAUDE_SKILL_DIR} - skill's own directory (for bundled scripts)
• Relative paths from repo root

Design Patterns

See [references/design-patterns.md](references/design-patterns.md) for detailed patterns with full examples. Quick reference:

| Scenario | Pattern | |----------|---------| | One action, no approval needed | Simple Task | | Multiple steps, some irreversible | Phased Workflow with Approval Gate | | Need info from multiple sources | Parallel Research + Sequential Implementation | | Modifying another project | Cross-Repo with Adaptive Discovery | | Command exceeds 200 lines | Progressive Disclosure with supporting files |

Anti-Patterns

Watch for these when reviewing command skills:

• Hardcoded paths: /Users/someone/... → use ${CLAUDE_PROJECT_DIR} or relative
• Missing safety: no disable-model-invocation on commands with side effects
• Over-specification: complex argument parsers instead of natural language
• No checkpoints: making changes without showing what will happen first
• Blind edits: modifying files without reading them
• Silent failures: no error handling or status reporting
• Context ignorance: not reading CLAUDE.md, existing conventions, or config files
• Monolithic prompt: 500+ line SKILL.md instead of using supporting files

Audit Checklist

Every command skill must pass before finalizing:

1. disable-model-invocation: true if any side effects exist
2. argument-hint present if command takes arguments
3. No hardcoded absolute paths
4. Adaptive discovery (grep/glob) for cross-repo file references
5. Guard clause for missing $ARGUMENTS
6. Approval gate before destructive/irreversible operations
7. Clear outcome reporting (succeeded, failed, next steps)
8. SKILL.md under 200 lines (supporting files for overflow)
9. Explicit error handling ("if X fails, stop and show error")
10. ${CLAUDE_PROJECT_DIR} or relative paths, never absolute
11. Reads files before editing (no blind modifications)
12. Reads target project's CLAUDE.md for cross-repo operations