create-command

name	create-command
plugin	agent-scaffolders
description	Scaffolds a new slash command in an existing plugin. NOT for creating event-driven hooks (use `create-hook`) and NOT for standard skills (use `create-skill`).
allowed-tools	Bash, Read, Write

Dependencies

This skill requires Python 3.8+ and standard library only. No external packages needed.

To install this skill's dependencies:

pip-compile ./requirements.in
pip install -r ./requirements.txt

See ../../requirements.txt for the dependency lockfile (currently empty — standard library only).

---

Slash Command Designer

Slash commands are reusable Markdown prompts that Claude executes when invoked with /command-name. They provide consistency, efficiency, and shareability for common workflows. Commands can be simple prompts or powerful multi-step workflows using dynamic arguments, file references, bash execution, and integration with agents and skills.

Reference files for deep dives:

• references/frontmatter-reference.md -- full list of all frontmatter fields
• references/interactive-commands.md -- AskUserQuestion, conditional logic
• references/advanced-workflows.md -- multi-step, multi-component patterns
• references/plugin-features-reference.md -- ${CLAUDE_PLUGIN_ROOT}, bash execution syntax
• references/examples/simple-commands.md -- copy-ready simple command templates
• references/examples/plugin-commands.md -- copy-ready plugin command templates

---

The Most Important Rule

Commands are instructions FOR Claude, not messages TO the user.

When /command-name is invoked, the command body becomes Claude's instructions. Write what Claude should DO, not what the user will see.

# CORRECT -- tells Claude what to do:
Review this code for security vulnerabilities:
- SQL injection
- XSS attacks
- Authentication bypass
Provide specific line numbers and severity ratings.

# WRONG -- addresses the user, not Claude:
This command will review your code for security issues.
You will receive a report with vulnerability details.

---

Step 1: Understand the Use Case

Extract from context first. Ask only what is unclear.

Core questions:

1. What workflow should this automate? One command, one purpose.

2. Which command type fits?

   • Simple: Static prompt, no arguments, no bash -- just a great reusable instruction
   • Dynamic: Uses $ARGUMENTS, $1/$2 positional args, or file references (@$1)
   • Bash-powered: Inline !`` `` `` bash commands to gather dynamic context before Claude runs
   • Multi-component: Coordinates skills, agents, and scripts in a workflow

