architecture/skills/capability-writing/SKILL.md

---
name: capability-writing
description: >
  Guide for designing and creating capabilities for the architecture repository.
  A capability is a cohesive set of components (skill + agent).
  Use when creating new skills, agents, or extending the
  AI workflow system. Includes templates, design guidance, and conventions.
user-invocable: false
---

# Capability Writing

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

| Component | Location | Purpose | Example |
|-----------|----------|---------|---------|
| **User-invocable Skill** | `skills/name/SKILL.md` | Workflow users trigger with `/name` | /work-issue, /dashboard |
| **Background Skill** | `skills/name/SKILL.md` | Knowledge auto-loaded when needed | gitea, issue-writing |
| **Agent** | `agents/name/AGENT.md` | Isolated subtask handler | code-reviewer |

## When to Use Each Component

### Decision Tree

```
Start here: What do you need?
    |
    +--> Just knowledge to apply automatically?
    |        --> Background skill (user-invocable: false)
    |
    +--> User-initiated workflow?
    |        --> User-invocable skill (user-invocable: true)
    |
    +--> Complex isolated work needing focused context?
    |        --> User-invocable skill + Agent
    |
    +--> New domain expertise + workflow + isolated work?
             --> Full capability (background skill + user-invocable skill + agent)
```

**Detailed decision criteria:** See [best-practices.md](best-practices.md)

## Component Templates

### User-Invocable Skill Template

```yaml
---
name: skill-name
description: >
  What this skill does and when to use it.
  Use when [trigger conditions] or when user says /skill-name.
model: haiku
argument-hint: <required> [optional]
user-invocable: true
---

# Skill Title

@~/.claude/skills/relevant-skill/SKILL.md

Brief intro if needed.

1. **First step**: What to do
2. **Second step**: What to do next
3. **Ask for approval** before significant actions
4. **Execute** the approved actions
5. **Present results** with links and summary
```

**Complete template with all fields:** See [templates/user-invocable-skill.md](templates/user-invocable-skill.md)

### Background Skill Template

```yaml
---
name: skill-name
description: >
  What this skill teaches and when to use it.
  Include trigger conditions in description.
user-invocable: false
---

# Skill Name

Brief description of what this skill covers.

## Core Concepts
## Patterns and Templates
## Guidelines
## Examples
```

**Complete template:** See [templates/background-skill.md](templates/background-skill.md)

### Agent Template

```yaml
---
name: agent-name
description: What this agent does and when to spawn it
model: haiku
skills: skill1, skill2
disallowedTools:
  - Edit  # For read-only agents
  - Write
---

You are a [role] specialist that [primary function].

## When Invoked
1. **Gather context**
2. **Analyze**
3. **Act**
4. **Report**
```

**Complete template:** See [templates/agent.md](templates/agent.md)

**Helper script template:** See [templates/helper-script.sh](templates/helper-script.sh)

## Structure Examples

### Simple Skill (< 300 lines, no scripts)
```
skills/simple-skill/
└── SKILL.md
```

### Progressive Disclosure (with reference files)
```
skills/complex-skill/
├── SKILL.md (~200 lines)
├── reference/
│   ├── detailed-guide.md
│   └── api-reference.md
└── examples/
    └── usage-examples.md
```

### With Bundled Scripts
```
skills/skill-with-scripts/
├── SKILL.md
├── reference/
│   └── error-handling.md
└── scripts/
    ├── validate.sh
    └── process.sh
```

**Detailed examples:** See [examples/](examples/) folder

## Referencing Skills

### In User-Invocable Skills

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" - file references guarantee the content is available.

### In Agents

List skill names in frontmatter (not paths):

```yaml
---
name: product-manager
skills: gitea, issue-writing, backlog-grooming
---
```

## Common Patterns

### Approval Workflow
```markdown
4. **Present plan** for approval
5. **If approved**, create the issues
6. **Present summary** with links
```

### Conditional Behavior
```markdown
## If issue number provided ($1):
1. Fetch specific issue
2. Process it

## If no argument (batch mode):
1. List all issues
2. Process each
```

### Spawning Agents
```markdown
9. **Auto-review**: Spawn the `code-reviewer` agent with the PR number
```

### Read-Only Agents
```yaml
---
name: code-reviewer
disallowedTools:
  - Edit
  - Write
---
```

## Quick Reference

**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)

## Naming Conventions

| 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` |

**Skills:** Name after domain/action (good: `gitea`, `work-issue`; bad: `utils`, `helpers`)
**Agents:** Name by role/persona (good: `code-reviewer`; bad: `helper`, `agent1`)

## Checklists

### Before Creating a User-Invocable Skill

- [ ] Workflow is used multiple times
- [ ] User explicitly triggers it (not automatic)
- [ ] Clear start and end points
- [ ] Frontmatter has `user-invocable: true`
- [ ] Description includes "Use when... or when user says /skill-name"
- [ ] 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

- [ ] Knowledge is used in multiple places (not just once)
- [ ] Existing skills do not already cover this domain
- [ ] Content is specific and actionable (not generic)
- [ ] Frontmatter has `user-invocable: false`
- [ ] Description includes trigger terms
- [ ] File at `skills/<name>/SKILL.md`

### Before Creating an Agent

- [ ] Built-in agents (Explore, Plan) are not sufficient
- [ ] Context isolation or skill composition is needed
- [ ] Clear role/persona emerges
- [ ] `model` selection is deliberate (default to `haiku`)
- [ ] `skills` list is right-sized (not too many)
- [ ] File at `agents/<name>/AGENT.md`