Address review feedback: clarify approval gate before file creation

- Made step 11 explicitly a gate before file creation
- Added explicit conditional ("If user declines/approves") flow
- Added note at Phase 6 start: "Only execute this phase after user approval"
- Added error handling notes for directory creation and file writes

The step ordering was already correct (approval step 11 before file creation
steps 12-13), but the flow is now more explicit about the conditional nature.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

commands/create-capability.md

@@ -0,0 +1,256 @@
+---
+description: Create new capabilities (skills, commands, agents) with validation and guided design decisions.
+argument-hint: <description>
+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 `<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
+
+    ```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/<name>
+    mkdir -p agents/<name>
+    ```
+
+    If directory creation fails, report the error and stop.
+
+13. **Write files** to correct locations:
+    - `skills/<name>/SKILL.md`
+    - `commands/<name>.md`
+    - `agents/<name>/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