flowmade-one/architecture
3
0
Fork 0
Code Issues 15 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Add skill authoring guide

Browse Source 
Create docs/writing-skills.md with comprehensive documentation for
writing new skills:
- File structure and naming conventions
- How skills are loaded and referenced by commands/agents
- Best practices for composable, focused content
- Annotated examples from existing skills (forgejo, issue-writing,
  backlog-grooming, roadmap-planning)
- Checklist for new skill submissions

Closes #3

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Hugo Nijhuis
2025-12-28 23:41:03 +01:00
parent 9d8b5a7e06
commit 77a6480f44
1 changed files with 445 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

445
docs/writing-skills.md Normal file
View File

@@ -0,0 +1,445 @@
# 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/
├── forgejo/
│ └── 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 `forgejo`).
## 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
- forgejo
- 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 **forgejo** 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:
- `forgejo` - 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 |
|--------|-------|
| `forgejo` | 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: forgejo (Tool Reference)
The `forgejo` 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 `fj` CLI authenticates via `fj auth login`. Credentials are stored locally.
## Common Commands
### Issues
\```bash
# List issues
fj issue search -s open # Open issues
fj 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