command-authoring

Reference Files

Detailed command authoring guidance:

• command-design-patterns.md - Four design patterns with complete examples and when to use each
• command-creation-process.md - Step-by-step command creation workflow (7 steps)
• command-examples.md - Real command examples with analysis and best practices

---

About Commands

Commands are user-invoked shortcuts that provide explicit control over when capabilities are used. They're typed as /command-name.

Key characteristics:

• User-invoked - Typed explicitly as /command-name (not auto-triggered)
• Simple - Focused instructions or actions rather than complex logic
• Focused - Single, clear purpose
• Explicit - User controls timing of invocation
• Discoverable - Shown in /help output

When to use commands:

• User wants explicit shortcut for frequent task
• Simple, focused instructions
• User should control timing
• Convenience wrapper for common operations

Core Philosophy

Commands Should Be Simple

Golden rule: Commands provide focused instructions, they don't implement complex logic.

Good command (simple and focused):

---
description: Run comprehensive code quality checks
---

# check-quality

Run linting, type checking, and tests on the codebase.

!npm run lint && npm run type-check && npm test

Bad command (complex logic):

# bad-example

# DON'T DO THIS - complex logic in command

First analyze all files, then determine which linters to run, then parse results,
then generate a custom report format, then send notifications...
[50 lines of implementation details]

Why keep it simple:

• Easier to maintain
• Clear purpose
• Less prone to errors
• Follows single responsibility principle

Commands Are Explicit

Unlike skills (which auto-trigger), commands require user action.

Use commands when:

• User wants control over timing
• Action shouldn't happen automatically
• Frequently-used prompt that deserves shortcut
• Explicit workflow trigger

Use skills when:

• Should auto-trigger based on context
• User doesn't need to remember to invoke it
• Complex domain knowledge that enhances conversation

Command Structure

Required Elements

Every command must have:

1. description field (in frontmatter) - Required for /help and model invocation
2. Command name heading (# command-name)
3. Clear purpose - What the command does

Optional Elements

Depending on complexity:

• Usage section - How to invoke, with/without arguments
• What It Does - Detailed explanation
• Examples - Sample invocations
• Use Cases - When to use the command
• Output - What to expect

Two Patterns

Pattern 1: Simple Command (6-10 lines)

• Just frontmatter + brief description
• Minimal documentation
• Clear, focused instructions

Pattern 2: Documented Command (30-80 lines)

• Full usage instructions
• Examples and use cases
• Detailed explanation of what happens
• What It Does section

Choose based on:

• Complexity of the operation
• Whether arguments need explanation
• How often users will reference it

See command-design-patterns.md for detailed design patterns and examples.

See command-creation-process.md for step-by-step creation workflow.

Commands vs Skills Decision Guide

📄 See when-to-use-what.md for complete decision guide including agents and output-styles (shared)

Quick guide:

Use a Command when:

• User wants explicit control over timing
• Action should be deliberate, not automatic
• Frequently-used prompt deserves shortcut
• User-initiated workflow
• Simple wrapper around agent/skill

Use a Skill when:

• AI should auto-discover capability
• Complex domain knowledge
• Should trigger on user queries automatically
• Needs progressive disclosure with references/
• Automatic workflow assistance

Common Mistakes to Avoid

1. Complex logic in command - Commands should provide focused instructions, not implement complex workflows
2. Missing description - Frontmatter description is required
3. Unclear purpose - Command should have single, clear focus
4. Vague purpose - Be specific about what the command does
5. Too many arguments - Keep it simple, 0-2 args typically
6. Not testing with /help - Verify command appears correctly
7. Poor naming - Use descriptive, action-oriented names

See command-examples.md for complete examples with analysis.

Tips for Success

1. Keep commands under 50 lines unless truly necessary
2. Stay focused - one clear purpose per command
3. Test with /help to verify display
4. Use descriptive names - action verbs work well
5. Make purpose immediately clear - no guessing
6. Optional arguments are better

...