Command Creator

A comprehensive skill for creating optimized, agent-executable slash commands in Claude Code. This skill guides you through the entire process of designing, implementing, and testing reusable workflow automation commands.

Table of Contents

• Overview
• When to Use This Skill
• What Are Slash Commands?
• Key Features
• How It Works
• Command Patterns
• Location Strategy
• Bundled Resources
• Usage Examples
• Best Practices
• Common Use Cases

---

Overview

The Command Creator skill helps you transform repetitive workflows into reusable slash commands that can be invoked with /command-name in Claude Code conversations. It provides expert guidance on command structure, agent optimization, and best practices to ensure your commands execute reliably and autonomously.

Purpose: Create high-quality, agent-executable slash commands with proper structure, clear instructions, and optimal tool usage patterns.

Target Users: Developers who want to:

• Automate repetitive workflows
• Document consistent processes for reuse
• Create project-specific or global automation
• Delegate complex tasks to specialized agents

---

When to Use This Skill

Invoke this skill when you need to:

• Create a new slash command from scratch
• Automate a workflow you find yourself repeating
• Document a multi-step process for consistent execution
• Convert manual procedures into automated commands
• Create project-specific commands for team workflows
• Build global commands for personal productivity

Trigger Phrases:

• "create a command"
• "make a slash command"
• "add a command"
• "I keep doing X, can we make a command for it?"
• "automate this workflow"
• "create a reusable command"

---

What Are Slash Commands?

Slash commands are markdown files stored in .claude/commands/ (project-level) or ~/.claude/commands/ (global/user-level) that get expanded into prompts when invoked.

Structure:

---
description: Brief description shown in /help (required)
argument-hint: <placeholder> (optional, if command takes arguments)
---

# Command Title

[Detailed instructions for the agent to execute autonomously]

Invocation:

/command-name [arguments]

Storage Locations:

• Project-level: .claude/commands/my-command.md (only available in this project)
• Global/User-level: ~/.claude/commands/my-command.md (available everywhere)

---

Key Features

1. Intelligent Location Detection

Automatically determines whether commands should be project-level or global based on:

• Current directory git repository status
• User explicit preferences
• Command scope and purpose

2. Pattern-Based Design

Guides you through proven command patterns:

• Workflow Automation: Multi-step processes with analysis, action, and reporting
• Iterative Fixing: Continuous improvement loops (run → parse → fix → repeat)
• Agent Delegation: Complex tasks broken into specialized agent work
• Simple Execution: Direct tool or script execution with arguments

3. Agent-Optimized Instructions

Creates commands that agents can execute autonomously with:

• Imperative/infinitive verb-first instructions
• Explicit tool usage specifications
• Clear success criteria
• Concrete error handling
• Expected outcomes defined

4. Quality Assurance

Includes comprehensive best practices for:

• Proper naming conventions (kebab-case enforced)
• Argument handling and hints
• Tool restriction guidelines
• Error recovery strategies
• Progress reporting patterns

5. Bundled Reference Documentation

Provides three comprehensive reference files:

• patterns.md: Command design patterns with detailed examples
• examples.md: Real-world command implementations
• best-practices.md: Quality checklist and writing guidelines

---

How It Works

The Command Creator follows a structured 6-step workflow:

Step 1: Determine Location

Auto-detection Logic:

1. Check if current directory is inside a git repository
2. Default to project-level (.claude/commands/) if in git repo
3. Default to global (~/.claude/commands/) if not in git repo
4. Allow user override for explicit location preference

User is informed of the chosen location before proceeding.

Step 2: Show Command Patterns

Present available command patterns to help frame the conversation:

• Workflow Automation: Analyze → Act → Report (e.g., submit PR stack)
• Iterative Fixing: Run → Parse → Fix → Repeat (e.g., ensure CI passes)
• Agent Delegation: Context → Delegate → Iterate (e.g., create implementation plan)
• Simple Execution: Run command with args (e.g., code review)

User selects the closest pattern to their needs.

Step 3: Gather Command Information

Interactive Q&A to collect:

A. Command Name and Purpose

• Command name (must be kebab-case: my-command, not my_command)
• Description for /help output
• Purpose and scope

B. Arguments

• Does it take arguments? (yes/no)
• Required or optional?
• Argument hint format (<required> or [optional])

C. Workflow Steps

• Specific steps in execution order
• Tools/commands to use
• Success criteria
• Error handling approach

D. Tool Restrictions

