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. Supports YAML-style lists.
model	Specific model to use when skill is active (e.g., sonnet, opus, haiku).
user-invocable	Whether the skill appears in the / command menu. Defaults to true. Set to false for reference-only skills.
context	Execution context. Use fork to run skill in an isolated sub-agent context, preventing context pollution.
agent	Agent type to use for execution. Allows skills to specify which agent handles them.
hooks	Define PreToolUse, PostToolUse, or Stop hooks scoped to this skill's lifecycle.

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

description: Helps with documents

Good (specific with trigger terms):

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

---
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.
user-invocable: false
---

# Gitea CLI (tea)

[Rest of skill content...]

Advanced Frontmatter Examples

Reference skill (not directly invocable):

---
name: gitea
description: CLI reference for Gitea operations.
user-invocable: false
---

Skill with isolated context:

---
name: codebase-analysis
description: Deep codebase exploration and analysis.
context: fork
model: haiku
---

Skill with tool restrictions (YAML-style list):

---
name: read-only-review
description: Code review without modifications.
allowed-tools:
  - Read
  - Glob
  - Grep
---

Skill with hooks:

---
name: database-operations
description: Database schema and migration operations.
hooks:
  - type: PreToolUse
    matcher: Bash
    command: echo "Validating database command..."
---

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:

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

# 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

Hot Reload

Skills support automatic hot-reload. When you create or modify a skill file in ~/.claude/skills/ or .claude/skills/, the changes are immediately available without restarting Claude Code. This enables rapid iteration when developing skills.

Visibility in Command Menu

By default, skills in /skills/ directories appear in the / slash command menu. Users can invoke them directly like commands. To hide a skill from the menu (e.g., for reference-only skills), add user-invocable: false to the frontmatter.

Subagent Access

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

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

# 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

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

Optional Frontmatter (Consider)

• user-invocable: false if skill is reference-only (e.g., CLI docs)
• context: fork if skill does heavy exploration that would pollute context
• model if skill benefits from a specific model (e.g., haiku for speed)
• allowed-tools if skill should be restricted to certain tools
• hooks if skill needs validation or logging

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