architecture/docs/writing-skills.md

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:

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

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

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

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

# Project Management
How to manage issues, PRs, releases, and documentation...

Better:

# Issue Writing
How to write clear, actionable issues.

2. Be Specific, Not Vague

Provide concrete patterns, not abstract principles.

Vague:

## Writing Good Titles
Titles should be clear and descriptive.

Specific:

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

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

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

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

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

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

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

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

# 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: How skills fit into the overall system
• VISION.md: The philosophy behind composable components