• Specific agents or tools to use
• Operations to avoid
• Context files to read

Step 4: Generate Optimized Command

Create agent-executable instructions using:

• Template structure from best-practices.md
• Imperative verb-first language
• Explicit tool specifications
• Clear expected outcomes
• Concrete examples where needed

Step 5: Create the Command File

1. Construct full file path (project or global)
2. Ensure directory exists (mkdir -p)
3. Write command file using Write tool
4. Confirm with user:
   • Report file location
   • Summarize command function
   • Explain invocation syntax

Step 6: Test and Iterate

1. Suggest testing the command
2. Wait for user feedback
3. Iterate and improve based on results
4. Update file with refinements

---

Command Patterns

1. Workflow Automation

Use Case: Multi-step processes requiring analysis, action, and reporting

Example: Submit PR stack

1. Analyze git history to identify commit stack
2. Create PRs for each commit with proper dependencies
3. Report created PRs with links and status

Key Characteristics:

• Sequential steps with dependencies
• Clear analysis phase before action
• Comprehensive final report

2. Iterative Fixing

Use Case: Continuous improvement until success criteria met

Example: Ensure CI passes

1. Run tests and capture output
2. Parse failures and errors
3. Fix identified issues
4. Repeat until all tests pass

Key Characteristics:

• Loop until success condition
• Parse errors to guide fixes
• Progress tracking across iterations

3. Agent Delegation

Use Case: Complex tasks requiring specialized agent expertise

Example: Create implementation plan

1. Gather context (requirements, codebase)
2. Delegate to subagent agent
3. Iterate on plan with user feedback
4. Save final plan to .PLAN.md

Key Characteristics:

• Use Task tool for specialized agents
• Pass relevant context to delegated agent
• Iterate on specialized agent output

4. Simple Execution

Use Case: Direct tool/script execution with arguments

Example: Code review

1. Run codex review on specified files
2. Present results to user

Key Characteristics:

• Minimal logic, direct execution
• Pass through arguments to underlying tool
• Quick feedback loop

---

Location Strategy

Project-Level Commands (.claude/commands/)

When to Use:

• Command is specific to this project's workflow
• Requires project-specific context or files
• Team members should share this command
• Automation tied to project structure

Examples:

