Writing Skills (Excellence)

⚡ Quick Decision Tree

What do you need to do?

1. 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
2. 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)
3. Verify Compliance:
   • Check metadata/naming -> Standards
   • Add tests -> Testing Guide

📚 Component Index

🛠️ 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

1. Identify goal → Use decision tree above
2. Select template → From

   references/templates/

3. Apply CSO → Optimize description for discovery
4. Add anti-rationalization → For discipline skills
5. Test → RED-GREEN-REFACTOR cycle

Quick Example

---
name: my-technique
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

metadata.triggers

creating-skills

references/

✅ Pre-Deploy Checklist

• name

  field matches directory name exactly

• SKILL.md

  filename is ALL CAPS
• Description starts with "Use when..."

• metadata.triggers

  has 3+ keywords
• Total lines < 500 (use

  references/

  for more)
• No

  @

  force-loading in cross-references
• Tested with real scenarios

🔗 Related Skills

• opencode-expert: For OpenCode environment configuration
• Use

  /write-skill

  command for guided skill creation

Examples

mkdir -p ~/.config/opencode/skills/my-technique
touch ~/.config/opencode/skills/my-technique/SKILL.md

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