architecture/docs/writing-skills.md

# Writing Skills

A guide to creating reusable knowledge modules for the Claude Code AI workflow system.

> **Official Documentation**: For the most up-to-date information, see https://code.claude.com/docs/en/skills

## What is a Skill?

Skills are **model-invoked knowledge modules**—Claude automatically applies them when your request matches their description. Unlike commands (which require explicit `/command` invocation), skills are triggered automatically based on semantic matching.

## YAML Frontmatter (Required)

Every `SKILL.md` file **must** start with YAML frontmatter. This is how Claude discovers and triggers skills.

### Format Requirements

- Must start with `---` on **line 1** (no blank lines before it)
- Must end with `---` before the markdown content
- Use spaces for indentation (not tabs)

### Required Fields

| Field | Required | Description |
|-------|----------|-------------|
| `name` | **Yes** | Lowercase letters, numbers, and hyphens only (max 64 chars). Should match directory name. |
| `description` | **Yes** | What the skill does and when to use it (max 1024 chars). **This is critical for triggering.** |

### Optional Fields

| Field | Description |
|-------|-------------|
| `allowed-tools` | **Restricts** which tools Claude can use when this skill is active. If omitted, no restrictions apply. |
| `model` | Specific model to use when skill is active (e.g., `claude-sonnet-4-20250514`). |

### Writing Effective Descriptions

The `description` field determines when Claude applies the skill. A good description answers:

1. **What does this skill do?** List specific capabilities.
2. **When should Claude use it?** Include trigger terms users would mention.

**Bad (too vague):**
```yaml
description: Helps with documents
```

**Good (specific with trigger terms):**
```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, adding comments, merging PRs, or when the user mentions tea, gitea, issue numbers, or PR numbers.
```

### Example Frontmatter

```yaml
---
name: gitea
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.
---

# Gitea CLI (tea)

[Rest of skill content...]
```

## Subagents and Skills

Subagents **do not automatically inherit skills** from the main conversation. To give a subagent access to skills, list them in the agent's `skills` field:

```yaml
---
name: code-reviewer
description: Review code for quality and best practices
skills: gitea, code-review
---
```

## File Structure

Skills live in the `skills/` directory, each in its own folder:

```
skills/
├── gitea/
│   └── SKILL.md
├── issue-writing/
│   └── SKILL.md
├── backlog-grooming/
│   └── SKILL.md
└── roadmap-planning/
    └── SKILL.md
```

### Why SKILL.md?

The uppercase `SKILL.md` filename:
- Makes the skill file immediately visible in directory listings
- Follows a consistent convention across all skills
- Clearly identifies the primary file in a skill folder

### Supporting Files (Optional)

A skill folder can contain additional files if needed:

```
skills/
└── complex-skill/
    ├── SKILL.md           # Main skill document (required)
    ├── templates/         # Template files
    │   └── example.md
    └── examples/          # Extended examples
        └── case-study.md
```

However, prefer keeping everything in `SKILL.md` when possible—it's easier to maintain and reference.

## Skill Document Structure

A well-structured `SKILL.md` follows this pattern:

```markdown
# Skill Name

Brief description of what this skill covers.

## Core Concepts
Explain the 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.
```

Not every skill needs all sections—include what's relevant. Some skills are primarily patterns (like `issue-writing`), others are reference-heavy (like `gitea`).

## How Skills are Discovered and Triggered

Skills are **model-invoked**: Claude decides which skills to use based on your request.

### Discovery Process

1. **At startup**: Claude loads only the `name` and `description` of each available skill
2. **On request**: Claude matches your request against skill descriptions using semantic similarity
3. **Activation**: When a match is found, Claude asks to use the skill before loading the full content

### Subagent Access

Subagents (defined in `.claude/agents/`) must explicitly list which skills they can use:

```yaml
---
name: product-manager
description: Manages backlog and roadmap
skills: gitea, issue-writing, backlog-grooming, roadmap-planning
---
```

**Important**: Built-in agents and the Task tool do not have access to skills. Only custom subagents with an explicit `skills` field can use them.

