---

Name: Use kebab-case (letters, numbers, hyphens only)

Examples: api-error-handling, condition-based-waiting, flatten-with-flags

NO parentheses, NO special chars, NO underscores

name: your-skill-name-here

Description: CRITICAL for Claude Search Optimization (CSO)

Format: "Use when [specific triggering conditions] - [what it does and how it helps]"

Write in THIRD PERSON (injected into system prompt)

Include CONCRETE symptoms, error messages, situations

Keep under 500 characters if possible

Examples:

GOOD: "Use when tests have race conditions, timing dependencies, or pass/fail inconsistently - replaces arbitrary timeouts with condition polling for reliable async tests"

GOOD: "Use when implementing any feature or bugfix, before writing implementation code - write the test first, watch it fail, write minimal code to pass; ensures tests actually verify behavior by requiring failure first"

BAD: "For async testing" (too vague, no triggers)

BAD: "I can help with flaky tests" (first person)

description: Use when [specific triggering conditions and symptoms] - [what the skill does and how it helps, written in third person]

[Skill Title]

Overview

[What is this skill? State the core principle clearly and concisely.]

When to Use

Use this skill when:

• [Symptom or situation 1 - be concrete and specific]
• [Symptom or situation 2 - include error messages if applicable]
• [Symptom or situation 3 - describe observable behaviors]

When NOT to use:

• [Counter-example 1 - helps clarify boundaries]
• [Counter-example 2]

[Main Content Section]

The Process

1. [Step 1 - be specific and actionable]
2. [Step 2]
3. [Step 3]

Core Pattern

Before:

Copy// Show the problematic approach

After:

Copy// Show the improved approach with comments explaining WHY

Quick Reference

The Iron Law

Copy[STATE THE CORE RULE IN ALL CAPS]

[Explain consequences of violation]

No exceptions:

• [Close specific loophole 1]
• [Close specific loophole 2]
• [Close specific loophole 3]

Implementation

Copy// Complete, runnable example from real scenario
// Well-commented explaining WHY, not just what
// Shows pattern clearly and ready to adapt

[code example]

Common Mistakes

[Mistake 1 heading - make it searchable]

[What goes wrong and why]

[How to fix it - be specific]

[Mistake 2 heading]

[What goes wrong and why]

[How to fix it]

Red Flags - STOP and Start Over

• [Warning sign 1 - quote actual rationalizations from baseline testing]
• [Warning sign 2]
• [Warning sign 3]
• "I'm following the spirit" or "This is different because..."

All of these mean: [Correct action - usually "Stop. Start over."]

Rationalization Table

[Optional: Real-World Impact / Trade-offs]

Impact:

• [Concrete result 1]
• [Concrete result 2]

Trade-offs:

• Advantage: [Benefit]
• Cost: [What you give up]
• When worth it: [Conditions]