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. A capability may be a single component or a cohesive set (skill + agent).

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

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

## Component Templates

### User-Invocable Skill Template

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

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

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

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

### 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 skills and agents, balanced performance | /work-issue, code-reviewer |
| `opus` | Deep reasoning, architectural analysis, complex judgment | /arch-review-repo |

### Decision Criteria

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

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

## Referencing Skills

### In User-Invocable Skills

Use the `@` 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.

### 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 (User-Invocable Skills)

Always ask before significant actions:

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

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

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/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:

- `docs/writing-capabilities.md` - Complete guide covering skills and agents

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

### 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 (not just `inherit`)
- [ ] `skills` list is right-sized (not too many)
- [ ] File at `agents/<name>/AGENT.md`