### Skills Can Reference Other Skills

Skills can mention other skills for related knowledge:

```markdown
# Roadmap Planning

...

When creating issues, follow the patterns in the **issue-writing** skill.
Use **gitea** commands to create the issues.
```

This creates a natural knowledge hierarchy without duplicating content.

## Naming Conventions

### Skill Folder Names

- Use **kebab-case**: `issue-writing`, `backlog-grooming`
- Be **descriptive**: name should indicate the skill's domain
- Be **concise**: 2-3 words is ideal
- Avoid generic names: `utils`, `helpers`, `common`

Good names:
- `gitea` - Tool-specific knowledge
- `issue-writing` - Activity-focused
- `backlog-grooming` - Process-focused
- `roadmap-planning` - Task-focused

### Skill Titles

The H1 title in `SKILL.md` should match the folder name in Title Case:

| Folder | Title |
|--------|-------|
| `gitea` | Forgejo CLI (fj) |
| `issue-writing` | Issue Writing |
| `backlog-grooming` | Backlog Grooming |
| `roadmap-planning` | Roadmap Planning |

## Best Practices

### 1. Keep Skills Focused

Each skill should cover **one domain, one concern**. If your skill document is getting long or covers multiple unrelated topics, consider splitting it.

**Too broad:**
```markdown
# Project Management
How to manage issues, PRs, releases, and documentation...
```

**Better:**
```markdown
# Issue Writing
How to write clear, actionable issues.
```

### 2. Be Specific, Not Vague

Provide concrete patterns, not abstract principles.

**Vague:**
```markdown
## Writing Good Titles
Titles should be clear and descriptive.
```

**Specific:**
```markdown
## Writing Good Titles
- Start with action verb: "Add", "Fix", "Update", "Remove"
- Be specific: "Add user authentication" not "Auth stuff"
- Keep under 60 characters
```

### 3. Include Actionable Examples

Every guideline should have an example showing what it looks like in practice.

```markdown
### Acceptance Criteria

Good criteria are:
- **Specific**: "User sees error message" not "Handle errors"
- **Testable**: Can verify pass/fail
- **User-focused**: What the user experiences

Examples:
- [ ] Login form validates email format before submission
- [ ] Invalid credentials show "Invalid email or password" message
- [ ] Successful login redirects to dashboard
```

### 4. Use Templates for Repeatability

When the skill involves creating structured content, provide copy-paste templates:

```markdown
### Feature Request Template

\```markdown
## Summary
What feature and why it's valuable.

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2

## Context
Additional background or references.
\```
```

### 5. Include Checklists for Verification

Checklists help ensure consistent quality:

```markdown
## Grooming Checklist

For each issue, verify:
- [ ] Starts with action verb
- [ ] Has acceptance criteria
- [ ] Scope is clear
- [ ] Dependencies identified
```

### 6. Document Common Mistakes

Help avoid pitfalls by documenting what goes wrong:

```markdown
## Common Mistakes

### Vague Titles
- Bad: "Fix bug"
- Good: "Fix login form validation on empty email"

### Missing Acceptance Criteria
Every issue needs specific, testable criteria.
```

### 7. Keep It Current

Skills should reflect current practices. When workflows change:
- Update the skill document
- Remove obsolete patterns
- Add new best practices

## Annotated Examples

Let's examine the existing skills to understand effective patterns.

### Example 1: gitea (Tool Reference)

The `gitea` skill is a **tool reference**—it documents how to use a specific CLI tool.

```markdown
# Forgejo CLI (fj)

Command-line interface for interacting with Forgejo repositories.

## Authentication
The `tea` CLI authenticates via `tea auth login`. Credentials are stored locally.

## Common Commands

### Issues
\```bash
# List issues
tea issue search -s open              # Open issues
tea issue search -s closed            # Closed issues
...
\```
```

**Key patterns:**
- Organized by feature area (Issues, Pull Requests, Repository)
- Includes actual command syntax with comments
- Covers common use cases, not exhaustive documentation
- Tips section for non-obvious behaviors

