feat(skills): modernize capability-writing with Anthropic best practices

Updates capability-writing skill with progressive disclosure structure based on
Anthropic's January 2025 documentation. Implements Haiku-first approach (12x
cheaper, 2-5x faster than Sonnet).

Key changes:
- Add 5 core principles: conciseness, progressive disclosure, script bundling,
  degrees of freedom, and Haiku-first model selection
- Restructure with best-practices.md, templates/, examples/, and reference/
- Create 4 templates: user-invocable skill, background skill, agent, helper script
- Add 3 examples: simple workflow, progressive disclosure, with scripts
- Add 3 reference docs: frontmatter fields, model selection, anti-patterns
- Update create-capability to analyze complexity and recommend structures
- Default all new skills/agents to Haiku unless justified

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

skills/create-capability/SKILL.md

@@ -13,7 +13,7 @@ user-invocable: true
 
 @~/.claude/skills/capability-writing/SKILL.md
 
-Create new capabilities following established patterns. A capability may be a single component or a cohesive set (skill + agent).
+Create new capabilities following latest Anthropic best practices (progressive disclosure, script bundling, Haiku-first).
 
 ## Process
 
@@ -42,11 +42,41 @@ Create new capabilities following established patterns. A capability may be a si
    Reasoning: [explain why this combination fits the need]
    ```
 
-3. **Gather information**: For each recommended component, ask:
+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)
+   - Description (one-line summary including trigger conditions)
 
    **For Skills:**
    - What domain/knowledge does this cover?
@@ -59,59 +89,117 @@ Create new capabilities following established patterns. A capability may be a si
    - What skills does it need?
    - Should it be read-only (no Edit/Write)?
 
-4. **Select appropriate models**:
+5. **Select appropriate models** (UPDATED):
 
-   | Model | Use For |
-   |-------|---------|
-   | `haiku` | Simple fetch/display skills, formatting tasks |
-   | `sonnet` | Most skills and agents (default) |
-   | `opus` | Deep reasoning, architectural analysis, complex judgment |
+   **Default to Haiku, upgrade only if needed:**
 
-   For each component, recommend a model with reasoning.
+   | 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 |
 
-5. **Generate files**: Create content using templates from capability-writing skill
+   **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?"
 
-   Ensure proper inter-references:
+   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
 
-6. **Present for approval**: Show all generated files with their full content:
+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?
    ```
 
-7. **Create files** in correct locations after approval:
+8. **Create files** in correct locations after approval:
+   - Create directories if needed
    - `skills/<name>/SKILL.md`
-   - `agents/<name>/AGENT.md`
+   - `skills/<name>/scripts/` (if scripts recommended)
+   - `skills/<name>/reference/` (if progressive disclosure)
+   - `agents/<name>/AGENT.md` (if agent recommended)
 
-8. **Report success**:
+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. Background skills will auto-activate based on context
+   3. **Test with Haiku** on 3-5 scenarios
+   4. Measure success rate (aim for ≥80%)
+   5. Upgrade to Sonnet only if Haiku <80%
    ```
 
-## Guidelines
+## 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 before significant actions
-- Default to `sonnet` model unless there's a clear reason for haiku/opus
-- Skills should have descriptive `description` fields for auto-activation
+- 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