Writing Skills (Excellence)
Dispatcher for skill creation excellence. Use the decision tree below to find the right template and standards.
⚡ Quick Decision Tree
What do you need to do?
Create a NEW skill:
- Is it simple (single file, <200 lines)? → Tier 1 Architecture
- Is it complex (multi-concept, 200-1000 lines)? → Tier 2 Architecture
- Is it a massive platform (10+ products, AWS, Convex)? → Tier 3 Architecture
Improve an EXISTING skill:
- Fix "it's too long" -> Modularize (Tier 3)
- Fix "AI ignores rules" -> Anti-Rationalization
- Fix "users can't find it" -> CSO (Search Optimization)
Verify Compliance:
- Check metadata/naming -> Standards
- Add tests -> Testing Guide
📚 Component Index
| Component |
Purpose |
| CSO |
"SEO for LLMs". How to write descriptions that trigger. |
| Standards |
File naming, YAML frontmatter, directory structure. |
| Anti-Rationalization |
How to write rules that agents won't ignore. |
| Testing |
How to ensure your skill actually works. |
🛠️ Templates
- Technique Skill (How-to)
- Reference Skill (Docs)
- Discipline Skill (Rules)
- Pattern Skill (Design Patterns)
When to Use
- Creating a NEW skill from scratch
- Improving an EXISTING skill that agents ignore
- Debugging why a skill isn't being triggered
- Standardizing skills across a team
How It Works
- Identify goal → Use decision tree above
- Select template → From
references/templates/
- Apply CSO → Optimize description for discovery
- Add anti-rationalization → For discipline skills
- Test → RED-GREEN-REFACTOR cycle
Quick Example
---
name: Writing Skills
description: Use when [specific symptom occurs].
metadata:
category: technique
triggers: error-text, symptom, tool-name
---
# My Technique
## When to Use
- [Symptom A]
- [Error message]
Common Mistakes
| Mistake |
Fix |
| Description summarizes workflow |
Use "Use when..." triggers only |
No metadata.triggers |
Add 3+ keywords |
| Generic name ("helper") |
Use gerund (creating-skills) |
| Long monolithic SKILL.md |
Split into references/ |
See gotchas.md for more.
✅ Pre-Deploy Checklist
Before deploying any skill:
🔗 Related Skills
- opencode-expert: For OpenCode environment configuration
- Use
/write-skill command for guided skill creation
Examples
Create a Tier 1 skill:
mkdir -p ~/.config/opencode/skills/my-technique
touch ~/.config/opencode/skills/my-technique/SKILL.md
Create a Tier 2 skill:
mkdir -p ~/.config/opencode/skills/my-skill/references/core
touch ~/.config/opencode/skills/my-skill/{SKILL.md,gotchas.md}
touch ~/.config/opencode/skills/my-skill/references/core/README.md
1---2name: writing-skills3description: "Use when creating, updating, or improving agent skills."4metadata:5 source: https://skillmd.com/skills/mayurrathi/writing-skills6 category: meta7 author: ozy8 triggers: new skill, create skill, update skill, skill documentation, skill template,9 agent skill, writing skill10 references: anti-rationalization, cso, standards, templates, testing, tier-1-simple,11 tier-2-expanded, tier-3-platform12risk: unknown13source: community14---1516# Writing Skills (Excellence)1718Dispatcher for skill creation excellence. Use the decision tree below to find the right template and standards.1920## ⚡ Quick Decision Tree2122### What do you need to do?23241. **Create a NEW skill:**25 - Is it simple (single file, <200 lines)? → [Tier 1 Architecture](references/tier-1-simple/README.md)26 - Is it complex (multi-concept, 200-1000 lines)? → [Tier 2 Architecture](references/tier-2-expanded/README.md)27 - Is it a massive platform (10+ products, AWS, Convex)? → [Tier 3 Architecture](references/tier-3-platform/README.md)28292. **Improve an EXISTING skill:**30 - Fix "it's too long" -> [Modularize (Tier 3)](references/templates/tier-3-platform.md)31 - Fix "AI ignores rules" -> [Anti-Rationalization](references/anti-rationalization/README.md)32 - Fix "users can't find it" -> [CSO (Search Optimization)](references/cso/README.md)33343. **Verify Compliance:**35 - Check metadata/naming -> [Standards](references/standards/README.md)36 - Add tests -> [Testing Guide](references/testing/README.md)3738## 📚 Component Index3940| Component | Purpose |41|-----------|---------|42| **[CSO](references/cso/README.md)** | "SEO for LLMs". How to write descriptions that trigger. |43| **[Standards](references/standards/README.md)** | File naming, YAML frontmatter, directory structure. |44| **[Anti-Rationalization](references/anti-rationalization/README.md)**| How to write rules that agents won't ignore. |45| **[Testing](references/testing/README.md)** | How to ensure your skill actually works. |4647## 🛠️ Templates4849- [Technique Skill](references/templates/technique.md) (How-to)50- [Reference Skill](references/templates/reference.md) (Docs)51- [Discipline Skill](references/templates/discipline.md) (Rules)52- [Pattern Skill](references/templates/pattern.md) (Design Patterns)5354## When to Use5556- Creating a NEW skill from scratch57- Improving an EXISTING skill that agents ignore58- Debugging why a skill isn't being triggered59- Standardizing skills across a team6061## How It Works62631. **Identify goal** → Use decision tree above642. **Select template** → From `references/templates/`653. **Apply CSO** → Optimize description for discovery664. **Add anti-rationalization** → For discipline skills675. **Test** → RED-GREEN-REFACTOR cycle6869## Quick Example7071```yaml72---73name: Writing Skills74description: Use when [specific symptom occurs].75metadata:76 category: technique77 triggers: error-text, symptom, tool-name78---7980# My Technique8182## When to Use83- [Symptom A]84- [Error message]85```8687## Common Mistakes8889| Mistake | Fix |90|---------|-----|91| Description summarizes workflow | Use "Use when..." triggers only |92| No `metadata.triggers` | Add 3+ keywords |93| Generic name ("helper") | Use gerund (`creating-skills`) |94| Long monolithic SKILL.md | Split into `references/` |9596See [gotchas.md](gotchas.md) for more.9798## ✅ Pre-Deploy Checklist99100Before deploying any skill:101102- [ ] `name` field matches directory name exactly103- [ ] `SKILL.md` filename is ALL CAPS104- [ ] Description starts with "Use when..."105- [ ] `metadata.triggers` has 3+ keywords106- [ ] Total lines < 500 (use `references/` for more)107- [ ] No `@` force-loading in cross-references108- [ ] Tested with real scenarios109110## 🔗 Related Skills111112- **opencode-expert**: For OpenCode environment configuration113- Use `/write-skill` command for guided skill creation114115## Examples116117**Create a Tier 1 skill:**118```bash119mkdir -p ~/.config/opencode/skills/my-technique120touch ~/.config/opencode/skills/my-technique/SKILL.md121```122123**Create a Tier 2 skill:**124```bash125mkdir -p ~/.config/opencode/skills/my-skill/references/core126touch ~/.config/opencode/skills/my-skill/{SKILL.md,gotchas.md}127touch ~/.config/opencode/skills/my-skill/references/core/README.md128```