writing-skills

name	writing-skills
description	Guide for creating, updating, or improving RooCode agent skills with templates and best practices.
risk	safe
source	self
tags	["meta","skill-authoring","templates","best-practices"]

Writing Skills (Excellence)

Dispatcher for skill creation excellence. Use the decision tree below to find the right template and standards.

Respond in the user's configured language.

⚡ 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

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

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]."
risk: safe
source: self
tags: [category, keyword1, keyword2]
---

# My Technique

## When to Use
- [Symptom A]
- [Error message]

Common Mistakes

Mistake	Fix
Description summarizes workflow	Use "Use when..." triggers only
No tags in frontmatter	Add 3+ keyword tags
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:

• name field matches directory name exactly
• SKILL.md filename is ALL CAPS
• Description is <200 chars, starts with verb or "Use when..."
• tags has 3+ keywords
• risk is set (safe or moderate)
• Total lines < 500 (use references/ for more)
• No @ force-loading in cross-references
• Tested with real scenarios

🔗 Related Skills

• skill-check: For validating skill compliance with RooCode Agent Skills spec

Examples

Create a Tier 1 skill (RooCode global):

~/.roo/skills/my-technique/SKILL.md

Create a Tier 2 skill (RooCode project):

<workspace>/.roo/skills/my-skill/SKILL.md
<workspace>/.roo/skills/my-skill/references/core/README.md