• /submit-stack (project's PR submission workflow)
• /ensure-ci (project's test suite)
• /deploy-staging (project's deployment process)

Advantages:

• Version controlled with project
• Shared across team
• Project-specific customization

Global Commands (~/.claude/commands/)

When to Use:

• Command works across any project
• Personal productivity tool
• Generic workflow automation
• No project-specific dependencies

Examples:

• /codex-review (code review any files)
• /create-implementation-plan (generic planning)
• /git-cleanup (git maintenance anywhere)

Advantages:

• Available everywhere
• Personal customization
• Independent of project

---

Bundled Resources

This skill includes three comprehensive reference files in the references/ directory:

references/patterns.md

Purpose: Detailed command design patterns with implementation guidance

Contents:

• Pattern 1: Workflow Automation (Analyze → Act → Report)
• Pattern 2: Iterative Fixing (Run → Parse → Fix → Repeat)
• Pattern 3: Agent Delegation (Context → Delegate → Iterate)
• Pattern 4: Simple Execution (Run command with args)
• When to use each pattern
• Tool usage recommendations
• Real examples for each pattern

Load When: Designing the command workflow and choosing the right pattern

references/examples.md

Purpose: Real-world command implementations with full source code

Contents:

• /submit-stack: Submit PR stack from git history
• /ensure-ci: Iteratively fix CI failures
• /create-implementation-plan: Delegate to planner agent
• Full markdown source for each example
• Annotations explaining key decisions
• Best practices demonstrated in context

Load When: Need concrete examples of how to structure specific command types

references/best-practices.md

Purpose: Quality checklist and writing guidelines

Contents:

• Command template structure
• Agent-optimized writing style
• Common pitfalls to avoid
• Quality checklist before finalizing
• Tool restriction patterns
• Error handling strategies
• Naming conventions

Load When: Finalizing command to ensure quality and completeness

---

Usage Examples

Example 1: Create Project-Level CI Fixer

User Request: "I keep fixing CI failures manually. Can we make a command for this?"

Skill Flow:

1. Detects project-level (in git repo)
2. Suggests "Iterative Fixing" pattern
3. Gathers info:
   • Name: ensure-ci
   • Description: "Iteratively fix CI failures until all tests pass"
   • Arguments: None
   • Steps: Run tests → Parse failures → Fix issues → Repeat
4. Generates command with Bash tool for pytest
5. Creates .claude/commands/ensure-ci.md
6. User invokes: /ensure-ci

Example 2: Create Global Code Review Command

User Request: "Create a global command to review code with Codex"

Skill Flow:

1. Detects global (user requests "global")
2. Suggests "Simple Execution" pattern
3. Gathers info:
   • Name: codex-review
   • Description: "Review code files using Codex"
   • Arguments: <files> (required)
   • Steps: Run codex review → Present results
4. Generates command with codex skill invocation
5. Creates ~/.claude/commands/codex-review.md
6. User invokes: /codex-review src/app.py src/utils.py

Example 3: Create PR Submission Workflow

User Request: "Make a command that analyzes my commits and creates a PR stack"

Skill Flow:

1. Detects project-level (in git repo)
2. Suggests "Workflow Automation" pattern
3. Gathers info:
   • Name: submit-stack
   • Description: "Create PR stack from commit history"
   • Arguments: [base-branch] (optional, defaults to main)
   • Steps: Analyze commits → Create PRs → Report results
4. Generates command with git analysis and gh CLI
5. Creates .claude/commands/submit-stack.md
6. User invokes: /submit-stack or /submit-stack develop

---

Best Practices

Naming Conventions

MUST use kebab-case (hyphens, not underscores):

• Correct: submit-stack, ensure-ci, create-from-plan
• Wrong: submit_stack, ensure_ci, create_from_plan

Argument Hints

• Use <angle-brackets> for required arguments
• Use [square-brackets] for optional arguments
• Examples:
  • argument-hint: <file-path> (required)
  • argument-hint: [base-branch] (optional)
  • argument-hint: <command> [args...] (mixed)

Agent-Optimized Instructions

Write in imperative/infinitive form:

• Correct: "Run pytest to execute tests"
• Wrong: "You should run pytest to execute tests"

Be explicit about tools:

• Correct: "Use the Bash tool to run pytest tests/"
• Wrong: "Run the tests"

Define success criteria:

• Correct: "Continue until all tests pass (exit code 0)"
• Wrong: "Fix the tests"

Include error handling:

• Correct: "If pytest fails, parse the output to identify failing tests, then fix each one"
• Wrong: "Fix any test failures"

Tool Restrictions

Use Bash tool for:

• pytest, pyright, ruff, prettier
• make, npm, yarn
• gt (git-town commands)

Use Task tool for:

• Specialized agents (subagent, subagents)
• Long-running or complex delegated tasks

Avoid in commands:

• Interactive prompts (commands must be autonomous)
• User confirmation loops (unless explicit in pattern)
• Ambiguous instructions that require interpretation

---

Common Use Cases

Development Workflows

• Submit PRs: Analyze commits, create PR stack with dependencies
• Fix CI: Iteratively run tests, parse failures, fix issues
• Code Review: Run linters, formatters, static analysis
• Deploy: Build, test, deploy to staging/production

Project Automation

• Setup: Initialize project structure, install dependencies
• Documentation: Generate docs from code, update README
• Testing: Run full test suite with coverage reports
• Release: Bump version, create changelog, tag release

Personal Productivity

• Git Cleanup: Delete merged branches, prune remotes
• Codebase Analysis: Generate architecture diagrams, dependency graphs
• Refactoring: Apply consistent patterns across files
• Planning: Create implementation plans for features

Team Collaboration

• Onboarding: Setup development environment, clone repos
• Standards: Enforce code style, commit message format
• Knowledge: Document architectural decisions, add examples
• Review: Automated code review checks before human review

---

Summary

The Command Creator skill provides a comprehensive, guided workflow for creating high-quality slash commands in Claude Code. By following proven patterns, gathering detailed requirements, and generating agent-optimized instructions, it ensures your commands are:

• Reliable: Execute autonomously without manual intervention
• Maintainable: Clear structure and documentation
• Reusable: Available project-wide or globally
• Optimized: Use appropriate tools and agents for the task

Next Steps:

1. Identify a repetitive workflow you want to automate
2. Invoke the command-creator skill
3. Follow the guided workflow to create your command
4. Test and iterate based on results
5. Share with your team (project-level) or use personally (global)

Get Started:

/command-creator

Or simply say: "I want to create a command that [does something]"