Command Creator Agent Skill

Command Creator

This skill guides the creation of Claude Code slash commands - reusable workflows that can be invoked with /command-name in Claude Code conversations.

About 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. They're ideal for:

• Repetitive workflows (code review, PR submission, CI fixing)
• Multi-step processes that need consistency
• Agent delegation patterns
• Project-specific automation

When to Use This Skill

Invoke this skill when users:

• Ask to "create a command" or "make a slash command"
• Want to automate a repetitive workflow
• Need to document a consistent process for reuse
• Say "I keep doing X, can we make a command for it?"
• Want to create project-specific or global commands

Bundled Resources

This skill includes reference documentation for detailed guidance:

• patterns.md in this skill's references folder - Command patterns (workflow automation, iterative fixing, agent delegation, simple execution)
• examples.md in this skill's references folder - Real command examples with full source (submit-stack, ensure-ci, create-implementation-plan)
• best-practices.md in this skill's references folder - Quality checklist, common pitfalls, writing guidelines, template structure

Load these references as needed when creating commands to understand patterns, see examples, or ensure quality.

Safety Boundaries

• Do not create or overwrite commands outside the user-chosen project or global commands directory.
• Do not include destructive steps, hidden network calls, or irreversible operations unless the user asked for them explicitly.
• Do not assume a command should be global when the project directory is the safer default.
• Do not read unrelated files for context when the command can be built from the request and this skill's bundled guides.

Command Structure Overview

Every slash command is a markdown file with:

---
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]

Command Creation Workflow

Step 1: Determine Location

Auto-detect the appropriate location:

• Check git repository status: git rev-parse --is-inside-work-tree 2>/dev/null
• Default location:
• If in git repo → Project-level: .claude/commands/
• If not in git repo → Global: ~/.claude/commands/
• Allow user override:
• If user explicitly mentions "global" or "user-level" → Use ~/.claude/commands/
• If user explicitly mentions "project" or "project-level" → Use .claude/commands/

Report the chosen location to the user before proceeding.

Step 2: Show Command Patterns

Help the user understand different command types. Load patterns.md from this skill's references folder to see available patterns:

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

Ask the user: "Which pattern is closest to what you want to create?" This helps frame the conversation.

Step 3: Gather Command Information

Ask the user for key information:

A. Command Name and Purpose

Ask:

• "What should the command be called?" (for filename)
• "What does this command do?" (for description field)

Guidelines:

• Command names MUST be kebab-case (hyphens, NOT underscores)
• ✅ CORRECT: submit-stack, ensure-ci, create-from-plan
• ❌ WRONG: submit_stack, ensure_ci, create_from_plan
• File names match command names: my-command.md → invoked as /my-command
• Description should be concise, action-oriented (appears in /help output)

B. Arguments

Ask:

• "Does this command take any arguments?"
• "Are arguments required or optional?"
• "What should arguments represent?"

If command takes arguments:

• Add argument-hint: <placeholder> to frontmatter
• Use <angle-brackets> for required arguments
• Use [square-brackets] for optional arguments

C. Workflow Steps

Ask:

• "What are the specific steps this command should follow?"
• "What order should they happen in?"
• "What tools or commands should be used?"

Gather details about:

• Initial analysis or checks to perform
• Main actions to take
• How to handle results
• Success criteria
• Error handling approach

D. Tool Restrictions and Guidance

Ask:

• "Should this command use any specific agents or tools?"
• "Are there any tools or operations it should avoid?"
• "Should it read any specific files for context?"

Step 4: Generate Optimized Command

Create the command file with agent-ready instructions. Load best-practices.md from this skill's references folder for:

• Template structure
• Best practices for agent execution
• Writing style guidelines
• Quality checklist

Key principles:

• Use imperative/infinitive form (verb-first instructions)
• Be explicit and specific
• Include expected outcomes
• Provide concrete examples
• Define clear error handling

Step 5: Create the Command File

• Determine full file path:
• Project: .claude/commands/[command-name].md
• Global: ~/.claude/commands/[command-name].md

• Ensure directory exists:

   mkdir -p [directory-path]

• Write the command file using the Write tool

• Confirm with user:
• Report the file location
• Summarize what the command does
• Explain how to use it: /command-name [arguments]

Step 6: Test and Iterate (Optional)

If the user wants to test:

• Suggest testing: You can test this command by running: /command-name [arguments]
• Be ready to iterate based on feedback
• Update the file with improvements as needed

Quick Tips

For detailed guidance, load the bundled references:

• Load patterns.md from this skill's references folder when designing the command workflow
• Load examples.md from this skill's references folder to see how existing commands are structured
• Load best-practices.md from this skill's references folder before finalizing to ensure quality

Common patterns to remember:

• Use Bash tool for pytest, pyright, ruff, prettier, make, gt commands
• Use Task tool to invoke subagents for specialized tasks
• Check for specific files first (e.g., .PLAN.md) before proceeding
• Mark todos complete immediately, not in batches
• Include explicit error handling instructions
• Define clear success criteria

Summary

When creating a command:

• Detect location (project vs global)
• Show patterns to frame the conversation
• Gather information (name, purpose, arguments, steps, tools)
• Generate optimized command with agent-executable instructions
• Create file at appropriate location
• Confirm and iterate as needed

Focus on creating commands that agents can execute autonomously, with clear steps, explicit tool usage, and proper error handling.