architecture/skills/create-capability/SKILL.md

---
name: create-capability
description: >
  Create a new capability (skill, agent, or a cohesive set) for the architecture
  repository. Use when creating new skills, agents, extending AI workflows, or when
  user says /create-capability.
model: haiku
argument-hint: <description>
user-invocable: true
---

# Create Capability

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

Create new capabilities following latest Anthropic best practices (progressive disclosure, script bundling, Haiku-first).

## Process

1. **Understand the capability**: Analyze "$1" to understand what the user wants to build
   - What domain or workflow does this cover?
   - What user need does it address?
   - What existing capabilities might overlap?

2. **Determine components needed**: Based on the description, recommend which components:

   | Pattern | When to Use |
   |---------|-------------|
   | Skill only (background) | Knowledge to apply automatically (reused across other skills) |
   | Skill only (user-invocable) | User-invoked workflow |
   | Skill + Agent | Workflow with isolated worker for complex subtasks |
   | Full set | New domain expertise + workflow + isolated work |

   Present recommendation with reasoning:
   ```
   ## Recommended Components for: $1

   Based on your description, I recommend:
   - **Skill**: `name` - [why this knowledge is needed]
   - **Agent**: `name` - [why isolation/specialization is needed] (optional)

   Reasoning: [explain why this combination fits the need]
   ```

3. **Analyze complexity** (NEW): For each skill, determine structure needed:

   **Ask these questions:**

   a) **Expected size**: Will this skill be >500 lines?
      - If NO → Simple structure (just SKILL.md)
      - If YES → Suggest progressive disclosure

   b) **Error-prone operations**: Are there complex bash operations?
      - Check for: PR creation, worktree management, complex git operations
      - If YES → Suggest bundling scripts

   c) **Degree of freedom**: What instruction style is appropriate?
      - Multiple valid approaches → Text instructions (high freedom)
      - Preferred pattern with variation → Templates (medium freedom)
      - Fragile operations, exact sequence → Scripts (low freedom)

   **Present structure recommendation:**
   ```
   ## Recommended Structure

   Based on complexity analysis:
   - **Size**: [Simple | Progressive disclosure]
   - **Scripts**: [None | Bundle error-prone operations]
   - **Degrees of freedom**: [High | Medium | Low]

   Structure:
   [Show folder structure diagram]
   ```

4. **Gather information**: For each recommended component, ask:

   **For all components:**
   - Name (kebab-case, descriptive)
   - Description (one-line summary including trigger conditions)

   **For Skills:**
   - What domain/knowledge does this cover?
   - What are the key concepts to teach?
   - What patterns or templates should it include?
   - Is it user-invocable (workflow) or background (reference)?

   **For Agents:**
   - What specialized role does this fill?
   - What skills does it need?
   - Should it be read-only (no Edit/Write)?

5. **Select appropriate models** (UPDATED):

   **Default to Haiku, upgrade only if needed:**

   | Model | Use For | Cost vs Haiku |
   |-------|---------|---------------|
   | `haiku` | Most skills and agents (DEFAULT) | Baseline |
   | `sonnet` | When Haiku would struggle (<80% success rate) | 12x more expensive |
   | `opus` | Deep reasoning, architectural analysis | 60x more expensive |

   **Ask for justification if not Haiku:**
   - "This looks like a simple workflow. Should we try Haiku first?"
   - "Does this require complex reasoning that Haiku can't handle?"

   For each component, recommend Haiku unless there's clear reasoning for Sonnet/Opus.

6. **Generate files**: Create content using templates from capability-writing skill

   **Structure options:**

   a) **Simple skill** (most common):
   ```
   skills/skill-name/
   └── SKILL.md
   ```

   b) **Progressive disclosure** (for large skills):
   ```
   skills/skill-name/
   ├── SKILL.md (~200-300 lines)
   ├── reference/
   │   ├── detailed-guide.md
   │   └── api-reference.md
   └── examples/
       └── usage-examples.md
   ```

   c) **With bundled scripts** (for error-prone operations):
   ```
   skills/skill-name/
   ├── SKILL.md
   ├── reference/
   │   └── error-handling.md
   └── scripts/
       ├── validate.sh
       └── process.sh
   ```

   **Ensure proper inter-references:**
   - User-invocable skill references background skills via `@~/.claude/skills/name/SKILL.md`
   - Agent lists skills in `skills:` frontmatter (names only, not paths)
   - User-invocable skill spawns agent via Task tool if agent is part of the set
   - Scripts are called with `./scripts/script-name.sh` in SKILL.md

7. **Present for approval**: Show all generated files with their full content:
   ```
   ## Generated Files

   ### skills/name/SKILL.md
   [full content]

   ### skills/name/scripts/helper.sh (if applicable)
   [full content]

   ### agents/name/AGENT.md (if applicable)
   [full content]

   Ready to create these files?
   ```

8. **Create files** in correct locations after approval:
   - Create directories if needed
   - `skills/<name>/SKILL.md`
   - `skills/<name>/scripts/` (if scripts recommended)
   - `skills/<name>/reference/` (if progressive disclosure)
   - `agents/<name>/AGENT.md` (if agent recommended)

9. **Report success**:
   ```
   ## Capability Created: name

   Files created:
   - skills/name/SKILL.md
   - skills/name/scripts/helper.sh (if applicable)
   - agents/name/AGENT.md (if applicable)

   Next steps:
   1. Run `make install` to symlink to ~/.claude/
   2. Test with: /name (for user-invocable skills)
   3. **Test with Haiku** on 3-5 scenarios
   4. Measure success rate (aim for ≥80%)
   5. Upgrade to Sonnet only if Haiku <80%
   ```

## Guidelines (UPDATED)

- Follow all conventions from capability-writing skill
- **Default to Haiku** for all new skills/agents (12x cheaper, 2-5x faster)
- **Bundle scripts** for error-prone bash operations
- **Use progressive disclosure** for skills >500 lines
- Reference existing skills rather than duplicating knowledge
- Keep components focused - split if scope is too broad
- User-invocable skills should have approval checkpoints
- Skills should have descriptive `description` fields with trigger conditions
- **Be concise** - assume Claude knows basics

## Output Style

Be concise and direct:
- No preambles ("I'll help you...")
- No sign-offs ("Let me know...")
- Show structure diagrams clearly
- Use tables for comparisons
- One decision per section