diff --git a/commands/create-capability.md b/commands/create-capability.md new file mode 100644 index 0000000..e4d14c0 --- /dev/null +++ b/commands/create-capability.md @@ -0,0 +1,248 @@ +--- +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**: + - "Create these files? (y/n)" + - If warnings exist: "There are warnings. Proceed anyway? (y/n)" + +### Phase 6: Create Files + +12. **Create directories** if needed: + ```bash + mkdir -p skills/ + mkdir -p agents/ + ``` + +13. **Write files** to correct locations: + - `skills//SKILL.md` + - `commands/.md` + - `agents//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