diff --git a/skills/capability-writing/SKILL.md b/skills/capability-writing/SKILL.md
index bc6922a..5fc3f1b 100644
--- a/skills/capability-writing/SKILL.md
+++ b/skills/capability-writing/SKILL.md
@@ -10,7 +10,101 @@ user-invocable: false
 
 # Capability Writing
 
-How to design and create capabilities for the architecture repository. A capability may be a single component or a cohesive set (skill + agent).
+How to design and create capabilities for the architecture repository using Anthropic's latest best practices (January 2025).
+
+## Core Principles (NEW)
+
+### 1. Conciseness is Critical
+
+**Default assumption: Claude already knows.**
+
+- Don't explain git, tea, standard CLI tools
+- Don't explain concepts Claude understands
+- Only add domain-specific context
+- Keep main SKILL.md under 500 lines
+
+**Bad:** "Git is a version control system. The commit command saves changes..."
+**Good:** "`git commit -m 'feat: add feature'`"
+
+### 2. Progressive Disclosure
+
+Skills can bundle reference files and scripts that load/execute on-demand:
+
+```
+skill-name/
+├── SKILL.md              # Main workflow (200-500 lines)
+├── best-practices.md     # Detailed guidance (loaded when referenced)
+├── examples/
+│   ├── example1.md
+│   └── example2.md
+├── reference/
+│   ├── api-docs.md
+│   └── checklists.md
+└── scripts/              # Bundled with this skill
+    ├── validate.sh       # Executed, not loaded into context
+    └── process.sh
+```
+
+**Benefits:**
+- Main SKILL.md stays concise
+- Reference files load only when Claude references them
+- Scripts execute without consuming context tokens
+- Each skill is self-contained
+
+### 3. Script Bundling
+
+Bundle error-prone bash operations as scripts within the skill:
+
+**Instead of inline bash:**
+```markdown
+5. Create PR: `tea pulls create --title "..." --description "..."`
+```
+
+**Bundle a script:**
+```markdown
+5. **Create PR**: `./scripts/create-pr.sh $issue "$title"`
+```
+
+```bash
+# In skill-name/scripts/create-pr.sh
+#!/bin/bash
+set -e
+# Script handles errors, retries, validation
+```
+
+**When to bundle scripts:**
+- Operations with complex error handling
+- Operations that need retries
+- Operations with multiple validation steps
+- Fragile bash operations
+
+### 4. Degrees of Freedom
+
+Match instruction style to task fragility:
+
+| Degree | When | Example |
+|--------|------|---------|
+| **High** (text) | Multiple valid approaches | "Review code quality and suggest improvements" |
+| **Medium** (template) | Preferred pattern with variation | "Use this template, customize as needed" |
+| **Low** (script) | Fragile operation, exact sequence | "Run: `./scripts/validate.sh`" |
+
+### 5. Model Selection (UPDATED)
+
+**New guidance:** Default to Haiku, justify if not.
+
+| Model | Use When | Cost vs Haiku |
+|-------|----------|---------------|
+| **Haiku** | Simple workflows, validated steps, with scripts | Baseline |
+| **Sonnet** | When Haiku testing shows <80% success rate | 12x more expensive |
+| **Opus** | Deep reasoning, architectural judgment | 60x more expensive |
+
+**Haiku works well when:**
+- Steps are simple and validated
+- Instructions are concise
+- Error-prone operations use scripts
+- Outputs have structured templates
+
+**Test with Haiku first.** Only upgrade if needed.
 
 ## Component Overview
 
@@ -40,41 +134,12 @@ Start here: What do you need?
              --> Full capability (background skill + user-invocable skill + agent)
 ```
 
-### Decision Matrix
-
-| Need | Component | Example |
-|------|-----------|---------|
-| Knowledge Claude applies automatically | Background skill | gitea, issue-writing |
-| User-invoked workflow | User-invocable skill | /work-issue, /dashboard |
-| Isolated subtask with focused context | Agent | code-reviewer, issue-worker |
-| All three working together | Full capability | architecture review |
-
-### Signs You Need Each Component
-
-**Create a Background Skill when:**
-- You explain the same concepts repeatedly
-- Quality is inconsistent without explicit guidance
-- Multiple user-invocable skills need the same knowledge
-- There is a clear domain that doesn't fit existing skills
-
-**Create a User-Invocable Skill when:**
-- Same workflow is used multiple times
-- User explicitly triggers the action
-- Approval checkpoints are needed
-- Multiple tools need orchestration
-
-**Create an Agent when:**
-- Task requires deep exploration that would pollute main context
-- Multiple skills work better together
-- Batch processing or parallel execution is needed
-- Specialist persona improves outputs
+**Detailed decision criteria:** See [best-practices.md](best-practices.md)
 
 ## Component Templates
 
 ### User-Invocable Skill Template
 
-Location: `skills/<name>/SKILL.md`
-
 ```yaml
 ---
 name: skill-name
@@ -99,22 +164,10 @@ Brief intro if needed.
 5. **Present results** with links and summary
 ```
 
-**Frontmatter fields:**
-
-| Field | Required | Description |
-|-------|----------|-------------|
-| `name` | Yes | Lowercase, hyphens, matches directory name |
-| `description` | Yes | What it does + when to use (max 1024 chars) |
-| `user-invocable` | Yes | Set `true` for user-triggered workflows |
-| `argument-hint` | No | Shows expected args: `<required>`, `[optional]` |
-| `model` | No | `haiku`, `sonnet`, `opus` |
-| `context` | No | Use `fork` for isolated context |
-| `allowed-tools` | No | Restrict available tools |
+**Complete template with all fields:** See [templates/user-invocable-skill.md](templates/user-invocable-skill.md)
 
 ### Background Skill Template
 
-Location: `skills/<name>/SKILL.md`
-
 ```yaml
 ---
 name: skill-name
@@ -129,130 +182,87 @@ user-invocable: false
 Brief description of what this skill covers.
 
 ## Core Concepts
-
-Explain fundamental ideas Claude needs to understand.
-
 ## Patterns and Templates
-
-Provide reusable structures and formats.
-
 ## Guidelines
-
-List rules, best practices, and quality standards.
-
 ## Examples
-
-Show concrete illustrations of the skill in action.
-
-## Common Mistakes
-
-Document pitfalls to avoid.
-
-## Reference
-
-Quick-reference tables, checklists, or commands.
 ```
 
-### Agent Template
+**Complete template:** See [templates/background-skill.md](templates/background-skill.md)
 
-Location: `agents/<name>/AGENT.md`
+### Agent Template
 
 ```yaml
 ---
 name: agent-name
 description: What this agent does and when to spawn it
-model: sonnet
+model: haiku
 skills: skill1, skill2
 disallowedTools:
-  - Edit
+  - Edit  # For read-only agents
   - Write
 ---
 
 You are a [role] specialist that [primary function].
 
 ## When Invoked
-
-Describe the process the agent follows:
-
-1. **Gather context**: What information to collect
-2. **Analyze**: What to evaluate
-3. **Act**: What actions to take
-4. **Report**: How to communicate results
-
-## Output Format
-
-Describe expected output structure.
-
-## Guidelines
-
-- Behavioral rules
-- Constraints
-- Quality standards
+1. **Gather context**
+2. **Analyze**
+3. **Act**
+4. **Report**
 ```
 
-**Frontmatter fields:**
+**Complete template:** See [templates/agent.md](templates/agent.md)
 
-| Field | Required | Description |
-|-------|----------|-------------|
-| `name` | Yes | Lowercase, hyphens, matches directory name |
-| `description` | Yes | What it does + when to spawn |
-| `model` | No | `haiku`, `sonnet`, `opus`, or `inherit` |
-| `skills` | No | Comma-separated skill names (not paths) |
-| `disallowedTools` | No | Tools to block (e.g., Edit, Write for read-only) |
-| `permissionMode` | No | `default` or `bypassPermissions` |
+**Helper script template:** See [templates/helper-script.sh](templates/helper-script.sh)
 
-## Model Selection Guidance
+## Structure Examples
 
-| Model | Use When | Examples |
-|-------|----------|----------|
-| `haiku` | Simple fetch/display, formatting, mechanical tasks | /dashboard, /roadmap |
-| `sonnet` | Most skills and agents, balanced performance | /work-issue, code-reviewer |
-| `opus` | Deep reasoning, architectural analysis, complex judgment | /arch-review-repo |
+### Simple Skill (< 300 lines, no scripts)
+```
+skills/simple-skill/
+└── SKILL.md
+```
 
-### Decision Criteria
+### Progressive Disclosure (with reference files)
+```
+skills/complex-skill/
+├── SKILL.md (~200 lines)
+├── reference/
+│   ├── detailed-guide.md
+│   └── api-reference.md
+└── examples/
+    └── usage-examples.md
+```
 
-- **Start with `haiku`** for simple display/fetch workflows
-- **Use `sonnet`** for most skills and agents (default choice)
-- **Reserve `opus` for judgment** - when errors are costly or reasoning is complex
-- **Consider the stakes** - higher consequence tasks warrant more capable models
+### With Bundled Scripts
+```
+skills/skill-with-scripts/
+├── SKILL.md
+├── reference/
+│   └── error-handling.md
+└── scripts/
+    ├── validate.sh
+    └── process.sh
+```
 
-## Naming Conventions
-
-### File and Folder Names
-
-| Component | Convention | Examples |
-|-----------|------------|----------|
-| Skill folder | kebab-case | `software-architecture`, `work-issue` |
-| Skill file | UPPERCASE | `SKILL.md` |
-| Agent folder | kebab-case | `code-reviewer`, `issue-worker` |
-| Agent file | UPPERCASE | `AGENT.md` |
-
-### Naming Patterns
-
-**Skills:** Name after the domain, knowledge area, or action
-- Good: `gitea`, `issue-writing`, `work-issue`, `dashboard`
-- Bad: `utils`, `helpers`, `misc`
-
-**Agents:** Name by role or persona (recognizable specialist)
-- Good: `code-reviewer`, `issue-worker`, `software-architect`
-- Bad: `helper`, `do-stuff`, `agent1`
+**Detailed examples:** See [examples/](examples/) folder
 
 ## Referencing Skills
 
 ### In User-Invocable Skills
 
-Use the `@` file reference syntax to guarantee background skill content is loaded:
+Use `@` file reference syntax to guarantee background skill content is loaded:
 
 ```markdown
 @~/.claude/skills/gitea/SKILL.md
 @~/.claude/skills/issue-writing/SKILL.md
 ```
 
-**Important:** Do NOT use phrases like "Use the gitea skill" - skills have only ~20% auto-activation rate. File references guarantee the content is available.
+**Important:** Do NOT use phrases like "Use the gitea skill" - file references guarantee the content is available.
 
 ### In Agents
 
-List skill names in the frontmatter (not paths):
+List skill names in frontmatter (not paths):
 
 ```yaml
 ---
