Menu
Use when creating new skills, editing existing skills, or verifying skills work before deployment
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Use before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation.
Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies
Use when you have a written implementation plan to execute in a separate session with review checkpoints
Use when implementation is complete, all tests pass, and you need to decide how to integrate the work
Use when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable
Use when completing tasks, implementing major features, or before merging to verify work meets requirements
| name | writing-skills |
| description | Use when creating new skills, editing existing skills, or verifying skills work before deployment |
Writing skills IS Test-Driven Development applied to process documentation.
You write test cases (pressure scenarios with subagents), watch them fail (baseline behavior), write the skill (documentation), watch tests pass (agents comply), and refactor (close loopholes).
Core principle: If you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing.
A skill is a reference guide for proven techniques, patterns, or tools. Skills help future agent instances find and apply effective approaches.
Skills are: Reusable techniques, patterns, tools, reference guides
Skills are NOT: Narratives about how you solved a problem once
Create when:
Don't create for:
Concrete method with steps to follow (condition-based-waiting, root-cause-tracing)
Way of thinking about problems (flatten-with-flags, test-invariants)
API docs, syntax guides, tool documentation
skills/
skill-name/
SKILL.md # Main reference (required)
supporting-file.* # Only if needed
Frontmatter (YAML):
name and descriptionname: Use letters, numbers, and hyphens onlydescription: Start with "Use when..." - triggering conditions only---
name: Skill-Name-With-Hyphens
description: Use when [specific triggering conditions and symptoms]
---
# Skill Name
## Overview
What is this? Core principle in 1-2 sentences.
## When to Use
Bullet list with SYMPTOMS and use cases
When NOT to use
## Core Pattern
Before/after code comparison
## Quick Reference
Table or bullets for scanning
## Implementation
Inline code for simple patterns
## Common Mistakes
What goes wrong + fixes
CRITICAL: Description = When to Use, NOT What the Skill Does
The description should ONLY describe triggering conditions. Do NOT summarize the skill's process.
# ❌ BAD: Summarizes workflow
description: Use when executing plans - dispatches subagent per task with code review between tasks
# ✅ GOOD: Just triggering conditions
description: Use when executing implementation plans with independent tasks in the current session
One excellent example beats many mediocre ones
Good example:
Don't:
NO SKILL WITHOUT A FAILING TEST FIRST
Write skill before testing? Delete it. Start over.
RED Phase - Write Failing Test:
GREEN Phase - Write Minimal Skill:
REFACTOR Phase - Close Loopholes:
Quality Checks:
Creating skills IS TDD for process documentation.
Same Iron Law: No skill without failing test first. Same cycle: RED (baseline) → GREEN (write skill) → REFACTOR (close loopholes).