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 + command + agent).
  Use when creating new skills, commands, or agents, or when 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. A capability is often a cohesive set of components (skill + command + agent) that work together.

## Component Overview

| Component | Location | Purpose | Example |
|-----------|----------|---------|---------|
| **Skill** | `skills/name/SKILL.md` | Knowledge Claude applies automatically | software-architecture |
| **Command** | `commands/name.md` | User-invoked workflow entry point | /work-issue |
| **Agent** | `agents/name/AGENT.md` | Isolated subtask handler with focused context | code-reviewer |

## When to Use Each Component

### Decision Tree

```
Start here: What do you need?
    |
    +--> Just knowledge to apply automatically?
    |        --> Skill only
    |
    +--> User-initiated workflow using existing knowledge?
    |        --> Command (reference skills via @)
    |
    +--> Complex isolated work needing focused context?
    |        --> Command + Agent (agent uses skills)
    |
    +--> New domain expertise + workflow + isolated work?
             --> Full capability (all three)
```

### Decision Matrix

| Need | Component | Example |
|------|-----------|---------|
| Knowledge Claude should apply automatically | Skill | software-architecture, issue-writing |
| User-invoked workflow | Command | /work-issue, /dashboard |
| Isolated subtask with focused context | Agent | code-reviewer, issue-worker |
| All three working together | Full capability | arch-review (skill + command + agent) |

### Signs You Need Each Component

**Create a Skill when:**
- You explain the same concepts repeatedly
- Quality is inconsistent without explicit guidance
- Multiple commands need the same knowledge
- There is a clear domain that does not fit existing skills

**Create a Command 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

## Component Templates

### Skill Template

Location: `skills/<name>/SKILL.md`

```yaml
---
name: skill-name
description: >
  What this skill teaches and when to use it.
  Include trigger conditions in description (not body).
  List specific capabilities users would mention.
user-invocable: false
---

# Skill Name

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

**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` | No | Set `false` for reference-only skills |
| `model` | No | Specific model: `haiku`, `sonnet`, `opus` |
| `context` | No | Use `fork` for isolated context |
| `allowed-tools` | No | Restrict available tools |

### Command Template

Location: `commands/<name>.md`

```yaml
---
description: What this command does (one-line summary)
argument-hint: <required> [optional]
model: sonnet
---

# Command Title

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

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

**Frontmatter fields:**

| Field | Required | Description |
|-------|----------|-------------|
| `description` | Yes | One-line summary for help/listings |
| `argument-hint` | No | Shows expected args: `<required>`, `[optional]` |
| `model` | No | Override model: `haiku`, `sonnet`, `opus` |
| `context` | No | Use `fork` for isolated context |
| `allowed-tools` | No | Restrict available tools |

### Agent Template

Location: `agents/<name>/AGENT.md`

```yaml
---
name: agent-name
description: What this agent does and when to spawn it
model: sonnet
skills: skill1, skill2
disallowedTools:
  - Edit
  - 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
```

**Frontmatter fields:**

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

## Model Selection Guidance

| Model | Use When | Examples |
|-------|----------|----------|
| `haiku` | Simple fetch/display, formatting, mechanical tasks | /dashboard, /roadmap |
| `sonnet` | Most commands and agents, balanced performance | /work-issue, issue-worker, code-reviewer |
| `opus` | Deep reasoning, architectural analysis, complex judgment | software-architect, security auditor |

### Decision Criteria

- **Start with `sonnet`** - handles most tasks well
- **Use `haiku` for volume** - speed and cost matter at scale
- **Reserve `opus` for judgment** - when errors are costly or reasoning is complex
- **Consider the stakes** - higher consequence tasks warrant more capable models

## Naming Conventions

### File and Folder Names

| Component | Convention | Examples |
|-----------|------------|----------|
| Skill folder | kebab-case | `software-architecture`, `issue-writing` |
| Skill file | UPPERCASE | `SKILL.md` |
| Command file | kebab-case | `work-issue.md`, `review-pr.md` |
| Agent folder | kebab-case | `code-reviewer`, `issue-worker` |
| Agent file | UPPERCASE | `AGENT.md` |

### Naming Patterns

**Skills:** Name after the domain or knowledge area
- Good: `gitea`, `issue-writing`, `software-architecture`
- Bad: `utils`, `helpers`, `misc`

**Commands:** Use verb or verb-phrase (actions)
- Good: `work-issue`, `review-pr`, `create-issue`
- Bad: `issue-work`, `pr-review`, `issue`

**Agents:** Name by role or persona (recognizable specialist)
- Good: `code-reviewer`, `issue-worker`, `software-architect`
- Bad: `helper`, `do-stuff`, `agent1`

## Referencing Skills

### In Commands

Use the `@` file reference syntax to guarantee 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.

### In Agents

List skill names in the frontmatter (not paths):

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

The agent runtime loads these skills automatically.

## Common Patterns

### Approval Workflow (Commands)

Always ask before significant actions:

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

### Conditional Behavior (Commands)

Handle optional arguments with mode switching:

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

Delegate complex subtasks:

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

### Read-Only Agents

For analysis without modification:

```yaml
---
name: code-reviewer
disallowedTools:
  - Edit
  - Write
---
```

## Anti-Patterns to Avoid

### Overly Broad Components

**Bad:** One skill/command/agent that does everything
```markdown
# Project Management
Handles issues, PRs, releases, documentation, deployment...
```

**Good:** Focused components with clear responsibility
```markdown
# Issue Writing
How to write clear, actionable issues.
```

### 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 the `docs/` directory:

- `docs/writing-skills.md` - Complete skill writing guide
- `docs/writing-commands.md` - Complete command writing guide
- `docs/writing-agents.md` - Complete agent writing guide

These documents include:
- Full frontmatter reference
- Annotated examples from the codebase
- Lifecycle management
- Integration checklists

## Checklists

### Before Creating a 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 descriptive `description` with trigger terms
- [ ] File at `skills/<name>/SKILL.md`

### Before Creating a Command

- [ ] Workflow is repeatable (used multiple times)
- [ ] User explicitly triggers it (not automatic)
- [ ] Clear start and end points
- [ ] Skills referenced via `@~/.claude/skills/<name>/SKILL.md`
- [ ] Approval checkpoints before significant actions
- [ ] File at `commands/<name>.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 (not just `inherit`)
- [ ] `skills` list is right-sized (not too many)
- [ ] File at `agents/<name>/AGENT.md`