@@ -261,24 +271,16 @@ skills: gitea, issue-writing, backlog-grooming
 ---
 ```
 
-The agent runtime loads these skills automatically.
-
 ## Common Patterns
 
-### Approval Workflow (User-Invocable Skills)
-
-Always ask before significant actions:
-
+### Approval Workflow
 ```markdown
 4. **Present plan** for approval
 5. **If approved**, create the issues
 6. **Present summary** with links
 ```
 
-### Conditional Behavior (User-Invocable Skills)
-
-Handle optional arguments with mode switching:
-
+### Conditional Behavior
 ```markdown
 ## If issue number provided ($1):
 1. Fetch specific issue
@@ -289,18 +291,12 @@ Handle optional arguments with mode switching:
 2. Process each
 ```
 
-### Spawning Agents from Skills
-
-Delegate complex subtasks:
-
+### Spawning Agents
 ```markdown
 9. **Auto-review**: Spawn the `code-reviewer` agent with the PR number
 ```
 
 ### Read-Only Agents
-
-For analysis without modification:
-
 ```yaml
 ---
 name: code-reviewer
@@ -310,73 +306,24 @@ disallowedTools:
 ---
 ```
 
-## Anti-Patterns to Avoid
+## Quick Reference
 
-### Overly Broad Components
+**Frontmatter fields:** See [reference/frontmatter-fields.md](reference/frontmatter-fields.md)
+**Model selection:** See [reference/model-selection.md](reference/model-selection.md)
+**Anti-patterns:** See [reference/anti-patterns.md](reference/anti-patterns.md)
+**Best practices:** See [best-practices.md](best-practices.md)
 
-**Bad:** One skill/agent that does everything
-```markdown
-# Project Management
-Handles issues, PRs, releases, documentation, deployment...
-```
+## Naming Conventions
 
-**Good:** Focused components with clear responsibility
-```markdown
-# Issue Writing
-How to write clear, actionable issues.
-```
+| Component | Convention | Examples |
+|-----------|------------|----------|
+| Skill folder | kebab-case | `software-architecture`, `work-issue` |
+| Skill file | UPPERCASE | `SKILL.md` |
+| Agent folder | kebab-case | `code-reviewer`, `issue-worker` |
+| Agent file | UPPERCASE | `AGENT.md` |
 
-### Vague Instructions
-
-**Bad:**
-```markdown
-1. Handle the issue
-2. Do the work
-3. Finish up
-```
-
-**Good:**
-```markdown
-1. **View the issue** with `--comments` flag
-2. **Create branch**: `git checkout -b issue-$1-<title>`
-3. **Commit** with message referencing the issue
-```
-
-### Missing Skill References
-
-**Bad:**
-```markdown
-Use the gitea skill to create an issue.
-```
-
-**Good:**
-```markdown
-@~/.claude/skills/gitea/SKILL.md
-
-Use `tea issues create --title "..." --description "..."`
-```
-
-### God Skills
-
-**Bad:** Single skill with 1000+ lines covering unrelated topics
-
-**Good:** Multiple focused skills that reference each other
-
-### Premature Agent Creation
-
-**Bad:** Creating an agent for every task
-
-**Good:** Use agents only when you need:
-- Context isolation
-- Skill composition
-- Parallel execution
-- Specialist persona
-
-## Detailed Documentation
-
-For comprehensive guides, see:
-
-- `docs/writing-capabilities.md` - Complete guide covering skills and agents
+**Skills:** Name after domain/action (good: `gitea`, `work-issue`; bad: `utils`, `helpers`)
+**Agents:** Name by role/persona (good: `code-reviewer`; bad: `helper`, `agent1`)
 
 ## Checklists
 
@@ -390,6 +337,7 @@ For comprehensive guides, see:
 - [ ] Background skills referenced via `@~/.claude/skills/<name>/SKILL.md`
 - [ ] Approval checkpoints before significant actions
 - [ ] File at `skills/<name>/SKILL.md`
+- [ ] **Model defaults to `haiku`** unless justified
 
 ### Before Creating a Background Skill
 
@@ -405,6 +353,6 @@ For comprehensive guides, see:
 - [ ] Built-in agents (Explore, Plan) are not sufficient
 - [ ] Context isolation or skill composition is needed
 - [ ] Clear role/persona emerges
-- [ ] `model` selection is deliberate (not just `inherit`)
+- [ ] `model` selection is deliberate (default to `haiku`)
 - [ ] `skills` list is right-sized (not too many)
 - [ ] File at `agents/<name>/AGENT.md`
diff --git a/skills/capability-writing/best-practices.md b/skills/capability-writing/best-practices.md
new file mode 100644
index 0000000..771eea6
--- /dev/null
+++ b/skills/capability-writing/best-practices.md
@@ -0,0 +1,500 @@
+# Skill Authoring Best Practices
+
+Based on Anthropic's latest agent skills documentation (January 2025).
+
+## Core Principles
+
+### Concise is Key
+
+> "The context window is a public good. Default assumption: Claude is already very smart."
+
+**Only add context Claude doesn't already have.**
+
+**Challenge each piece of information:**
+- "Does Claude really need this explanation?"
+- "Can I assume Claude knows this?"
+- "Does this paragraph justify its token cost?"
+
+**Good example (concise):**
+```markdown
+## Extract PDF text
+
+Use pdfplumber:
+
+\`\`\`python
+import pdfplumber
+with pdfplumber.open("file.pdf") as pdf:
+    text = pdf.pages[0].extract_text()
+\`\`\`
+```
+
+**Bad example (verbose):**
+```markdown
+## Extract PDF text
+
+PDF (Portable Document Format) files are a common file format that contains text,
+images, and other content. To extract text from a PDF, you'll need to use a library.
+There are many libraries available for PDF processing, but we recommend pdfplumber
+because it's easy to use and handles most cases well. First, you'll need to install
+it using pip. Then you can use the code below...
+```
+
+The concise version assumes Claude knows what PDFs are and how libraries work.
+
+### Set Appropriate Degrees of Freedom
+
+Match the level of specificity to the task's fragility and variability.
+
+#### High Freedom (Text-Based Instructions)
+
+Use when multiple approaches are valid:
+
+```markdown
+## Code Review Process
+
+1. Analyze code structure and organization
+2. Check for potential bugs or edge cases
+3. Suggest improvements for readability
+4. Verify adherence to project conventions
+```
+
+#### Medium Freedom (Templates/Pseudocode)
+
+Use when there's a preferred pattern but variation is acceptable:
+
+```markdown
+## Generate Report
+
+Use this template and customize as needed:
+
+\`\`\`python
+def generate_report(data, format="markdown", include_charts=True):
+    # Process data
+    # Generate output in specified format
+    # Optionally include visualizations
+\`\`\`
+```
+
+#### Low Freedom (Exact Scripts)
+
+Use when operations are fragile and error-prone:
+
+```markdown
+## Database Migration
+
+Run exactly this script:
+
+\`\`\`bash
+python scripts/migrate.py --verify --backup
+\`\`\`
+
+Do not modify the command or add additional flags.
+```
+
+**Analogy:** Think of Claude as a robot exploring a path:
+- **Narrow bridge with cliffs**: One safe way forward. Provide specific guardrails (low freedom)
+- **Open field**: Many paths lead to success. Give general direction (high freedom)
+
+### Progressive Disclosure
+
+Split large skills into layers that load on-demand.
+
+#### Three Levels of Loading
+
+| Level | When Loaded | Token Cost | Content |
+|-------|------------|------------|---------|
+| **Level 1: Metadata** | Always (at startup) | ~100 tokens | `name` and `description` from frontmatter |
+| **Level 2: Instructions** | When skill is triggered | Under 5k tokens | SKILL.md body with instructions |
+| **Level 3: Resources** | As needed | Unlimited | Referenced files, scripts |
+
+#### Organizing Large Skills
+
+**Pattern 1: High-level guide with references**
+
+```markdown
+# PDF Processing
+
+## Quick Start
+\`\`\`python
+import pdfplumber
+with pdfplumber.open("file.pdf") as pdf:
+    text = pdf.pages[0].extract_text()
+\`\`\`
+
+## Advanced Features
+**Form filling**: See [FORMS.md](FORMS.md)
+**API reference**: See [REFERENCE.md](REFERENCE.md)
+**Examples**: See [EXAMPLES.md](EXAMPLES.md)
+```
+
+Claude loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed.
+
+**Pattern 2: Domain-specific organization**
+
+For skills with multiple domains:
+
+```
+bigquery-skill/
+├── SKILL.md (overview and navigation)
+└── reference/
+    ├── finance.md (revenue, billing metrics)
+    ├── sales.md (opportunities, pipeline)
+    ├── product.md (API usage, features)
+    └── marketing.md (campaigns, attribution)
+```
+
+When user asks about revenue, Claude reads only `reference/finance.md`.
+
+**Pattern 3: Conditional details**
+
+```markdown
+# DOCX Processing
+
+## Creating Documents
+Use docx-js. See [DOCX-JS.md](DOCX-JS.md).
+
+## Editing Documents
+For simple edits, modify XML directly.
+
+**For tracked changes**: See [REDLINING.md](REDLINING.md)
+**For OOXML details**: See [OOXML.md](OOXML.md)
+```
+
+#### Avoid Deeply Nested References
+
+**Keep references one level deep from SKILL.md.**
+
+**Bad (too deep):**
+```
+SKILL.md → advanced.md → details.md → actual info
+```
+
+**Good (one level):**
+```
+SKILL.md → {advanced.md, reference.md, examples.md}
+```
+
+#### Structure Longer Files with TOC
+
+For reference files >100 lines, include a table of contents:
+
+```markdown
+# API Reference
+
+## Contents
+- Authentication and setup
+- Core methods (create, read, update, delete)
+- Advanced features (batch operations, webhooks)
+- Error handling patterns
+- Code examples
+
+## Authentication and Setup
+...
+```
+
+This ensures Claude can see the full scope even with partial reads.
+
+## Script Bundling
+
+### When to Bundle Scripts
+
+Bundle scripts for:
+- **Error-prone operations**: Complex bash with retry logic
+- **Fragile sequences**: Operations requiring exact order
+- **Validation steps**: Checking conditions before proceeding
+- **Reusable utilities**: Operations used in multiple steps
+
+**Benefits of bundled scripts:**
+- More reliable than generated code
+- Save tokens (no code in context)
+- Save time (no code generation)
+- Ensure consistency
+
+### Script Structure
+
+```bash
+#!/bin/bash
+# script-name.sh - Brief description
+#
+# Usage: script-name.sh <param1> <param2>
+#
+# Example: script-name.sh issue-42 "Fix bug"
+
+set -e  # Exit on error
+
+# Input validation
+if [ $# -lt 2 ]; then
+  echo "Usage: $0 <param1> <param2>"
+  exit 1
+fi
+
+param1=$1
+param2=$2
+
+# Main logic with error handling
+if ! some_command; then
+  echo "ERROR: Command failed"
+  exit 1
+fi
+
+# Success output
+echo "SUCCESS: Operation completed"
+```
+
+### Referencing Scripts in Skills
+
+**Make clear whether to execute or read:**
+
+**Execute (most common):**
+```markdown
+7. **Create PR**: `./scripts/create-pr.sh $1 "$title"`
+```
+
+**Read as reference (for understanding complex logic):**
+```markdown
+See `./scripts/analyze-form.py` for the field extraction algorithm
+```
+
+### Solving, Not Punting
+
+Scripts should handle error conditions, not punt to Claude.
+
+**Good (handles errors):**
+```python
+def process_file(path):
+    try:
+        with open(path) as f:
+            return f.read()
+    except FileNotFoundError:
+        print(f"File {path} not found, creating default")
+        with open(path, 'w') as f:
+            f.write('')
+        return ''
+    except PermissionError:
+        print(f"Cannot access {path}, using default")
+        return ''
+```
+
+**Bad (punts to Claude):**
+```python
+def process_file(path):
+    return open(path).read()  # Fails, Claude has to figure it out
+```
+
+## Workflow Patterns
+
+### Plan-Validate-Execute
+
+Add verification checkpoints to catch errors early.
+
+**Example: Workflow with validation**
+
+```markdown
+## PDF Form Filling
+
+Copy this checklist:
+
+\`\`\`
+Progress:
+- [ ] Step 1: Analyze form (run analyze_form.py)
+- [ ] Step 2: Create field mapping (edit fields.json)
+- [ ] Step 3: Validate mapping (run validate_fields.py)
+- [ ] Step 4: Fill form (run fill_form.py)
+- [ ] Step 5: Verify output (run verify_output.py)
+\`\`\`
+
+**Step 1: Analyze**
+Run: `python scripts/analyze_form.py input.pdf`
+
+**Step 2: Create Mapping**
+Edit `fields.json`
+
+**Step 3: Validate**
+Run: `python scripts/validate_fields.py fields.json`
+Fix any errors before continuing.
+
+**Step 4: Fill**
+Run: `python scripts/fill_form.py input.pdf fields.json output.pdf`
+
+**Step 5: Verify**
+Run: `python scripts/verify_output.py output.pdf`
+If verification fails, return to Step 2.
+```
+
+### Feedback Loops
+
+**Pattern:** Run validator → fix errors → repeat
+
+**Example: Document editing**
+
+```markdown
+1. Make edits to `word/document.xml`
+2. **Validate**: `python scripts/validate.py unpacked_dir/`
+3. If validation fails:
+   - Review error message
+   - Fix issues
+   - Run validation again
+4. **Only proceed when validation passes**
+5. Rebuild: `python scripts/pack.py unpacked_dir/ output.docx`
+6. Test output document
+```
+
+## Model Selection
+
+### Decision Framework
+
+```
+Start with Haiku
+    |
+    v
+Test on 3-5 representative tasks
+    |
+    +-- Success rate ≥80%? ---------> Use Haiku ✓
+    |
+    +-- Success rate <80%? --------> Try Sonnet
+                                          |
+                                          v
+                                    Test on same tasks
+                                          |
+                                          +-- Success ≥80%? --> Use Sonnet
+                                          |
+                                          +-- Still failing? --> Opus or redesign task
+```
+
+### Haiku Works Well When
+
+- **Steps are simple and validated**
+- **Instructions are concise** (no verbose explanations)
+- **Error-prone operations use scripts** (deterministic)
+- **Outputs have structured templates**
+- **Checklists replace open-ended judgment**
+
+### Testing with Multiple Models
+
+Test skills with all models you plan to use:
+
+1. **Create test cases:** 3-5 representative scenarios
+2. **Run with Haiku:** Measure success rate, response quality
+3. **Run with Sonnet:** Compare results
+4. **Adjust instructions:** If Haiku struggles, add clarity or scripts
+
+What works for Opus might need more detail for Haiku.
+
+## Common Anti-Patterns
+
+### Offering Too Many Options
+
+**Bad (confusing):**
+```markdown
+You can use pypdf, or pdfplumber, or PyMuPDF, or pdf2image, or...
+```
+
+**Good (provide default):**
+```markdown
+Use pdfplumber for text extraction:
+\`\`\`python
+import pdfplumber
+\`\`\`
+
+For scanned PDFs requiring OCR, use pdf2image with pytesseract instead.
+```
+
+### Time-Sensitive Information
+
+**Bad (will become wrong):**
+```markdown
+If you're doing this before August 2025, use the old API.
+After August 2025, use the new API.
+```
+
+**Good (use "old patterns" section):**
+```markdown
+## Current Method
+Use the v2 API: `api.example.com/v2/messages`
+
+## Old Patterns
+<details>
+<summary>Legacy v1 API (deprecated 2025-08)</summary>
+
+The v1 API used: `api.example.com/v1/messages`
+This endpoint is no longer supported.
+</details>
+```
+
+### Inconsistent Terminology
+
+**Good (consistent):**
+- Always "API endpoint"
+- Always "field"
+- Always "extract"
+
+**Bad (inconsistent):**
+- Mix "API endpoint", "URL", "API route", "path"
+- Mix "field", "box", "element", "control"
+- Mix "extract", "pull", "get", "retrieve"
+
+### Windows-Style Paths
+
+Always use forward slashes:
+
+- ✓ **Good**: `scripts/helper.py`, `reference/guide.md`
+- ✗ **Bad**: `scripts\helper.py`, `reference\guide.md`
+
+Unix-style paths work cross-platform.
+
+## Iterative Development
+
+### Build Evaluations First
+
+Create test cases BEFORE extensive documentation:
+
+1. **Identify gaps**: Run Claude on tasks without skill, document failures
+2. **Create evaluations**: Build 3-5 test scenarios
+3. **Establish baseline**: Measure Claude's performance without skill
+4. **Write minimal instructions**: Just enough to pass evaluations
+5. **Iterate**: Execute evaluations, refine
+
+### Develop Iteratively with Claude
+
+**Use Claude to help write skills:**
+
+1. **Complete a task without skill**: Work through problem, note what context you provide
+2. **Identify reusable pattern**: What context is useful for similar tasks?
+3. **Ask Claude to create skill**: "Create a skill that captures this pattern"
+4. **Review for conciseness**: Remove unnecessary explanations
+5. **Test on similar tasks**: Use skill with fresh Claude instance
+6. **Iterate based on observation**: Where does Claude struggle?
+
+Claude understands skill format natively - no special prompts needed.
+
+## Checklist for Effective Skills
+
+**Before publishing:**
+
+### Core Quality
+- [ ] Description is specific and includes key terms
+- [ ] Description includes what skill does AND when to use it
+- [ ] SKILL.md body under 500 lines
+- [ ] Additional details in separate files (if needed)
+- [ ] No time-sensitive information
+- [ ] Consistent terminology throughout
+- [ ] Examples are concrete, not abstract
+- [ ] File references are one level deep
+- [ ] Progressive disclosure used appropriately
+- [ ] Workflows have clear steps
+
+### Code and Scripts
+- [ ] Scripts solve problems, don't punt to Claude
+- [ ] Error handling is explicit and helpful
+- [ ] No "magic numbers" (all values justified)
+- [ ] Required packages listed and verified
+- [ ] Scripts have clear documentation
+- [ ] No Windows-style paths (all forward slashes)
+- [ ] Validation steps for critical operations
+- [ ] Feedback loops for quality-critical tasks
+
+### Testing
+- [ ] At least 3 test cases created
+- [ ] Tested with Haiku (if that's the target)
+- [ ] Tested with real usage scenarios
+- [ ] Team feedback incorporated (if applicable)
diff --git a/skills/capability-writing/examples/progressive-disclosure.md b/skills/capability-writing/examples/progressive-disclosure.md
new file mode 100644
index 0000000..86822f1
--- /dev/null
+++ b/skills/capability-writing/examples/progressive-disclosure.md
@@ -0,0 +1,129 @@
+# Example: Progressive Disclosure Skill
+
+A skill that uses reference files to keep the main SKILL.md concise.
+
+## Structure
+
+```
+skills/database-query/
+├── SKILL.md (~200 lines)
+├── reference/
+│   ├── schemas.md (table schemas)
+│   ├── common-queries.md (frequently used queries)
+│   └── optimization-tips.md (performance guidance)
+└── examples/
+    ├── simple-select.md
+    └── complex-join.md
+```
+
+## When to Use
+
+- Skill content would be >500 lines
+- Multiple domains or topics
+- Reference documentation is large
+- Want to keep main workflow concise
+
+## Example: database-query (main SKILL.md)
+
+```markdown
+---
+name: database-query
+description: >
+  Help users query the PostgreSQL database with proper schemas and optimization.
+  Use when user needs to write SQL queries or mentions database/tables.
+user-invocable: false
+---
+
+# Database Query Helper
+
+Help write efficient, correct SQL queries for our PostgreSQL database.
+
+## Quick Start
+
+\`\`\`sql
+SELECT id, name, created_at
+FROM users
+WHERE status = 'active'
+LIMIT 10;
+\`\`\`
+
+## Table Schemas
+
+We have 3 main schemas:
+
+- **Users & Auth**: See [reference/schemas.md#users](reference/schemas.md#users)
+- **Products**: See [reference/schemas.md#products](reference/schemas.md#products)
+- **Orders**: See [reference/schemas.md#orders](reference/schemas.md#orders)
+
+## Common Queries
+
+For frequently requested queries, see [reference/common-queries.md](reference/common-queries.md):
+- User activity reports
+- Sales summaries
+- Inventory status
+
+## Writing Queries
+
+1. **Identify tables**: Which schemas does this query need?
+2. **Check schema**: Load relevant schema from reference
+3. **Write query**: Use proper column names and types
+4. **Optimize**: See [reference/optimization-tips.md](reference/optimization-tips.md)
+
+## Examples
+
+- **Simple select**: See [examples/simple-select.md](examples/simple-select.md)
+- **Complex join**: See [examples/complex-join.md](examples/complex-join.md)
+```
+
+## Example: reference/schemas.md
+
+```markdown
+# Database Schemas
+
+## Users
+
+| Column | Type | Description |
+|--------|------|-------------|
+| id | UUID | Primary key |
+| email | VARCHAR(255) | Unique email |
+| name | VARCHAR(100) | Display name |
+| status | ENUM('active','inactive','banned') | Account status |
+| created_at | TIMESTAMP | Account creation |
+| updated_at | TIMESTAMP | Last update |
+
+## Products
+
+| Column | Type | Description |
+|--------|------|-------------|
+| id | UUID | Primary key |
+| name | VARCHAR(200) | Product name |
+| price | DECIMAL(10,2) | Price in USD |
+| inventory | INTEGER | Stock count |
+| category_id | UUID | FK to categories |
+
+## Orders
+
+[...more tables...]
+```
+
+## Why This Works
+
+- **Main file stays concise** (~200 lines)
+- **Details load on-demand**: schemas.md loads when user asks about specific table
+- **Fast for common cases**: Simple queries don't need reference files
+- **Scalable**: Can add more schemas without bloating main file
+
+## Loading Pattern
+
+1. User: "Show me all active users"
+2. Claude reads SKILL.md (sees Users schema reference)
+3. Claude: "I'll load the users schema to get column names"
+4. Claude reads reference/schemas.md#users
+5. Claude writes correct query
+
+## What Makes It Haiku-Friendly
+
+- ✓ Main workflow is simple ("identify → check schema → write query")
+- ✓ Reference files provide facts, not reasoning
+- ✓ Clear pointers to where details are
+- ✓ Examples show patterns
diff --git a/skills/capability-writing/examples/simple-workflow.md b/skills/capability-writing/examples/simple-workflow.md
new file mode 100644
index 0000000..9ad2e16
--- /dev/null
+++ b/skills/capability-writing/examples/simple-workflow.md
@@ -0,0 +1,71 @@
+# Example: Simple Workflow Skill
+
+A basic skill with just a SKILL.md file - no scripts or reference files needed.
+
+## Structure
+
+```
+skills/list-open-prs/
+└── SKILL.md
+```
+
+## When to Use
+
+- Skill is simple (<300 lines)
+- No error-prone bash operations
+- No need for reference documentation
+- Straightforward workflow
+
+## Example: list-open-prs
+
+```markdown
+---
+name: list-open-prs
+description: >
+  List all open pull requests for the current repository.
+  Use when user wants to see PRs or says /list-open-prs.
+model: haiku
+user-invocable: true
+---
+
+# List Open PRs
+
+@~/.claude/skills/gitea/SKILL.md
+
+Show all open pull requests in the current repository.
+
+## Process
+
+1. **Get repository info**
+   - `git remote get-url origin`
+   - Parse owner/repo from URL
+
+2. **Fetch open PRs**
+   - `tea pulls list --state open --output simple`
+
+3. **Format results** as table
+
+| PR # | Title | Author | Created |
+|------|-------|--------|---------|
+| ... | ... | ... | ... |
+
+## Guidelines
+
+- Show most recent PRs first
+- Include link to each PR
+- If no open PRs, say "No open pull requests"
+```
+
+## Why This Works
+
+- **Concise**: Entire skill fits in ~30 lines
+- **Simple commands**: Just git and tea CLI
+- **No error handling needed**: tea handles errors gracefully
+- **Structured output**: Table format is clear
+
+## What Makes It Haiku-Friendly
+
+- ✓ Simple sequential steps
+- ✓ Clear commands with no ambiguity
+- ✓ Structured output format
+- ✓ No complex decision-making
diff --git a/skills/capability-writing/examples/with-scripts.md b/skills/capability-writing/examples/with-scripts.md
new file mode 100644
index 0000000..2d18eaf
--- /dev/null
+++ b/skills/capability-writing/examples/with-scripts.md
@@ -0,0 +1,210 @@
+# Example: Skill with Bundled Scripts
+
+A skill that bundles helper scripts for error-prone operations.
+
+## Structure
+
+```
+skills/deploy-to-staging/
+├── SKILL.md
+├── reference/
+│   └── rollback-procedure.md
+└── scripts/
+    ├── validate-build.sh
+    ├── deploy.sh
+    └── health-check.sh
+```
+
+## When to Use
+
+- Operations have complex error handling
+- Need retry logic
+- Multiple validation steps
+- Fragile bash commands
+
+## Example: deploy-to-staging (main SKILL.md)
+
+```markdown
+---
+name: deploy-to-staging
+description: >
+  Deploy current branch to staging environment with validation and health checks.
+  Use when deploying to staging or when user says /deploy-to-staging.
+model: haiku
+user-invocable: true
+---
+
+# Deploy to Staging
+
+Deploy current branch to staging with automated validation and rollback capability.
+
+## Process
+
+1. **Validate build**
+   - `./scripts/validate-build.sh`
+   - Checks tests pass, linter clean, no uncommitted changes
+
+2. **Show deployment plan** for approval
+   - Branch name
+   - Latest commit
+   - Services that will be updated
+
+3. **If approved, deploy**
+   - `./scripts/deploy.sh staging $branch`
+   - Script handles Docker build, push, k8s apply
+
+4. **Health check**
+   - `./scripts/health-check.sh staging`
+   - Verifies all services are healthy
+
+5. **Report results**
+   - Deployment URL
+   - Status of each service
+   - Rollback command if needed
+
+## Rollback
+
+If deployment fails, see [reference/rollback-procedure.md](reference/rollback-procedure.md)
+```
+
+## Example: scripts/validate-build.sh
+
+```bash
+#!/bin/bash
+# validate-build.sh - Pre-deployment validation
+#
+# Checks:
+# - Tests pass
+# - Linter clean
+# - No uncommitted changes
+# - Docker builds successfully
+
+set -e
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+NC='\033[0m'
+
+error() {
+    echo -e "${RED}ERROR: $1${NC}" >&2
+    exit 1
+}
+
+success() {
+    echo -e "${GREEN}✓ $1${NC}"
+}
+
+# Check 1: No uncommitted changes
+if ! git diff-index --quiet HEAD --; then
+    error "Uncommitted changes detected. Commit or stash first."
+fi
+success "No uncommitted changes"
+
+# Check 2: Tests pass
+if ! npm test > /dev/null 2>&1; then
+    error "Tests failing. Fix tests before deploying."
+fi
+success "Tests pass"
+
+# Check 3: Linter clean
+if ! npm run lint > /dev/null 2>&1; then
+    error "Linter errors. Run 'npm run lint' to see details."
+fi
+success "Linter clean"
+
+# Check 4: Docker builds
+if ! docker build -t test-build . > /dev/null 2>&1; then
+    error "Docker build failed"
+fi
+success "Docker build successful"
+
+echo ""
+echo -e "${GREEN}✓ All validations passed${NC}"
+```
+
+## Example: scripts/deploy.sh
+
+```bash
+#!/bin/bash
+# deploy.sh - Deploy to environment
+#
+# Usage: deploy.sh <environment> <branch>
+# Example: deploy.sh staging feature-new-ui
+
+set -e
+
+ENVIRONMENT=$1
+BRANCH=$2
+
+if [ -z "$ENVIRONMENT" ] || [ -z "$BRANCH" ]; then
+    echo "Usage: $0 <environment> <branch>"
+    exit 1
+fi
+
+echo "Deploying $BRANCH to $ENVIRONMENT..."
+
+# Build Docker image
+docker build -t myapp:$BRANCH .
+
+# Tag for registry
+docker tag myapp:$BRANCH registry.example.com/myapp:$BRANCH
+
+# Push to registry with retry
+for i in {1..3}; do
+    if docker push registry.example.com/myapp:$BRANCH; then
+        break
+    fi
+    echo "Push failed, retrying ($i/3)..."
+    sleep 5
+done
+
+# Update Kubernetes deployment
+kubectl set image deployment/myapp \
+    myapp=registry.example.com/myapp:$BRANCH \
+    -n $ENVIRONMENT
+
+# Wait for rollout
+kubectl rollout status deployment/myapp -n $ENVIRONMENT --timeout=5m
+
+echo "Deployment complete!"
+echo "URL: https://$ENVIRONMENT.example.com"
+```
+
+## Why This Works
+
+**Script benefits:**
+- **Deterministic**: Same behavior every time
+- **Error handling**: Retries, clear messages
+- **Validation**: Pre-flight checks prevent bad deployments
+- **No token cost**: Scripts execute without loading code into context
+
+**Skill stays simple:**
+- Main SKILL.md is ~30 lines
+- Just calls scripts in order
+- No complex bash logic inline
+- Easy to test scripts independently
+
+## What Makes It Haiku-Friendly
+
+- ✓ Skill has simple instructions ("run script X, then Y")
+- ✓ Scripts handle all complexity
+- ✓ Clear success/failure from script exit codes
+- ✓ Validation prevents ambiguous states
+- ✓ Structured output from scripts is easy to parse
+
+## Testing Scripts
+
+Scripts can be tested independently:
+
+```bash
+# Test validation
+./scripts/validate-build.sh
+
+# Test deployment (dry-run)
+./scripts/deploy.sh staging test-branch --dry-run
+
+# Test health check
+./scripts/health-check.sh staging
+```
+
+This makes the skill more reliable than inline bash.
diff --git a/skills/capability-writing/reference/anti-patterns.md b/skills/capability-writing/reference/anti-patterns.md
new file mode 100644
index 0000000..410ca66
--- /dev/null
+++ b/skills/capability-writing/reference/anti-patterns.md
@@ -0,0 +1,536 @@
+# Anti-Patterns to Avoid
+
+Common mistakes when creating skills and agents.
+
+## Skill Design Anti-Patterns
+
+### 1. Overly Broad Components
+
+**Bad:** One skill that does everything
+
+```yaml
+---
+name: project-management
+description: Handles issues, PRs, releases, documentation, deployment, testing, CI/CD...
+---
+
+# Project Management
+
+This skill does:
+- Issue management
+- Pull request reviews
+- Release planning
+- Documentation
+- Deployment
+- Testing
+- CI/CD configuration
+...
+```
+
+**Why it's bad:**
+- Huge context window usage
+- Hard to maintain
+- Unclear when to trigger
+- Tries to do too much
+
+**Good:** Focused components
+
+```yaml
+---
+name: issue-writing
+description: How to write clear, actionable issues with acceptance criteria.
+---
+```
+
+**Separate skills for:**
+- `issue-writing` - Issue quality
+- `review-pr` - PR reviews
+- `gitea` - CLI reference
+- Each does one thing well
+
+---
+
+### 2. Vague Instructions
+
+**Bad:**
+
+```markdown
+1. Handle the issue
+2. Do the work
+3. Finish up
+4. Let me know when done
+```
+
+**Why it's bad:**
+- No clear actions
+- Claude has to guess
+- Inconsistent results
+- Hard to validate
+
+**Good:**
+
+```markdown
+1. **View issue**: `tea issues $1 --comments`
+2. **Create branch**: `git checkout -b issue-$1-<title>`
+3. **Plan work**: Use TodoWrite to break down steps
+4. **Implement**: Make necessary changes
+5. **Commit**: `git commit -m "feat: ..."`
+6. **Create PR**: `tea pulls create --title "..." --description "..."`
+```
+
+---
+
+### 3. Missing Skill References
+
+**Bad:**
+
+```markdown
+Use the gitea skill to create an issue.
+```
+
+**Why it's bad:**
+- Skills have ~20% auto-activation rate
+- Claude might not load the skill
+- Inconsistent results
+
+**Good:**
+
+```markdown
+@~/.claude/skills/gitea/SKILL.md
+
+Use `tea issues create --title "..." --description "..."`
+```
+
+**The `@` reference guarantees the skill content is loaded.**
+
+---
+
+### 4. God Skills
+
+**Bad:** Single 1500-line skill covering everything
+
+```
+skills/database/SKILL.md (1500 lines)
+- PostgreSQL
+- MySQL
+- MongoDB
+- Redis
+- All queries
+- All optimization tips
+- All schemas
+```
+
+**Why it's bad:**
+- Exceeds recommended 500 lines
+- Loads everything even if you need one thing
+- Hard to maintain
+- Wastes tokens
+
+**Good:** Progressive disclosure
+
+```
+skills/database/
+├── SKILL.md (200 lines - overview)
+├── reference/
+│   ├── postgres.md
+│   ├── mysql.md
+│   ├── mongodb.md
+│   └── redis.md
+└── schemas/
+    ├── users.md
+    ├── products.md
+    └── orders.md
+```
+
+Claude loads only what's needed.
+
+---
+
+### 5. Premature Agent Creation
+
+**Bad:** Creating an agent for every task
+
+```
+agents/
+├── issue-viewer/
+├── branch-creator/
+├── commit-maker/
+├── pr-creator/
+└── readme-updater/
+```
+
+**Why it's bad:**
+- Overhead of spawning agents
+- Most tasks don't need isolation
+- Harder to follow workflow
+- Slower execution
+
+**Good:** Use agents only when needed:
+- Context isolation (parallel work)
+- Skill composition (multiple skills together)
+- Specialist persona (architecture review)
+
+**Simple tasks → Skills**
+**Complex isolated work → Agents**
+
+---
+
+### 6. Verbose Explanations
+
+**Bad:**
+
+```markdown
+Git is a distributed version control system that was created by Linus Torvalds in 2005. It allows multiple developers to work on the same codebase simultaneously while maintaining a complete history of all changes. When you want to save your changes, you use the git commit command, which creates a snapshot of your current working directory...
+```
+
+**Why it's bad:**
+- Wastes tokens
+- Claude already knows git
+- Slows down loading
+- Adds no value
+
+**Good:**
+
+```markdown
+`git commit -m 'feat: add feature'`
+```
+
+**Assume Claude is smart. Only add domain-specific context.**
+
+---
+
+## Instruction Anti-Patterns
+
+### 7. Offering Too Many Options
+
+**Bad:**
+
+```markdown
+You can use pypdf, or pdfplumber, or PyMuPDF, or pdf2image, or camelot, or tabula, or...
+```
+
+**Why it's bad:**
+- Decision paralysis
+- Inconsistent choices
+- No clear default
+
+**Good:**
+
+```markdown
+Use pdfplumber for text extraction:
+
+\`\`\`python
+import pdfplumber
+with pdfplumber.open("file.pdf") as pdf:
+    text = pdf.pages[0].extract_text()
+\`\`\`
+
+For scanned PDFs requiring OCR, use pdf2image + pytesseract instead.
+```
+
+**Provide default, mention alternative only when needed.**
+
+---
+
+### 8. Time-Sensitive Information
+
+**Bad:**
+
+```markdown
+If you're doing this before August 2025, use the old API.
+After August 2025, use the new API.
+```
+
+**Why it's bad:**
+- Will become wrong
+- Requires maintenance
+- Confusing after the date
+
+**Good:**
+
+```markdown
+## Current Method
+Use v2 API: `api.example.com/v2/messages`
+
+## Old Patterns
+<details>
+<summary>Legacy v1 API (deprecated 2025-08)</summary>
+The v1 API: `api.example.com/v1/messages`
+No longer supported.
+</details>
+```
+
+---
+
+### 9. Inconsistent Terminology
+
+**Bad:** Mixing terms for the same thing
+
+```markdown
+1. Get the API endpoint
+2. Call the URL
+3. Hit the API route
+4. Query the path
+```
+
+**Why it's bad:**
+- Confusing
+- Looks like different things
+- Harder to search
+
+**Good:** Pick one term and stick with it
+
+```markdown
+1. Get the API endpoint
+2. Call the API endpoint
+3. Check the API endpoint response
+4. Retry the API endpoint if needed
+```
+
+---
+
+### 10. Windows-Style Paths
+
+**Bad:**
+
+```markdown
+Run: `scripts\helper.py`
+See: `reference\guide.md`
+```
+
+**Why it's bad:**
+- Fails on Unix systems
+- Causes errors on Mac/Linux
+
+**Good:**
+
+```markdown
+Run: `scripts/helper.py`
+See: `reference/guide.md`
+```
+
+**Always use forward slashes. They work everywhere.**
+
+---
+
+## Script Anti-Patterns
+
+### 11. Punting to Claude
+
+**Bad script:**
+
+```python
+def process_file(path):
+    return open(path).read()  # Let Claude handle errors
+```
+
+**Why it's bad:**
+- Script fails with no helpful message
+- Claude has to guess what happened
+- Inconsistent error handling
+
+**Good script:**
+
+```python
+def process_file(path):
+    try:
+        with open(path) as f:
+            return f.read()
+    except FileNotFoundError:
+        print(f"ERROR: File {path} not found")
+        print("Creating default file...")
+        with open(path, 'w') as f:
+            f.write('')
+        return ''
+    except PermissionError:
+        print(f"ERROR: Cannot access {path}")
+        print("Using default value")
+        return ''
+```
+
+**Scripts should solve problems, not punt to Claude.**
+
+---
+
+### 12. Magic Numbers
+
+**Bad:**
+
+```bash
+TIMEOUT=47  # Why 47?
+RETRIES=5   # Why 5?
+DELAY=3.7   # Why 3.7?
+```
+
+**Why it's bad:**
+- No one knows why these values
+- Hard to adjust
+- "Voodoo constants"
+
+**Good:**
+
+```bash
+# HTTP requests typically complete in <30s
+# Extra buffer for slow connections
+TIMEOUT=30
+
+# Three retries balances reliability vs speed
+# Most intermittent failures resolve by retry 2
+RETRIES=3
+
+# Exponential backoff: 1s, 2s, 4s
+INITIAL_DELAY=1
+```
+
+**Document why each value is what it is.**
+
+---
+
+## Model Selection Anti-Patterns
+
+### 13. Always Using Sonnet/Opus
+
+**Bad:**
+
+```yaml
+---
+name: dashboard
+model: opus  # "Just to be safe"
+---
+```
+
+**Why it's bad:**
+- 60x more expensive than Haiku
+- 5x slower
+- Wasted cost for simple task
+
+**Good:**
+
+```yaml
+---
+name: dashboard
+model: haiku  # Tested: 5/5 tests passed
+---
+```
+
+**Test with Haiku first. Only upgrade if needed.**
+
+---
+
+### 14. Never Testing Haiku
+
+**Bad:**
+
+```yaml
+---
+name: review-pr
+model: sonnet  # Assumed it needs Sonnet, never tested Haiku
+---
+```
+
+**Why it's bad:**
+- Might work fine with Haiku
+- Missing 12x cost savings
+- Missing 2.5x speed improvement
+
+**Good:**
+
+```yaml
+---
+name: review-pr
+model: haiku  # Tested: Haiku 4/5 (80%), good enough!
+---
+```
+
+Or:
+
+```yaml
+---
+name: review-pr
+model: sonnet  # Tested: Haiku 2/5 (40%), Sonnet 4/5 (80%)
+---
+```
+
+**Always test Haiku first, document results.**
+
+---
+
+## Progressive Disclosure Anti-Patterns
+
+### 15. Deeply Nested References
+
+**Bad:**
+
+```
+SKILL.md → advanced.md → details.md → actual-info.md
+```
+
+**Why it's bad:**
+- Claude may partially read nested files
+- Information might be incomplete
+- Hard to navigate
+
+**Good:**
+
+```
+SKILL.md → {advanced.md, reference.md, examples.md}
+```
+
+**Keep references one level deep from SKILL.md.**
+
+---
+
+### 16. No Table of Contents for Long Files
+
+**Bad:** 500-line reference file with no structure
+
+```markdown
+# Reference
+
+(500 lines of content with no navigation)
+```
+
+**Why it's bad:**
+- Hard to preview
+- Claude might miss sections
+- User can't navigate
+
+**Good:**
+
+```markdown
+# Reference
+
+## Contents
+- Authentication and setup
+- Core methods
+- Advanced features
+- Error handling
+- Examples
+
+## Authentication and Setup
+...
+```
+
+**Files >100 lines should have TOC.**
+
+---
+
+## Checklist to Avoid Anti-Patterns
+
+Before publishing a skill:
+
+- [ ] Not overly broad (does one thing well)
+- [ ] Instructions are specific (not vague)
+- [ ] Skill references use `@` syntax
+- [ ] Under 500 lines (or uses progressive disclosure)
+- [ ] Only creates agents when needed
+- [ ] Concise (assumes Claude knows basics)
+- [ ] Provides default, not 10 options
+- [ ] No time-sensitive information
+- [ ] Consistent terminology
+- [ ] Forward slashes for paths
+- [ ] Scripts handle errors, don't punt
+- [ ] No magic numbers in scripts
+- [ ] Tested with Haiku first
+- [ ] References are one level deep
+- [ ] Long files have table of contents
diff --git a/skills/capability-writing/reference/frontmatter-fields.md b/skills/capability-writing/reference/frontmatter-fields.md
new file mode 100644
index 0000000..202732c
--- /dev/null
+++ b/skills/capability-writing/reference/frontmatter-fields.md
@@ -0,0 +1,278 @@
+# Frontmatter Fields Reference
+
+Complete documentation of all available frontmatter fields for skills and agents.
+
+## Skill Frontmatter
+
+### Required Fields
+
+#### `name`
+- **Type:** string
+- **Required:** Yes
+- **Format:** Lowercase, hyphens only, no spaces
+- **Max length:** 64 characters
+- **Must match:** Directory name
+- **Cannot contain:** XML tags, reserved words ("anthropic", "claude")
+- **Example:** `work-issue`, `code-review`, `gitea`
+
+#### `description`
+- **Type:** string (multiline supported with `>`)
+- **Required:** Yes
+- **Max length:** 1024 characters
+- **Cannot contain:** XML tags
+- **Should include:**
+  - What the skill does
+  - When to use it
+  - Trigger conditions
+- **Example:**
+  ```yaml
+  description: >
+    View, create, and manage Gitea issues and pull requests.
+    Use when working with issues, PRs, or when user mentions tea, gitea, issue numbers.
+  ```
+
+#### `user-invocable`
+- **Type:** boolean
+- **Required:** Yes
+- **Values:** `true` or `false`
+- **Usage:**
+  - `true`: User can trigger with `/skill-name`
+  - `false`: Background skill, auto-loaded when needed
+
+### Optional Fields
+
+#### `model`
+- **Type:** string
+- **Required:** No
+- **Values:** `haiku`, `sonnet`, `opus`
+- **Default:** Inherits from parent (usually haiku)
+- **Guidance:** Default to `haiku`, only upgrade if needed
+- **Example:**
+  ```yaml
+  model: haiku  # 12x cheaper than sonnet
+  ```
+
+#### `argument-hint`
+- **Type:** string
+- **Required:** No (only for user-invocable skills)
+- **Format:** `<required>` for required params, `[optional]` for optional
+- **Shows in UI:** Helps users know what arguments to provide
+- **Example:**
+  ```yaml
+  argument-hint: <issue-number>
+  argument-hint: <issue-number> [optional-title]
+  ```
+
+#### `context`
+- **Type:** string
+- **Required:** No
+- **Values:** `fork`
+- **Usage:** Set to `fork` for skills needing isolated context
+- **When to use:** Heavy exploration tasks that would pollute main context
+- **Example:**
+  ```yaml
+  context: fork  # For arch-review-repo, deep exploration
+  ```
+
+#### `allowed-tools`
+- **Type:** list of strings
+- **Required:** No
+- **Usage:** Restrict which tools the skill can use
+- **Example:**
+  ```yaml
+  allowed-tools:
+    - Read
+    - Bash
+    - Grep
+  ```
+- **Note:** Rarely used, most skills have all tools
+
+## Agent Frontmatter
+
+### Required Fields
+
+#### `name`
+- **Type:** string
+- **Required:** Yes
+- **Same rules as skill name**
+
+#### `description`
+- **Type:** string
+- **Required:** Yes
+- **Should include:**
+  - What the agent does
+  - When to spawn it
+- **Example:**
+  ```yaml
+  description: >
+    Automated code review of pull requests for quality, bugs, security, and style.
+    Spawn when reviewing PRs or checking code quality.
+  ```
+
+### Optional Fields
+
+#### `model`
+- **Type:** string
+- **Required:** No
+- **Values:** `haiku`, `sonnet`, `opus`, `inherit`
+- **Default:** `inherit` (uses parent's model)
+- **Guidance:**
+  - Default to `haiku` for simple agents
+  - Use `sonnet` for balanced performance
+  - Reserve `opus` for deep reasoning
+- **Example:**
+  ```yaml
+  model: haiku  # Fast and cheap for code review checklist
+  ```
+
+#### `skills`
+- **Type:** comma-separated list of skill names (not paths)
+- **Required:** No
+- **Usage:** Auto-load these skills when agent spawns
+- **Format:** Just skill names, not paths
+- **Example:**
+  ```yaml
+  skills: gitea, issue-writing, code-review
+  ```
+- **Note:** Agent runtime loads skills automatically
+
+#### `disallowedTools`
+- **Type:** list of tool names
+- **Required:** No
+- **Common use:** Make agents read-only
+- **Example:**
+  ```yaml
+  disallowedTools:
+    - Edit
+    - Write
+  ```
+- **When to use:** Analysis agents that shouldn't modify code
+
+#### `permissionMode`
+- **Type:** string
+- **Required:** No
+- **Values:** `default`, `bypassPermissions`
+- **Usage:** Rarely used, for agents that need to bypass permission prompts
+- **Example:**
+  ```yaml
+  permissionMode: bypassPermissions
+  ```
+
+## Examples
+
+### Minimal User-Invocable Skill
+
+```yaml
+---
+name: dashboard
+description: Show open issues, PRs, and CI status.
+user-invocable: true
+---
+```
+
+### Full-Featured Skill
+
+```yaml
+---
+name: work-issue
+description: >
+  Implement a Gitea issue with full workflow: branch, plan, code, PR, review.
+  Use when implementing issues or when user says /work-issue.
+model: haiku
+argument-hint: <issue-number>
+user-invocable: true
+---
+```
+
+### Background Skill
+
+```yaml
+---
+name: gitea
+description: >
+  View, create, and manage Gitea issues and PRs using tea CLI.
+  Use when working with issues, PRs, viewing issue details, or when user mentions tea, gitea, issue numbers.
+user-invocable: false
+---
+```
+
+### Read-Only Agent
+
+```yaml
+---
+name: code-reviewer
+description: >
+  Automated code review of pull requests for quality, bugs, security, style, and test coverage.
+model: sonnet
+skills: gitea, code-review
+disallowedTools:
+  - Edit
+  - Write
+---
+```
+
+### Implementation Agent
+
+```yaml
+---
+name: issue-worker
+description: >
+  Autonomously implements a single issue in an isolated git worktree.
+model: haiku
+skills: gitea, issue-writing, software-architecture
+---
+```
+
+## Validation Rules
+
+### Name Validation
+- Must be lowercase
+- Must use hyphens (not underscores or spaces)
+- Cannot contain: `anthropic`, `claude`
+- Cannot contain XML tags `<`, `>`
+- Max 64 characters
+- Must match directory name exactly
+
+### Description Validation
+- Cannot be empty
+- Max 1024 characters
+- Cannot contain XML tags
+- Should end with period
+
+### Model Validation
+- Must be one of: `haiku`, `sonnet`, `opus`, `inherit`
+- Case-sensitive (must be lowercase)
+
+## Common Mistakes
+
+**Bad: Using paths in skills field**
+```yaml
+skills: ~/.claude/skills/gitea/SKILL.md  # Wrong!
+```
+
+**Good: Just skill names**
+```yaml
+skills: gitea, issue-writing
+```
+
+**Bad: Reserved word in name**
+```yaml
+name: claude-helper  # Contains "claude"
+```
+
+**Good: Descriptive name**
+```yaml
+name: code-helper
+```
+
+**Bad: Vague description**
+```yaml
+description: Helps with stuff
+```
+
+**Good: Specific description**
+```yaml
+description: >
+  Analyze Excel spreadsheets, create pivot tables, generate charts.
+  Use when analyzing Excel files, spreadsheets, or .xlsx files.
+```
diff --git a/skills/capability-writing/reference/model-selection.md b/skills/capability-writing/reference/model-selection.md
new file mode 100644
index 0000000..8d16a51
--- /dev/null
+++ b/skills/capability-writing/reference/model-selection.md
@@ -0,0 +1,336 @@
+# Model Selection Guide
+
+Detailed guidance on choosing the right model for skills and agents.
+
+## Cost Comparison
+
+| Model | Input (per MTok) | Output (per MTok) | vs Haiku |
+|-------|------------------|-------------------|----------|
+| **Haiku** | $0.25 | $1.25 | Baseline |
+| **Sonnet** | $3.00 | $15.00 | 12x more expensive |
+| **Opus** | $15.00 | $75.00 | 60x more expensive |
+
+**Example cost for typical skill call (2K input, 1K output):**
+- Haiku: $0.00175
+- Sonnet: $0.021 (12x more)
+- Opus: $0.105 (60x more)
+
+## Speed Comparison
+
+| Model | Tokens/Second | vs Haiku |
+|-------|---------------|----------|
+| **Haiku** | ~100 | Baseline |
+| **Sonnet** | ~40 | 2.5x slower |
+| **Opus** | ~20 | 5x slower |
+
+## Decision Framework
+
+```
+Start with Haiku by default
+    |
+    v
+Test on 3-5 representative tasks
+    |
+    +-- Success rate ≥80%? ---------> ✓ Use Haiku
+    |                                  (12x cheaper, 2-5x faster)
+    |
+    +-- Success rate <80%? --------> Try Sonnet
+    |                                    |
+    |                                    v
+    |                              Test on same tasks
+    |                                    |
+    |                                    +-- Success ≥80%? --> Use Sonnet
+    |                                    |
+    |                                    +-- Still failing? --> Opus or redesign
+    |
+    v
+Document why you chose the model
+```
+
+## When Haiku Works Well
+
+### ✓ Ideal for Haiku
+
+**Simple sequential workflows:**
+- `/dashboard` - Fetch and display
+- `/roadmap` - List and format
+- `/commit` - Generate message from diff
+
+**Workflows with scripts:**
+- Error-prone operations in scripts
+- Skills just orchestrate script calls
+- Validation is deterministic
+
+**Structured outputs:**
+- Tasks with clear templates
+- Format is defined upfront
+- No ambiguous formatting
+
+**Reference/knowledge skills:**
+- `gitea` - CLI reference
+- `issue-writing` - Patterns and templates
+- `software-architecture` - Best practices
+
+### Examples of Haiku Success
+
+**work-issue skill:**
+- Sequential steps (view → branch → plan → implement → PR)
+- Each step has clear validation
+- Scripts handle error-prone operations
+- Success rate: ~90%
+
+**dashboard skill:**
+- Fetch data (tea commands)
+- Format as table
+- Clear, structured output
+- Success rate: ~95%
+
+## When to Use Sonnet
+
+### Use Sonnet When
+
+**Haiku fails 20%+ of the time**
+- Test with Haiku first
+- If success rate <80%, upgrade to Sonnet
+
+**Complex judgment required:**
+- Code review (quality assessment)
+- Issue grooming (clarity evaluation)
+- Architecture decisions
+
+**Nuanced reasoning:**
+- Understanding implicit requirements
+- Making trade-off decisions
+- Applying context-dependent rules
+
+### Examples of Sonnet Success
+
+**review-pr skill:**
+- Requires code understanding
+- Judgment about quality/bugs
+- Context-dependent feedback
+- Originally tried Haiku: 65% success → Sonnet: 85%
+
+**issue-worker agent:**
+- Autonomous implementation
+- Pattern matching
+- Architectural decisions
+- Originally tried Haiku: 70% success → Sonnet: 82%
+
+## When to Use Opus
+
+### Reserve Opus For
+
+**Deep architectural reasoning:**
+- `software-architect` agent
+- Pattern recognition across large codebases
+- Identifying subtle anti-patterns
+- Trade-off analysis
+
+**High-stakes decisions:**
+- Breaking changes analysis
+- System-wide refactoring plans
+- Security architecture review
+
+**Complex pattern recognition:**
+- Requires sophisticated understanding
+- Multiple layers of abstraction
+- Long-term implications
+
+### Examples of Opus Success
+
+**software-architect agent:**
+- Analyzes entire codebase
+- Identifies 8 different anti-patterns
+- Provides prioritized recommendations
+- Sonnet: 68% success → Opus: 88%
+
+**arch-review-repo skill:**
+- Comprehensive architecture audit
+- Cross-cutting concerns
+- System-wide patterns
+- Opus justified for depth
+
+## Making Haiku More Effective
+
+If Haiku is struggling, try these improvements **before** upgrading to Sonnet:
+
+### 1. Add Validation Steps
+
+**Instead of:**
+```markdown
+3. Implement changes and create PR
+```
+
+**Try:**
+```markdown
+3. Implement changes
+4. Validate: Run `./scripts/validate.sh` (tests pass, linter clean)
+5. Create PR: `./scripts/create-pr.sh`
+```
+
+### 2. Bundle Error-Prone Operations in Scripts
+
+**Instead of:**
+```markdown
+5. Create PR: `tea pulls create --title "..." --description "..."`
+```
+
+**Try:**
+```markdown
+5. Create PR: `./scripts/create-pr.sh $issue "$title"`
+```
+
+### 3. Add Structured Output Templates
+
+**Instead of:**
+```markdown
+Show the results
+```
+
+**Try:**
+```markdown
+Format results as:
+
+| Issue | Status | Link |
+|-------|--------|------|
+| ... | ... | ... |
+```
+
+### 4. Add Explicit Checklists
+
+**Instead of:**
+```markdown
+Review the code for quality
+```
+
+**Try:**
+```markdown
+Check:
+- [ ] Code quality (readability, naming)
+- [ ] Bugs (edge cases, null checks)
+- [ ] Tests (coverage, assertions)
+```
+
+### 5. Make Instructions More Concise
+
+**Instead of:**
+```markdown
+Git is a version control system. When you want to commit changes, you use the git commit command which saves your changes to the repository...
+```
+
+**Try:**
+```markdown
+`git commit -m 'feat: add feature'`
+```
+
+## Testing Methodology
+
+### Create Test Suite
+
+For each skill, create 3-5 test cases:
+
+**Example: work-issue skill tests**
+1. Simple bug fix issue
+2. New feature with acceptance criteria
+3. Issue missing acceptance criteria
+4. Issue with tests that fail
+5. Complex refactoring task
+
+### Test with Haiku
+
+```bash
+# Set skill to Haiku
+model: haiku
+
+# Run all 5 tests
+# Document success/failure for each
+```
+
+### Measure Success Rate
+
+```
+Success rate = (Successful tests / Total tests) × 100
+```
+
+**Decision:**
+- ≥80% → Keep Haiku
+- <80% → Try Sonnet
+- <50% → Likely need Opus or redesign
+
+### Test with Sonnet (if needed)
+
+```bash
+# Upgrade to Sonnet
+model: sonnet
+
+# Run same 5 tests
+# Compare results
+```
+
+### Document Decision
+
+```yaml
+---
+name: work-issue
+model: haiku  # Tested: 4/5 tests passed with Haiku (80%)
+---
+```
+
+Or:
+
+```yaml
+---
+name: review-pr
+model: sonnet  # Tested: Haiku 3/5 (60%), Sonnet 4/5 (80%)
+---
+```
+
+## Common Patterns
+
+### Pattern: Start Haiku, Upgrade if Needed
+
+**Issue-worker agent evolution:**
+1. **V1 (Haiku):** 70% success - struggled with pattern matching
+2. **Analysis:** Added more examples, still 72%
+3. **V2 (Sonnet):** 82% success - better code understanding
+4. **Decision:** Keep Sonnet, document why
+
+### Pattern: Haiku for Most, Sonnet for Complex
+
+**Review-pr skill:**
+- Static analysis steps: Haiku could handle
+- Manual code review: Needs Sonnet judgment
+- **Decision:** Use Sonnet for whole skill (simplicity)
+
+### Pattern: Split Complex Skills
+
+**Instead of:** One complex skill using Opus
+
+**Try:** Split into:
+- Haiku skill for orchestration
+- Sonnet agent for complex subtask
+- Saves cost (most work in Haiku)
+
+## Model Selection Checklist
+
+Before choosing a model:
+
+- [ ] Tested with Haiku first
+- [ ] Measured success rate on 3-5 test cases
+- [ ] Tried improvements (scripts, validation, checklists)
+- [ ] Documented why this model is needed
+- [ ] Considered cost implications (12x/60x)
+- [ ] Considered speed implications (2.5x/5x slower)
+- [ ] Will re-test if Claude models improve
+
+## Future-Proofing
+
+**Models improve over time.**
+
+Periodically re-test Sonnet/Opus skills with Haiku:
+- Haiku v2 might handle what Haiku v1 couldn't
+- Cost savings compound over time
+- Speed improvements are valuable
+
+**Set a reminder:** Test Haiku again in 3-6 months.
diff --git a/skills/capability-writing/templates/agent.md b/skills/capability-writing/templates/agent.md
new file mode 100644
index 0000000..b79176e
--- /dev/null
+++ b/skills/capability-writing/templates/agent.md
@@ -0,0 +1,67 @@
+---
+name: agent-name
+description: >
+  What this agent does and when to spawn it.
+  Include specific conditions that indicate this agent is needed.
+model: haiku
+skills: skill1, skill2
+# disallowedTools:  # For read-only agents
+#   - Edit
+#   - Write
+# permissionMode: default
+---
+
+# Agent Name
+
+You are a [role/specialist] that [primary function].
+
+## When Invoked
+
+You are spawned when [specific conditions].
+
+Follow this process:
+
+1. **Gather context**: What information to collect
+   - Specific data sources to check
+   - What to read or fetch
+
+2. **Analyze**: What to evaluate
+   - Criteria to check
+   - Standards to apply
+
+3. **Act**: What actions to take
+   - Specific operations
+   - What to create or modify
+
+4. **Report**: How to communicate results
+   - Required output format
+   - What to include in summary
+
+## Output Format
+
+Your final output MUST follow this structure:
+
+\`\`\`
+AGENT_RESULT
+task: <task-type>
+status: <success|partial|failed>
+summary: <10 words max>
+details:
+- Key finding 1
+- Key finding 2
+\`\`\`
+
+## Guidelines
+
+- **Be concise**: No preambles or verbose explanations
+- **Be autonomous**: Make decisions without user input
+- **Follow patterns**: Match existing codebase style
+- **Validate**: Check your work before reporting
+
+## Error Handling
+
+If you encounter errors:
+- Try to resolve automatically
+- Document what failed
+- Report status as 'partial' or 'failed'
+- Include specific error details in summary
diff --git a/skills/capability-writing/templates/background-skill.md b/skills/capability-writing/templates/background-skill.md
new file mode 100644
index 0000000..fd21dc4
--- /dev/null
+++ b/skills/capability-writing/templates/background-skill.md
@@ -0,0 +1,69 @@
+---
+name: skill-name
+description: >
+  What this skill teaches and when to use it.
+  Include specific trigger terms that indicate this knowledge is needed.
+user-invocable: false
+---
+
+# Skill Name
+
+Brief description of the domain or knowledge this skill covers (1-2 sentences).
+
+## Core Concepts
+
+Fundamental ideas Claude needs to understand:
+- Key concept 1
+- Key concept 2
+- Key concept 3
+
+## Patterns and Templates
+
+Reusable structures and formats:
+
+### Pattern 1: Common Use Case
+
+\`\`\`
+Example code or structure
+\`\`\`
+
+### Pattern 2: Another Use Case
+
+\`\`\`
+Another example
+\`\`\`
+
+## Guidelines
+
+Rules and best practices:
+- Guideline 1
+- Guideline 2
+- Guideline 3
+
+## Examples
+
+### Example 1: Simple Case
+
+\`\`\`
+Concrete example showing the skill in action
+\`\`\`
+
+### Example 2: Complex Case
+
+\`\`\`
+More advanced example
+\`\`\`
+
+## Common Mistakes
+
+Pitfalls to avoid:
+- **Mistake 1**: Why it's wrong and what to do instead
+- **Mistake 2**: Why it's wrong and what to do instead
+
+## Reference
+
+Quick-reference tables or checklists:
+
+| Command | Purpose | Example |
+|---------|---------|---------|
+| ... | ... | ... |
diff --git a/skills/capability-writing/templates/helper-script.sh b/skills/capability-writing/templates/helper-script.sh
new file mode 100644
index 0000000..c9a8272
--- /dev/null
+++ b/skills/capability-writing/templates/helper-script.sh
@@ -0,0 +1,86 @@
+#!/bin/bash
+# script-name.sh - Brief description of what this script does
+#
+# Usage: script-name.sh <param1> <param2> [optional-param]
+#
+# Example:
+#   script-name.sh value1 value2
+#   script-name.sh value1 value2 optional-value
+#
+# Exit codes:
+#   0 - Success
+#   1 - Invalid arguments or general error
+#   2 - Specific error condition (document what)
+
+set -e  # Exit immediately on error
+# set -x  # Uncomment for debugging
+
+# Color output for better visibility
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# Helper functions
+error() {
+    echo -e "${RED}ERROR: $1${NC}" >&2
+    exit 1
+}
+
+success() {
+    echo -e "${GREEN}SUCCESS: $1${NC}"
+}
+
+warn() {
+    echo -e "${YELLOW}WARNING: $1${NC}"
+}
+
+# Input validation
+if [ $# -lt 2 ]; then
+    echo "Usage: $0 <param1> <param2> [optional-param]"
+    echo ""
+    echo "Description: Brief description of what this does"
+    echo ""
+    echo "Arguments:"
+    echo "  param1        Description of param1"
+    echo "  param2        Description of param2"
+    echo "  optional-param  Description of optional param (default: value)"
+    exit 1
+fi
+
+# Parse arguments
+PARAM1=$1
+PARAM2=$2
+OPTIONAL_PARAM=${3:-"default-value"}
+
+# Validate inputs
+if [ -z "$PARAM1" ]; then
+    error "param1 cannot be empty"
+fi
+
+# Main logic
+main() {
+    echo "Processing with param1=$PARAM1, param2=$PARAM2..."
+
+    # Step 1: Describe what this step does
+    if ! some_command "$PARAM1"; then
+        error "Failed to process param1"
+    fi
+
+    # Step 2: Another operation with error handling
+    result=$(another_command "$PARAM2" 2>&1)
+    if [ $? -ne 0 ]; then
+        error "Failed to process param2: $result"
+    fi
+
+    # Step 3: Validation
+    if [ ! -f "$result" ]; then
+        error "Expected file not found: $result"
+    fi
+
+    success "Operation completed successfully"
+    echo "$result"  # Output for caller to parse
+}
+
+# Execute main function
+main
diff --git a/skills/capability-writing/templates/user-invocable-skill.md b/skills/capability-writing/templates/user-invocable-skill.md
new file mode 100644
index 0000000..facc2f9
--- /dev/null
+++ b/skills/capability-writing/templates/user-invocable-skill.md
@@ -0,0 +1,65 @@
+---
+name: skill-name
+description: >
+  Clear description of what this skill does and when to use it.
+  Use when [specific trigger conditions] or when user says /skill-name.
+model: haiku
+argument-hint: <required-param> [optional-param]
+user-invocable: true
+# context: fork  # Use for skills needing isolated context
+# allowed-tools:  # Restrict tools if needed
+#   - Read
+#   - Bash
+---
+
+# Skill Title
+
+@~/.claude/skills/relevant-background-skill/SKILL.md
+
+Brief intro explaining the skill's purpose (1-2 sentences max).
+
+## Process
+
+1. **First step**: Clear action with specific command or instruction
+   - `command or tool to use`
+   - What to look for or validate
+
+2. **Second step**: Next action
+   - Specific details
+   - Expected output
+
+3. **Ask for approval** before significant actions
+   - Show what will be created/modified
+   - Wait for user confirmation
+
+4. **Execute** the approved actions
+   - Run commands/create files
+   - Handle errors gracefully
+
+5. **Present results** with links and summary
+   - Structured output (table or list)
+   - Links to created resources
+
+## Guidelines
+
+- Keep responses concise
+- Use structured output (tables, lists)
+- No preambles or sign-offs
+- Validate inputs before acting
+
+## Output Format
+
+Use this structure for responses:
+
+\`\`\`
+## Summary
+[1-2 sentences]
+
+## Results
+| Item | Status | Link |
+|------|--------|------|
+| ... | ... | ... |
+
+## Next Steps
+- ...
+\`\`\`
diff --git a/skills/create-capability/SKILL.md b/skills/create-capability/SKILL.md
index 954bd64..334502a 100644
--- a/skills/create-capability/SKILL.md
+++ b/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