architecture/commands/create-capability.md

description, argument-hint, model

description	argument-hint	model
Create new capabilities (skills, commands, agents) with validation and guided design decisions.	<description>	sonnet

Create Capability

@~/.claude/skills/capability-writing/SKILL.md

Create new capabilities for the architecture repository with validation and interactive guidance.

Process

Phase 1: Understand Intent

1. Parse the description from $1 or ask for one:

   • "What capability do you want to add? Describe what it should do."

2. Ask clarifying questions to determine component type:

   Question	Purpose
   "Will this knowledge apply automatically, or is it user-invoked?"	Skill vs Command
   "Does this need isolated context for complex work?"	Agent needed?
   "Is this read-only analysis or does it modify files?"	Tool restrictions
   "Will this be used repeatedly, or is it one-time?"	Worth encoding?

3. Recommend components based on answers:

   • Skill only: Knowledge Claude applies automatically
   • Command only: Workflow using existing skills
   • Command + Skill: New knowledge + workflow
   • Command + Agent: Workflow with isolated worker
   • Full set: Skill + Command + Agent

Phase 2: Gather Details

4. Collect information for each component:

   For Skills:

   • Name (kebab-case): skill name matching directory
   • Description: what it teaches + trigger conditions
   • Core sections to include

   For Commands:

   • Name (kebab-case): verb-phrase action name
   • Description: one-line summary
   • Arguments: required <arg> and optional [arg]
   • Skills to reference

   For Agents:

   • Name (kebab-case): role-based specialist name
   • Description: what it does + when to spawn
   • Skills it needs
   • Tool restrictions (read-only?)

Phase 3: Model Selection

5. Recommend appropriate models with explanation:

   Capability Pattern	Model	Rationale
   Simple display/fetch	haiku	Speed for mechanical tasks
   Most commands	sonnet	Balanced for workflows
   Code generation	sonnet	Good reasoning for code
   Deep analysis/review	opus	Complex judgment needed
   Read-only agents	sonnet	Standard agent work
   Architectural decisions	opus	High-stakes reasoning

   Say something like:

   • "This seems like a simple display task - I recommend haiku for speed"
   • "This involves code generation - I recommend sonnet"
   • "This requires architectural analysis - I recommend opus"

Phase 4: Generate and Validate

6. Generate file content using templates from capability-writing skill

7. Run validation checks before showing preview:

   Frontmatter Validation

   Check	Component	Rule
   Required fields	All	name for skills/agents, description for all
   Model value	All	Must be haiku, sonnet, or opus (or absent)
   Tools list	Agents	Only valid tool names: Bash, Read, Write, Edit, Glob, Grep, Task, TodoWrite
   Skills reference	Agents	Each skill in list must exist in skills/*/SKILL.md

   Content Validation

   Check	Component	Rule
   Trigger conditions	Skills	Description must explain when to use (not just what)
   Step instructions	Commands	Must have numbered steps with **Step**: format
   Behavior sections	Agents	Must have "When Invoked" or process section
   Skill references	Commands	@~/.claude/skills/name/SKILL.md paths must be valid

   Convention Checks

   Check	Rule
   Skill file name	Must be SKILL.md (uppercase)
   Command file name	Must be lowercase kebab-case
   Agent file name	Must be AGENT.md (uppercase)
   Directory structure	skills/<name>/, commands/, agents/<name>/
   No duplicates	Name must not match existing capability

8. Check for anti-patterns and warn:

   Anti-pattern	Detection	Warning
   Trigger in body	Skill body contains "when to use"	"Move trigger conditions to description frontmatter"
   No tool restrictions	Read-only agent without disallowedTools	"Consider adding disallowedTools: [Edit, Write] for read-only agents"
   Missing skill refs	Command mentions domain without @ reference	"Add explicit skill reference: @~/.claude/skills/name/SKILL.md"
   Overly broad tools	Agent allows all tools but does specific task	"Consider restricting tools to what's actually needed"
   Generic naming	Name like utils, helper, misc	"Use specific domain-focused naming"
   God capability	Single component handling multiple unrelated concerns	"Consider splitting into focused components"

Phase 5: Present and Confirm

9. Show validation results:

   ## Validation Results
   
   [PASS] Frontmatter: All required fields present
   [PASS] Model: sonnet is valid
   [WARN] Anti-pattern: Agent allows all tools but only reads files
         Recommendation: Add disallowedTools: [Edit, Write]
   [PASS] Conventions: File names follow patterns
   [PASS] No duplicates: Name is unique
   
   Proceed with warnings? (y/n)
   

10. Show file preview with full content:

    ## Files to Create
    
    ### skills/migration-review/SKILL.md
    
    ```yaml
    ---
    name: migration-review
    description: >
      Knowledge for reviewing database migrations...
    ---
    

    commands/review-migration.md

    ---
    description: Review database migrations for safety and best practices
    ---
    

11. Ask for approval:

    • "Create these files? (y/n)"
    • If warnings exist: "There are warnings. Proceed anyway? (y/n)"

Phase 6: Create Files

12. Create directories if needed:

    mkdir -p skills/<name>
    mkdir -p agents/<name>
    

13. Write files to correct locations:

    • skills/<name>/SKILL.md
    • commands/<name>.md
    • agents/<name>/AGENT.md

14. Report success:

    ## Capability Created
    
    Files created:
    - skills/migration-review/SKILL.md
    - commands/review-migration.md
    
    Next steps:
    1. Run `make install` to symlink to ~/.claude/
    2. Test with: /review-migration
    3. Refine based on usage
    

Validation Error Messages

Provide clear, actionable error messages:

Error	Message
Missing name	"Skill requires name field in frontmatter"
Invalid model	"Model must be haiku, sonnet, or opus. Got: gpt-4"
Unknown tool	"Unknown tool Search in disallowedTools. Valid tools: Bash, Read, Write, Edit, Glob, Grep, Task, TodoWrite"
Missing skill	"Agent references skill foo but skills/foo/SKILL.md does not exist"
Invalid path	"Skill reference @~/.claude/skills/bar/SKILL.md invalid - directory skills/bar/ not found"
Duplicate name	"Capability gitea already exists at skills/gitea/SKILL.md"
Wrong file name	"Skill file must be named SKILL.md, not skill.md"

Example Session

User: /create-capability I want to add support for reviewing database migrations

Claude: I'll help you create a migration review capability. Let me ask a few questions:

1. Will this knowledge apply automatically when Claude sees migrations,
   or should users explicitly invoke it?

User: Users should invoke it explicitly

Claude: 2. Does this need isolated context for deep analysis, or can it work
   in the main conversation?

User: Isolated would be good for complex migrations

Claude: 3. Is this read-only analysis, or will it modify migration files?

User: Just analysis, read-only

Claude: Based on your answers, I recommend:

- **Command**: `/review-migration` - Entry point for users
- **Skill**: `migration-review` - Knowledge about safe migrations
- **Agent**: `migration-reviewer` - Isolated analysis (read-only)

For model selection:
- Command: `sonnet` (standard workflow)
- Agent: `sonnet` with `opus` upgrade path for complex cases

Let me gather details for each component...

[Continues with file generation, validation, and creation]

Guidelines

• Always run full validation before showing preview
• Show warnings but allow override with explicit confirmation
• Validate skill references exist before creating dependent components
• Suggest related existing skills that could be referenced
• Keep generated content minimal - users can expand after testing