3. Where should it live?

   • .claude/skills/<name>/SKILL.md -- recommended for new work (supports supporting files, cross-agent portability, inline hooks). The directory name becomes the slash command.
   • .claude/commands/<name>.md -- flat file, still works, simpler but no supporting files. Note: confirmed macOS discovery bug (GitHub #13906) with .claude/commands/ in some Claude Code versions. Prefer skills/ or a local plugin for reliability.
   • ~/.claude/skills/<name>/SKILL.md -- personal commands available in all projects
   • plugin-name/skills/<name>/SKILL.md -- distributed with plugin, namespaced as /plugin-name:<name> -- always use the full namespaced form in agent files

4. Does it need arguments? Use $ARGUMENTS (all as one string) or $1, $2 (positional).

5. Does it need to read files? Use @file-path or @$1 for dynamic file args.

6. Tool restrictions needed? Set allowed-tools to restrict scope (e.g. Bash(git:*) not Bash(*)).

---

Step 2: Choose the Right Pattern

Pattern A: Simple static command

---
description: Review code for security vulnerabilities
allowed-tools: Read, Grep
---

Review the current file for security vulnerabilities including:
- SQL injection risks
- XSS attack vectors
- Authentication bypass
- Insecure data handling

Provide specific line numbers and severity (critical/high/medium/low).

Pattern B: Dynamic arguments with $ARGUMENTS

---
description: Fix GitHub issue by number
argument-hint: [issue-number]
---

Fix issue #$ARGUMENTS following our coding standards and writing tests for all changes.

Pattern C: Positional arguments $1, $2

---
description: Review PR with priority and assignee
argument-hint: [pr-number] [priority] [assignee]
---

Review pull request #$1 with $2 priority.
After review, assign to $3 for follow-up action.

Pattern D: File reference

---
description: Generate documentation for a source file
argument-hint: [source-file]
---

Generate comprehensive documentation for @$1 including:
- Function/class descriptions and parameter docs
- Return value descriptions with types
- Usage examples with edge cases

Pattern E: Bash context injection

---
description: Review code changes
allowed-tools: Read, Bash(git:*)
---

Files changed: !`git diff --name-only HEAD~1`
Current branch: !`git branch --show-current`

Review each changed file for:
1. Code quality and style consistency
2. Potential bugs or regressions
3. Test coverage gaps
4. Documentation needs

Provide specific feedback per file.

Pattern F: Plugin command with ${CLAUDE_PLUGIN_ROOT}

---
description: Run plugin analyzer on target file
argument-hint: [file-path]
allowed-tools: Bash(node:*), Read
---

Run analysis: !`node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js $1`

Load rules: @${CLAUDE_PLUGIN_ROOT}/config/rules.json

Review results and report findings by severity.

---

Step 3: Scaffold and Write

Default scaffold: skills/ directory (recommended)

# Project command (as skill directory)
mkdir -p .claude/skills/<name>
touch .claude/skills/<name>/SKILL.md
# optionally: mkdir -p .claude/skills/<name>/evals
# optionally: touch .claude/skills/<name>/acceptance-criteria.md

# Personal command
mkdir -p ~/.claude/skills/<name>
touch ~/.claude/skills/<name>/SKILL.md

# Plugin command (namespaced as /plugin-name:<name>)
mkdir -p plugin-name/skills/<name>
touch plugin-name/skills/<name>/SKILL.md

Simple mode: flat .md file (still supported)

mkdir -p .claude/commands
touch .claude/commands/<name>.md

Use for one-liner prompts with no supporting files. For anything more complex, prefer the skills/ directory so you can add references/, evals/, and inline hooks later.

YAML frontmatter complete reference

Field	Purpose	Default	Example
name	Required. Slash command name. Kebab-case.	—	name: deploy
description	Text in /help. Hard limit 1024 chars. Keep under 150 words.	—	description: Deploy to target env.
argument-hint	Autocomplete hint for arguments	—	argument-hint: "[env: dev|staging|prod]"
allowed-tools	Restrict tool access (least privilege)	All	allowed-tools: Read(*), Bash(git *)
disable-model-invocation	true = user-only, blocks auto-invoke	false	disable-model-invocation: true
user-invocable	false = background knowledge, not user-typed	true	user-invocable: false
model	Override model for this command	session default	model: claude-haiku-4-5-20251001
effort	Override effort level	medium	effort: low
maxTokens	Cap token budget for this command	model default	maxTokens: 4096
hooks	Inline hooks scoped to this skill's lifetime	—	see create-hook
isolation	Run in isolated git worktree	none	isolation: worktree

No frontmatter is needed for the simplest commands -- omit the --- block entirely.

Argument handling rules

• $ARGUMENTS -- all user-supplied text as one string (use for simple single-arg commands)
• $1, $2, $3 -- positional (use when multiple distinct args needed)
• Mix: $1 for first, $ARGUMENTS for "everything after"
• Always document with argument-hint and handle the missing-arg case in the prompt

Bash inline execution syntax

!`command`          -- executes, output injected before Claude processes
!`git diff HEAD~1`  -- inject git diff
!`cat package.json` -- inject file contents (alternative to @syntax)

Use allowed-tools: Bash(git:*) to scope permissions. See references/plugin-features-reference.md for full bash execution details and edge cases.

File references

@path/to/file.md      -- static file reference, Claude reads before processing
@$1                    -- dynamic file reference using first argument
@${CLAUDE_PLUGIN_ROOT}/templates/report.md  -- plugin-relative file

Argument validation pattern

---
argument-hint: [environment]
---

Validate: !`echo "$1" | grep -E "^(dev|staging|prod)$" && echo "valid" || echo "invalid"`

If $1 is a valid environment (dev/staging/prod):
  Deploy to $1 environment
Otherwise:
  Explain valid environments and show usage: /deploy [dev|staging|prod]

Multi-component workflow pattern (agent + skill + script)

---
description: Comprehensive review workflow
argument-hint: [file]
allowed-tools: Bash(node:*), Read
---

Target: @$1

Phase 1 - Static analysis:
!`node ${CLAUDE_PLUGIN_ROOT}/scripts/lint.js $1`

Phase 2 - Deep review:
Launch the code-reviewer agent for detailed analysis.

Phase 3 - Standards check:
Use the coding-standards skill for validation.

Phase 4 - Report:
Template: @${CLAUDE_PLUGIN_ROOT}/templates/review.md
Compile findings following the template structure.

---

Step 4: Organize Commands

Naming convention

• Use verb-noun: review-pr, fix-issue, deploy-staging
• Avoid generics: test, run, build (conflict-prone)
• Hyphens for multi-word, no underscores

Namespacing with subdirectories

commands/
├── ci/
│   ├── build.md        # /build (project:ci)
│   ├── test.md         # /test (project:ci)
│   └── lint.md
├── git/
│   ├── commit.md
│   └── review-pr.md
└── docs/
    └── generate.md

Use subdirectories when you have 15+ commands or clear logical categories.

Inline documentation

<!--
Usage: /deploy [staging|production] [version]
Requires: AWS credentials configured
Example: /deploy staging v1.2.3
-->

Deploy application to $1 environment using version $2...

---

Step 5: Validate

Checklist:

• Command body written as instructions TO Claude (not messages to user)
• name field present (required — without it the command silently fails to register)
• description clear, under 150 words, hard limit 1024 chars
• argument-hint documents all arguments
• allowed-tools restricts to only what's needed
• $ARGUMENTS used for single-arg commands; $1/$2 for multiple distinct args
• @file references use valid paths
• Bash commands scoped: Bash(git *) not Bash(*) where possible
• Plugin commands use ${CLAUDE_PLUGIN_ROOT} not hardcoded paths
• Plugin commands referenced from agents/skills use full namespaced form: /plugin-name:command
• Command is in skills/ directory (preferred) or commands/ (flat, simple only)

Test the command:

/command-name arg1 arg2

If the command isn't showing up, work through this in order:

[ ] 1. YAML syntax: open SKILL.md, check frontmatter manually.
        `---` markers must be on their own lines, no leading spaces.
[ ] 2. name field: must be present.
[ ] 3. Plugin namespace: if installed as plugin, use /plugin-name:command not /command.
[ ] 4. Scope: is it in ~/.claude/skills/ (always) or .claude/skills/ (this project only)?
[ ] 5. Budget: run /context -- are skills excluded? Fix: SLASH_COMMAND_TOOL_CHAR_BUDGET=200000
[ ] 6. Platform: macOS + .claude/commands/ has a known bug (#13906). Migrate to skills/.
[ ] 7. Reload: run /reload-plugins after editing.
[ ] 8. Health: run /doctor for failures.
[ ] 9. Verify: run /help -- does the command appear with correct namespace?

Run audit:

audit-plugin    -- validates full plugin structure including commands

---

Next Actions

• Refine: Run continuous-skill-optimizer to benchmark trigger optimization
• Extend: Add interactivity with AskUserQuestion -- see references/interactive-commands.md
• Distribute: Add to a plugin for team sharing -- see references/examples/plugin-commands.md
• Audit: Run audit-plugin to validate structure