### Example 2: issue-writing (Process Knowledge)

The `issue-writing` skill is **process knowledge**—it teaches how to do something well.

```markdown
# Issue Writing

How to write clear, actionable issues.

## Issue Structure

### Title
- Start with action verb: "Add", "Fix", "Update", "Remove"
- Be specific: "Add user authentication" not "Auth stuff"
- Keep under 60 characters

### Description
\```markdown
## Summary
One paragraph explaining what and why.

## Acceptance Criteria
- [ ] Specific, testable requirement
...
\```
```

**Key patterns:**
- Clear guidelines with specific rules
- Templates for different issue types
- Good/bad examples for each guideline
- Covers the full lifecycle (structure, criteria, labels, dependencies)

### Example 3: backlog-grooming (Workflow Checklist)

The `backlog-grooming` skill is a **workflow checklist**—it provides a systematic process.

```markdown
# Backlog Grooming

How to review and improve existing issues.

## Grooming Checklist

For each issue, verify:

### 1. Title Clarity
- [ ] Starts with action verb
- [ ] Specific and descriptive
- [ ] Understandable without reading description
...
```

**Key patterns:**
- Structured as a checklist with categories
- Each item is a yes/no verification
- Includes workflow steps (Grooming Workflow section)
- Questions to guide decision-making

### Example 4: roadmap-planning (Strategy Guide)

The `roadmap-planning` skill is a **strategy guide**—it teaches how to think about a problem.

```markdown
# Roadmap Planning

How to plan features and create issues for implementation.

## Planning Process

### 1. Understand the Goal
- What capability or improvement is needed?
- Who benefits and how?
- What's the success criteria?

### 2. Break Down the Work
- Identify distinct components
- Define boundaries between pieces
...
```

**Key patterns:**
- Process-oriented with numbered steps
- Multiple breakdown strategies (by layer, by user story, by component)
- Concrete examples showing the pattern applied
- Questions to guide planning decisions

## When to Create a New Skill

Create a skill when you find yourself:

1. **Explaining the same concepts repeatedly** across different conversations
2. **Wanting consistent quality** in a specific area
3. **Building up domain expertise** that should persist
4. **Needing a reusable reference** for commands or agents

### Signs You Need a New Skill

- You're copy-pasting the same guidelines
- Multiple commands need the same knowledge
- Quality is inconsistent without explicit guidance
- There's a clear domain that doesn't fit existing skills

### Signs You Don't Need a New Skill

- The knowledge is only used once
- It's already covered by an existing skill
- It's too generic to be actionable
- It's better as part of a command's instructions

## Skill Lifecycle

### 1. Draft

Start with the essential content:
- Core patterns and templates
- Key guidelines
- A few examples

### 2. Refine

As you use the skill, improve it:
- Add examples from real usage
- Clarify ambiguous guidelines
- Remove unused content

### 3. Maintain

Keep skills current:
- Update when practices change
- Remove obsolete patterns
- Add newly discovered best practices

## Checklist: Before Submitting a New Skill

### Frontmatter (Critical)
- [ ] YAML frontmatter starts on line 1 (no blank lines before `---`)
- [ ] `name` field uses lowercase letters, numbers, and hyphens only
- [ ] `name` matches the directory name
- [ ] `description` lists specific capabilities
- [ ] `description` includes "Use when..." with trigger terms

### File Structure
- [ ] File is at `skills/<name>/SKILL.md`
- [ ] Name follows kebab-case convention

### Content Quality
- [ ] Skill focuses on a single domain
- [ ] Guidelines are specific and actionable
- [ ] Examples illustrate each major point
- [ ] Templates are provided where appropriate
- [ ] Common mistakes are documented

### Integration
- [ ] Skill is listed in relevant subagent `skills` fields if needed

## See Also

- [ARCHITECTURE.md](../ARCHITECTURE.md): How skills fit into the overall system
- [VISION.md](../VISION.md): The philosophy behind composable components