Cursor rule

1---
2description: Meta-guide for creating effective Claude Code skills with proper structure, CSO optimization, and real examples
3tags: [meta, skill-creation, documentation, best-practices]
4---
5 
6# Creating Skills - Meta Guide
7 
8## Overview
9 
10**Skills are reference guides for proven techniques, patterns, or tools.** Write them to help future Claude instances quickly find and apply effective approaches.
11 
12Skills must be **discoverable** (Claude can find them), **scannable** (quick to evaluate), and **actionable** (clear examples).
13 
14**Core principle**: Default assumption is Claude is already very smart. Only add context Claude doesn't already have.
15 
16## When to Use
17 
18**Create a skill when:**
19- Technique wasn't intuitively obvious
20- Pattern applies broadly across projects
21- You'd reference this again
22- Others would benefit
23 
24**Don't create for:**
25- One-off solutions specific to single project
26- Standard practices well-documented elsewhere
27- Project conventions (put those in `.claude/CLAUDE.md` or `.cursor/rules`)
28 
29## Required Structure
30 
31### Frontmatter (YAML)
32 
33```yaml
34---
35name: skill-name-with-hyphens
36description: Use when [triggers/symptoms] - [what it does and how it helps]
37tags: relevant-tags
38---
39```
40 
41**Rules:**
42- Only `name` and `description` fields supported (max 1024 chars total)
43- Name: letters, numbers, hyphens only (no special chars). Use gerund form (verb + -ing)
44- Description: Third person, starts with "Use when..."
45- Include BOTH triggering conditions AND what skill does
46- Match specificity to task complexity (degrees of freedom)
47 
48### Document Structure
49 
50```markdown
51# Skill Name
52 
53## Overview
54Core principle in 1-2 sentences. What is this?
55 
56## When to Use
57- Bullet list with symptoms and use cases
58- When NOT to use
59 
60## Quick Reference
61Table or bullets for common operations
62 
63## Implementation
64Inline code for simple patterns
65Link to separate file for heavy reference (100+ lines)
66 
67## Common Mistakes
68What goes wrong + how to fix
69 
70## Real-World Impact (optional)
71Concrete results from using this technique
72```
73 
74## Degrees of Freedom
75 
76**Match specificity to task complexity:**
77 
78- **High freedom**: Flexible tasks requiring judgment
79  - Use broad guidance, principles, examples
80  - Let Claude adapt approach to context
81  - Example: "Use when designing APIs - provides REST principles and patterns"
82 
83- **Low freedom**: Fragile or critical operations
84  - Be explicit about exact steps
85  - Include validation checks
86  - Example: "Use when deploying to production - follow exact deployment checklist with rollback procedures"
87 
88**Red flag**: If skill tries to constrain Claude too much on creative tasks, reduce specificity. If skill is too vague on critical operations, add explicit steps.
89 
90## Claude Search Optimization (CSO)
91 
92**Critical:** Future Claude reads the description to decide if skill is relevant. Optimize for discovery.
93 
94### Description Best Practices
95 
96```yaml
97# ❌ BAD - Too vague, doesn't mention when to use
98description: For async testing
99 
100# ❌ BAD - First person (injected into system prompt)
101description: I help you with flaky tests
102 
103# ✅ GOOD - Triggers + what it does
104description: Use when tests have race conditions or pass/fail inconsistently - replaces arbitrary timeouts with condition polling for reliable async tests
105 
106# ✅ GOOD - Technology-specific with explicit trigger
107description: Use when using React Router and handling auth redirects - provides patterns for protected routes and auth state management
108```
109 
110### Keyword Coverage
111 
112Use words Claude would search for:
113- **Error messages**: "ENOENT", "Cannot read property", "Timeout"
114- **Symptoms**: "flaky", "hanging", "race condition", "memory leak"
115- **Synonyms**: "cleanup/teardown/afterEach", "timeout/hang/freeze"
116- **Tools**: Actual command names, library names, file types
117 
118### Naming Conventions
119 
120**Use gerund form (verb + -ing):**
121- ✅ `creating-skills` not `skill-creation`
122- ✅ `testing-with-subagents` not `subagent-testing`
123- ✅ `debugging-memory-leaks` not `memory-leak-debugging`
124- ✅ `processing-pdfs` not `pdf-processor`
125- ✅ `analyzing-spreadsheets` not `spreadsheet-analysis`
126 
127**Why gerunds work:**
128- Describes the action you're taking
129- Active and clear
130- Consistent with Anthropic conventions
131 
132**Avoid:**
133- ❌ Vague names like "Helper" or "Utils"
134- ❌ Passive voice constructions
135 
136## Code Examples
137 
138**One excellent example beats many mediocre ones.**
139 
140### Choose Language by Use Case
141 
142- Testing techniques → TypeScript/JavaScript
143- System debugging → Shell/Python
144- Data processing → Python
145- API calls → TypeScript/JavaScript
146 
147### Good Example Checklist
148 
149- [ ] Complete and runnable
150- [ ] Well-commented explaining **WHY** not just what
151- [ ] From real scenario (not contrived)
152- [ ] Shows pattern clearly
153- [ ] Ready to adapt (not generic template)
154- [ ] Shows both BAD (❌) and GOOD (✅) approaches
155- [ ] Includes realistic context/setup code
156 
157### Example Template
158 
159```typescript
160// ✅ GOOD - Clear, complete, ready to adapt
161interface RetryOptions {
162  maxAttempts: number;
163  delayMs: number;
164  backoff?: 'linear' | 'exponential';
165}
166 
167async function retryOperation<T>(
168  operation: () => Promise<T>,
169  options: RetryOptions
170): Promise<T> {
171  const { maxAttempts, delayMs, backoff = 'linear' } = options;
172 
173  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
174    try {
175      return await operation();
176    } catch (error) {
177      if (attempt === maxAttempts) throw error;
178 
179      const delay = backoff === 'exponential'
180        ? delayMs * Math.pow(2, attempt - 1)
181        : delayMs * attempt;
182 
183      await new Promise(resolve => setTimeout(resolve, delay));
184    }
185  }
186 
187  throw new Error('Unreachable');
188}
189 
190// Usage
191const data = await retryOperation(
192  () => fetchUserData(userId),
193  { maxAttempts: 3, delayMs: 1000, backoff: 'exponential' }
194);
195```
196 
197### Don't
198 
199- ❌ Implement in 5+ languages (you're good at porting)
200- ❌ Create fill-in-the-blank templates
201- ❌ Write contrived examples
202- ❌ Show only code without comments
203 
204## File Organization
205 
206### Self-Contained (Preferred)
207 
208```
209typescript-type-safety/
210  SKILL.md    # Everything inline
211```
212 
213**When:** All content fits in ~500 words, no heavy reference needed
214 
215### With Supporting Files
216 
217```
218api-integration/
219  SKILL.md           # Overview + patterns
220  retry-helpers.ts   # Reusable code
221  examples/
222    auth-example.ts
223    pagination-example.ts
224```
225 
226**When:** Reusable tools or multiple complete examples needed
227 
228## Token Efficiency
229 
230Skills load into every conversation. Keep them concise.
231 
232### Target Limits
233 
234- **SKILL.md**: Keep under 500 lines
235- Getting-started workflows: <150 words
236- Frequently-loaded skills: <200 words total
237- Other skills: <500 words
238 
239**Challenge each piece of information**: "Does Claude really need this explanation?"
240 
241### Compression Techniques
242 
243```markdown
244# ❌ BAD - Verbose (42 words)
245Your human partner asks: "How did we handle authentication errors in React Router before?"
246You should respond: "I'll search past conversations for React Router authentication patterns."
247Then dispatch a subagent with the search query: "React Router authentication error handling 401"
248 
249# ✅ GOOD - Concise (20 words)
250Partner: "How did we handle auth errors in React Router?"
251You: Searching...
252[Dispatch subagent → synthesis]
253```
254 
255**Techniques:**
256- Reference tool `--help` instead of documenting all flags
257- Cross-reference other skills instead of repeating content
258- Show minimal example of pattern
259- Eliminate redundancy
260- Use progressive disclosure (reference additional files as needed)
261 
262## Common Mistakes
263 
264| Mistake | Why It Fails | Fix |
265|---------|--------------|-----|
266| Narrative example | "In session 2025-10-03..." | Focus on reusable pattern |
267| Multi-language dilution | Same example in 5 languages | One excellent example |
268| Generic labels | helper1, helper2, step3 | Use semantic names |
269| Missing description triggers | "For testing" | "Use when tests are flaky..." |
270| First-person description | "I help you..." | "Use when... - provides..." |
271| Offering too many options | 10 different approaches | Focus on one proven approach |
272| Time-sensitive information | "As of 2025..." | Keep content evergreen |
273 
274## Workflow Recommendations
275 
276For multi-step processes, include:
277 
2781. **Clear sequential steps**: Break complex tasks into numbered operations
2792. **Feedback loops**: Build in verification/validation steps
2803. **Error handling**: What to check when things go wrong
2814. **Checklists**: For processes with many steps
282 
283**Example structure:**
284```markdown
285## Workflow
286 
2871. **Preparation**
288   - Check prerequisites
289   - Validate environment
290 
2912. **Execution**
292   - Step 1: [action + expected result]
293   - Step 2: [action + expected result]
294 
2953. **Verification**
296   - [ ] Check 1 passes
297   - [ ] Check 2 passes
298 
2994. **Rollback** (if needed)
300   - Steps to undo changes
301```
302 
303## Skill Creation Checklist
304 
305**Before writing:**
306- [ ] Technique isn't obvious or well-documented elsewhere
307- [ ] Pattern applies broadly (not project-specific)
308- [ ] I would reference this across multiple projects
309 
310**Frontmatter:**
311- [ ] Name uses only letters, numbers, hyphens
312- [ ] Description starts with "Use when..."
313- [ ] Description includes triggers AND what skill does
314- [ ] Description is third person
315- [ ] Total frontmatter < 1024 characters
316 
317**Content:**
318- [ ] Overview states core principle (1-2 sentences)
319- [ ] "When to Use" section with symptoms
320- [ ] Quick reference table for common operations
321- [ ] One excellent code example (if technique skill)
322- [ ] Common mistakes section
323- [ ] Keywords throughout for searchability
324 
325**Quality:**
326- [ ] Word count appropriate for frequency
327- [ ] SKILL.md under 500 lines
328- [ ] No narrative storytelling
329- [ ] Supporting files only if needed (100+ lines reference)
330- [ ] No time-sensitive information
331- [ ] Consistent terminology throughout
332- [ ] Concrete examples (not templates)
333- [ ] Degrees of freedom match task complexity
334 
335## Real-World Impact
336 
337**Good skills:**
338- Future Claude finds them quickly (CSO optimization)
339- Can be scanned in seconds (quick reference)
340- Provide clear actionable examples
341- Prevent repeating same research
342- Stay under 500 lines (token efficient)
343- Match specificity to task needs
344 
345**Bad skills:**
346- Get ignored (vague description)
347- Take too long to evaluate (no quick reference)
348- Leave gaps in understanding (no examples)
349- Waste token budget (verbose explanations)
350- Over-constrain creative tasks
351- Include time-sensitive or obsolete information
352 
353---
354 
355**Remember:** Skills are for future Claude, not current you. Optimize for discovery, scanning, and action.
356 
357**Golden rule:** Default assumption is Claude is already very smart. Only add context Claude doesn't already have.
358