diff --git a/docs/writing-skills.md b/docs/writing-skills.md
new file mode 100644
index 0000000..8869a30
--- /dev/null
+++ b/docs/writing-skills.md
@@ -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