Writing Skills

1---
2name: writing-skills
3description: Use when creating, updating, or improving agent skills.
4metadata:
5  category: meta
6  author: ozy
7  triggers: new skill, create skill, update skill, skill documentation, skill template,
8    agent skill, writing skill
9  references: anti-rationalization, cso, standards, templates, testing, tier-1-simple,
10    tier-2-expanded, tier-3-platform
11---
12 
13# Writing Skills (Excellence)
14 
15Dispatcher for skill creation excellence. Use the decision tree below to find the right template and standards.
16 
17## ⚡ Quick Decision Tree
18 
19### What do you need to do?
20 
211. **Create a NEW skill:**
22   - Is it simple (single file, <200 lines)? → [Tier 1 Architecture](references/tier-1-simple/README.md)
23   - Is it complex (multi-concept, 200-1000 lines)? → [Tier 2 Architecture](references/tier-2-expanded/README.md)
24   - Is it a massive platform (10+ products, AWS, Convex)? → [Tier 3 Architecture](references/tier-3-platform/README.md)
25 
262. **Improve an EXISTING skill:**
27   - Fix "it's too long" -> [Modularize (Tier 3)](references/templates/tier-3-platform.md)
28   - Fix "AI ignores rules" -> [Anti-Rationalization](references/anti-rationalization/README.md)
29   - Fix "users can't find it" -> [CSO (Search Optimization)](references/cso/README.md)
30 
313. **Verify Compliance:**
32   - Check metadata/naming -> [Standards](references/standards/README.md)
33   - Add tests -> [Testing Guide](references/testing/README.md)
34 
35## 📚 Component Index
36 
37| Component | Purpose |
38|-----------|---------|
39| **[CSO](references/cso/README.md)** | "SEO for LLMs". How to write descriptions that trigger. |
40| **[Standards](references/standards/README.md)** | File naming, YAML frontmatter, directory structure. |
41| **[Anti-Rationalization](references/anti-rationalization/README.md)**| How to write rules that agents won't ignore. |
42| **[Testing](references/testing/README.md)** | How to ensure your skill actually works. |
43 
44## 🛠️ Templates
45 
46- [Technique Skill](references/templates/technique.md) (How-to)
47- [Reference Skill](references/templates/reference.md) (Docs)
48- [Discipline Skill](references/templates/discipline.md) (Rules)
49- [Pattern Skill](references/templates/pattern.md) (Design Patterns)
50 
51## When to Use
52 
53- Creating a NEW skill from scratch
54- Improving an EXISTING skill that agents ignore
55- Debugging why a skill isn't being triggered
56- Standardizing skills across a team
57 
58## How It Works
59 
601. **Identify goal** → Use decision tree above
612. **Select template** → From `references/templates/`
623. **Apply CSO** → Optimize description for discovery
634. **Add anti-rationalization** → For discipline skills
645. **Test** → RED-GREEN-REFACTOR cycle
65 
66## Quick Example
67 
68```yaml
69---
70name: my-technique
71description: Use when [specific symptom occurs].
72metadata:
73  category: technique
74  triggers: error-text, symptom, tool-name
75---
76 
77# My Technique
78 
79## When to Use
80- [Symptom A]
81- [Error message]
82```
83 
84## Common Mistakes
85 
86| Mistake | Fix |
87|---------|-----|
88| Description summarizes workflow | Use "Use when..." triggers only |
89| No `metadata.triggers` | Add 3+ keywords |
90| Generic name ("helper") | Use gerund (`creating-skills`) |
91| Long monolithic SKILL.md | Split into `references/` |
92 
93See [gotchas.md](gotchas.md) for more.
94 
95## ✅ Pre-Deploy Checklist
96 
97Before deploying any skill:
98 
99- [ ] `name` field matches directory name exactly
100- [ ] `SKILL.md` filename is ALL CAPS
101- [ ] Description starts with "Use when..."
102- [ ] `metadata.triggers` has 3+ keywords
103- [ ] Total lines < 500 (use `references/` for more)
104- [ ] No `@` force-loading in cross-references
105- [ ] Tested with real scenarios
106 
107## 🔗 Related Skills
108 
109- **[opencode-expert](skill://opencode-expert)**: For OpenCode environment configuration
110- Use `/write-skill` command for guided skill creation
111 
112## Examples
113 
114**Create a Tier 1 skill:**
115```bash
116mkdir -p ~/.config/opencode/skills/my-technique
117touch ~/.config/opencode/skills/my-technique/SKILL.md
118```
119 
120**Create a Tier 2 skill:**
121```bash
122mkdir -p ~/.config/opencode/skills/my-skill/references/core
123touch ~/.config/opencode/skills/my-skill/{SKILL.md,gotchas.md}
124touch ~/.config/opencode/skills/my-skill/references/core/README.md
125```
126