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:

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

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

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

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:

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

@~/.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:

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

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

# 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

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

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

---
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: How components fit together
• skills/capability-writing/SKILL.md: Quick reference