Command Creator Skill

A Claude Code skill for designing and building custom slash commands — reusable markdown-based workflows that extend Claude Code with project-specific automation invoked via /command-name.

When to Use This Skill

Choose this skill when:

• Creating reusable workflows that your team will invoke repeatedly
• Building project-specific automation (deploy, test, review patterns)
• Standardizing common development tasks across a team
• Wrapping complex multi-step processes into a single command
• Creating onboarding commands for new team members

Consider alternatives when:

• You need one-time scripts (use bash scripts directly)
• You need scheduled automation (use CI/CD or cron jobs)
• You need interactive UIs (use a custom CLI tool or web interface)

Quick Start

Copy
# Create a command directory
mkdir -p .claude/commands

# Create your first command
cat > .claude/commands/deploy.md << 'EOF'
---
description: Deploy the application to the specified environment
arguments:
  - name: environment
    description: Target environment (staging or production)
    required: true
---

# Deploy to $ARGUMENTS.environment

1. Run the test suite to verify all tests pass
2. Build the production bundle
3. Deploy to $ARGUMENTS.environment using the deploy script
4. Verify the deployment health check endpoint responds
5. Post deployment summary to the team Slack channel
EOF

Copy
# Example: /deploy staging
# The command file above will be expanded and Claude will execute each step

# More examples of command files:

# .claude/commands/review.md - Code review workflow
# .claude/commands/test.md - Run and analyze tests
# .claude/commands/db-migrate.md - Database migration steps
# .claude/commands/onboard.md - New developer setup guide

Core Concepts

Command Structure

Element	Purpose	Required
Frontmatter	YAML metadata (description, arguments)	Yes
Description	Shown in command list and help	Yes
Arguments	Dynamic inputs passed at invocation	Optional
Body	Markdown instructions Claude follows	Yes
Variables	$ARGUMENTS.name placeholders	Optional

Command Patterns

Copy
# Pattern 1: Simple automation
---
description: Run linter and fix issues
---
Run ESLint with --fix on all TypeScript files.
Report what was auto-fixed and what needs manual attention.

# Pattern 2: Parameterized workflow
---
description: Create a new feature module
arguments:
  - name: feature
    description: Name of the feature to scaffold
    required: true
  - name: type
    description: Module type (page, component, service)
    required: false
---
Create a new $ARGUMENTS.type for $ARGUMENTS.feature following
the project's existing patterns. Include tests and types.

# Pattern 3: Multi-step process
---
description: Prepare release candidate
arguments:
  - name: version
    description: Release version number
    required: true
---
1. Update version in package.json to $ARGUMENTS.version
2. Generate changelog from last release tag
3. Run full test suite
4. Create release branch release/$ARGUMENTS.version
5. Open draft PR to main with changelog as description

Configuration

Parameter	Type	Default	Description
description	string	—	Short description shown in command listing (required)
arguments[].name	string	—	Argument name used as $ARGUMENTS.name
arguments[].description	string	—	Help text for the argument
arguments[].required	boolean	false	Whether the argument must be provided
arguments[].default	string	—	Default value if argument not provided

Best Practices

1. Write commands as instructions, not code — commands are prompts that Claude interprets and executes; write clear step-by-step instructions in plain language rather than trying to script every detail.

2. Keep commands focused on a single workflow — a deploy command should deploy, not also run tests and generate docs; compose multiple commands for complex workflows rather than creating monolithic ones.

3. Use argument descriptions as documentation — the description field for each argument is shown to users when they invoke the command; make descriptions specific enough that users know exactly what to provide.

4. Test commands with edge cases — invoke your command with unusual inputs (empty strings, special characters, missing optional args) to ensure Claude handles them gracefully.

5. Store team commands in version control — commit .claude/commands/ to your repository so all team members have access and changes go through code review like any other code.

Common Issues

Command arguments aren't substituted — Make sure you use the exact syntax $ARGUMENTS.name (case-sensitive). The argument name in the YAML frontmatter must match the placeholder in the body exactly.

Command is too vague and Claude improvises — If Claude takes unexpected actions, make the command instructions more specific. Instead of "deploy the app," write "run npm run build then npm run deploy:staging and verify the health check at /api/health."

Command not appearing in command list — Commands must be in .claude/commands/ directory (not .claude/skills/ or other locations) and must have valid YAML frontmatter with at least a description field.