# Writing Skills

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

## What is a Skill?

Skills are **knowledge modules**—focused documents that teach Claude how to do something well. Unlike commands (which define workflows) or agents (which execute tasks), skills are passive: they encode domain expertise, patterns, and best practices that can be referenced when needed.

Think of skills as the "how-to guides" that inform Claude's work. A skill doesn't act on its own—it provides the knowledge that commands and agents use to complete their tasks effectively.

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

Skills are loaded by **explicit reference**. When a command or agent mentions a skill by name, Claude reads the skill file to gain that knowledge.

### Referenced by Commands

Commands reference skills in their instructions:

```markdown
# Groom Issues

Use the **backlog-grooming** and **issue-writing** skills to review and improve issues.

1. Fetch open issues...
```

When this command runs, Claude reads both referenced skills before proceeding.

### Referenced by Agents

Agents list their skills explicitly:

```markdown
# Product Manager Agent

## Skills
- gitea
- issue-writing
- backlog-grooming
- roadmap-planning
```

When spawned, the agent has access to all listed skills as part of its context.

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

- [ ] File is at `skills/<name>/SKILL.md`
- [ ] Name follows kebab-case convention
- [ ] 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
- [ ] Skill is referenced by at least one command or agent

## See Also

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