--- description: Create new capabilities (skills, commands, agents) with validation and guided design decisions. argument-hint: model: 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 `` 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//`, `commands/`, `agents//` | | 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 ```yaml --- description: Review database migrations for safety and best practices --- ``` ``` 11. **Ask for approval** (gate before file creation): - "Create these files? (y/n)" - If warnings exist: "There are warnings. Proceed anyway? (y/n)" - **If user declines**: Stop here. Offer to adjust the generated content or cancel. - **If user approves**: Proceed to Phase 6. ### Phase 6: Create Files **Only execute this phase after user approval in step 11.** 12. **Create directories** if needed: ```bash mkdir -p skills/ mkdir -p agents/ ``` If directory creation fails, report the error and stop. 13. **Write files** to correct locations: - `skills//SKILL.md` - `commands/.md` - `agents//AGENT.md` If any file write fails, report which files were created and which failed. 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