architecture/docs/writing-capabilities.md

# Writing Capabilities

A comprehensive guide to creating capabilities for the Claude Code AI workflow system.

> **Official Documentation**: For the most up-to-date Claude Code documentation, see https://code.claude.com/docs

## Component Types

The architecture repository uses two component types:

| Component | Location | Purpose | Invocation |
|-----------|----------|---------|------------|
| **Skill** | `skills/<name>/SKILL.md` | Knowledge modules and workflows | Auto-triggered or `/skill-name` |
| **Agent** | `agents/<name>/AGENT.md` | Isolated subtask handlers | Spawned via Task tool |

### Skills: Two Types

Skills come in two flavors based on the `user-invocable` frontmatter field:

| Type | `user-invocable` | Purpose | Example |
|------|------------------|---------|---------|
| **User-invocable** | `true` | Workflows users trigger with `/skill-name` | `/work-issue`, `/dashboard` |
| **Background** | `false` | Reference knowledge auto-loaded when needed | `gitea`, `issue-writing` |

User-invocable skills replaced the former "commands" - they define workflows that users trigger directly.

### Agents: Isolated Workers

Agents are specialized subprocesses that:
- Combine multiple skills into focused personas
- Run with isolated context (don't pollute main conversation)
- Handle complex subtasks autonomously
- Can run in parallel or background

---

## Writing Skills

Skills are markdown files in the `skills/` directory, each in its own folder.

### File Structure

```
skills/
├── gitea/                    # Background skill
│   └── SKILL.md
├── work-issue/               # User-invocable skill
│   └── SKILL.md
└── issue-writing/            # Background skill
    └── SKILL.md
```

### YAML Frontmatter

Every skill requires YAML frontmatter starting on line 1:

```yaml
---
name: skill-name
description: >
  What this skill does and when to use it.
  Include trigger terms for auto-detection.
model: haiku
user-invocable: true
argument-hint: <required-arg> [optional-arg]
---
```

#### Required Fields

| Field | Description |
|-------|-------------|
| `name` | Lowercase, hyphens only (max 64 chars). Must match directory name. |
| `description` | What the skill does + when to use (max 1024 chars). Critical for triggering. |

#### Optional Fields

| Field | Description |
|-------|-------------|
| `user-invocable` | Whether skill appears in `/` menu. Default: `true` |
| `model` | Model to use: `haiku`, `sonnet`, `opus` |
| `argument-hint` | For user-invocable: `<required>`, `[optional]` |
| `context` | Use `fork` for isolated context |
| `allowed-tools` | Restrict available tools (YAML list) |
| `hooks` | Define PreToolUse, PostToolUse, or Stop hooks |

### User-Invocable Skills (Workflows)

These replace the former "commands" - workflows users invoke with `/skill-name`.

**Example: `/work-issue`**

```yaml
---
name: work-issue
description: >
  Work on a Gitea issue. Fetches issue details and sets up branch.
  Use when working on issues, implementing features, or when user says /work-issue.
model: haiku
argument-hint: <issue-number>
user-invocable: true
---

# Work on Issue #$1

@~/.claude/skills/gitea/SKILL.md
@~/.claude/skills/software-architecture/SKILL.md

1. **View the issue** with `--comments` flag
2. **Create a branch**: `git checkout -b issue-$1-<short-title>`
3. **Plan**: Use TodoWrite to break down work
4. **Implement** following architectural patterns
5. **Commit** with message referencing the issue
6. **Push** and **Create PR**
```

**Key patterns for user-invocable skills:**

1. **Argument handling**: Use `$1`, `$2` for positional arguments
2. **Skill references**: Use `@~/.claude/skills/name/SKILL.md` to include background skills
3. **Approval workflows**: Ask before significant actions
4. **Clear steps**: Numbered, actionable workflow steps

### Background Skills (Reference)

Knowledge modules that Claude applies automatically when context matches.

**Example: `gitea`**

```yaml
---
name: gitea
description: >
  View, create, and manage Gitea issues and pull requests using tea CLI.
  Use when working with issues, PRs, or when user mentions tea, gitea.
model: haiku
user-invocable: false
---

# Gitea CLI (tea)

## Common Commands

### Issues
```bash
tea issues                    # List open issues
tea issues <number>           # View issue details
tea issues create --title "..." --description "..."
```
...
```

**Key patterns for background skills:**

1. **Rich descriptions**: Include trigger terms like tool names, actions
2. **Reference material**: Commands, templates, patterns, checklists
3. **No workflow steps**: Just knowledge, not actions

### Writing Effective Descriptions

The `description` field determines when Claude applies the skill. Include:

1. **What the skill does**: Specific capabilities
2. **When to use it**: Trigger terms users would mention

**Bad:**
```yaml
description: Helps with documents
```

**Good:**
```yaml
description: >
  View, create, and manage Gitea issues and pull requests using tea CLI.
  Use when working with issues, PRs, viewing issue details, creating pull
  requests, or when the user mentions tea, gitea, or issue numbers.
```

### Argument Handling (User-Invocable Skills)

User-invocable skills can accept arguments via `$1`, `$2`, etc.

**Argument hints:**
- `<arg>` - Required argument
- `[arg]` - Optional argument
- `<arg1> [arg2]` - Mix of both

**Example with optional argument:**
```yaml
---
name: groom
argument-hint: [issue-number]
---

# Groom Issues

## If issue number provided ($1):
1. Fetch that specific issue
2. Evaluate against checklist
...

## If no argument:
1. List all open issues
2. Review each against checklist
...
```

### Skill References

User-invocable skills include background skills using file references:

```markdown
@~/.claude/skills/gitea/SKILL.md
@~/.claude/skills/issue-writing/SKILL.md
```

**Important**: Do NOT use phrases like "Use the gitea skill" - skills have ~20% auto-activation rate. File references guarantee the content is loaded.

### Approval Workflows

User-invocable skills should ask for approval before significant actions:

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

---

## Writing Agents

Agents are specialized subprocesses that combine skills for complex, isolated tasks.

### File Structure

```
agents/
└── code-reviewer/
    └── AGENT.md
```

### YAML Frontmatter

```yaml
---
name: code-reviewer
description: Review code for quality, bugs, and style issues
model: sonnet
skills: gitea, code-review
disallowedTools:
  - Edit
  - Write
---
```

#### Required Fields

| Field | Description |
|-------|-------------|
| `name` | Agent identifier (lowercase, hyphens). Match directory name. |
| `description` | What the agent does. Used for matching when spawning. |

#### Optional Fields

| Field | Description |
|-------|-------------|
| `model` | `haiku`, `sonnet`, `opus`, or `inherit` |
| `skills` | Comma-separated skill names the agent can access |
| `disallowedTools` | Block specific tools (e.g., Edit, Write for read-only) |
| `permissionMode` | `default` or `bypassPermissions` |
| `hooks` | Define PreToolUse, PostToolUse, or Stop hooks |

### Agent Document Structure

```markdown
# Agent Name

Brief description of the agent's role.

## Skills
- skill1
- skill2

## Capabilities
What the agent can do.

## When to Use
Guidance on when to spawn this agent.

## Behavior
Operational rules and constraints.
```

### Built-in Agents

Claude Code provides built-in agents - prefer these before creating custom ones:

| Agent | Purpose |
|-------|---------|
| **Explore** | Codebase exploration, finding files, searching code |
| **Plan** | Implementation planning, architectural decisions |

### Skill Composition

Agents gain expertise by combining skills:

```
┌─────────────────────────────────────────┐
│         Code Reviewer Agent             │
│                                         │
│  ┌─────────┐  ┌─────────────┐           │
│  │ gitea   │  │ code-review │           │
│  │ CLI     │  │ patterns    │           │
│  └─────────┘  └─────────────┘           │
│                                         │
└─────────────────────────────────────────┘
```

### Use Cases for Agents

1. **Parallel processing**: Spawn multiple agents for independent tasks
2. **Context isolation**: Deep exploration without polluting main context
3. **Complex workflows**: Iterative decision-making with multiple skills
4. **Background execution**: Long-running tasks while user continues working

### Model Selection

| Model | Best For |
|-------|----------|
| `haiku` | Simple tasks, formatting, batch processing |
| `sonnet` | Most agent tasks, code review (default choice) |
| `opus` | Complex analysis, security audits, architectural decisions |

---

## Decision Guide

### When to Create a User-Invocable Skill

Create when you have:
- Repeatable workflow used multiple times
- User explicitly triggers the action
- Clear start and end points
- Approval checkpoints needed

### When to Create a Background Skill

Create when:
- You explain the same concepts repeatedly
- Multiple user-invocable skills need the same knowledge
- Quality is inconsistent without explicit guidance
- There's a clear domain that doesn't fit existing skills

### When to Create an Agent

Create when:
- Multiple skills needed together for complex tasks
- Context isolation required
- Parallel execution possible
- Autonomous exploration needed
- Specialist persona improves outputs

### Decision Matrix

| Scenario | Component | Reason |
|----------|-----------|--------|
| User types `/work-issue 42` | User-invocable skill | Explicit user trigger |
| Need tea CLI reference | Background skill | Auto-loaded knowledge |
| Review 20 issues in parallel | Agent | Batch processing, isolation |
| Create one issue | User-invocable skill | Single workflow |
| Deep architectural analysis | Agent | Complex, isolated work |

---

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

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

Explain fundamental ideas.

## Patterns and Templates

Provide reusable structures.

## Guidelines

List rules and best practices.

## Examples

Show concrete illustrations.

## Common Mistakes

Document pitfalls to avoid.
```

### Agent Template

```yaml
---
name: agent-name
description: What this agent does and when to spawn it
model: sonnet
skills: skill1, skill2
---

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

## When Invoked

1. **Gather context**: What 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
```

---

## Checklists

### Before Creating a User-Invocable Skill

- [ ] Workflow is repeatable (used multiple times)
- [ ] User explicitly triggers it
- [ ] File at `skills/<name>/SKILL.md`
- [ ] `user-invocable: true` in frontmatter
- [ ] `description` includes "Use when... or when user says /skill-name"
- [ ] Background skills referenced via `@~/.claude/skills/<name>/SKILL.md`
- [ ] Approval checkpoints before significant actions
- [ ] Clear numbered workflow steps

### Before Creating a Background Skill

- [ ] Knowledge used in multiple places
- [ ] Doesn't fit existing skills
- [ ] File at `skills/<name>/SKILL.md`
- [ ] `user-invocable: false` in frontmatter
- [ ] `description` includes trigger terms
- [ ] Content is specific and actionable

### Before Creating an Agent

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

---

## See Also

- [ARCHITECTURE.md](../ARCHITECTURE.md): How components fit together
- [skills/capability-writing/SKILL.md](../skills/capability-writing/SKILL.md): Quick reference