| name | writing-skills |
| description | Create Agent Skills for Codex. Use when asked to write, create, or design a skill, skillsheet, or SKILL.md file. Provides skill structure, naming conventions, description patterns, and progressive disclosure strategies. |
Writing Agent Skills
Workflow
- Clarify the skill's purpose - What specific capability? When should it trigger?
- Choose complexity level - Single file vs. multi-file based on content volume
- Write the description first - This determines discoverability
- Draft SKILL.md body - Keep under 500 lines
- Split if needed - Extract to reference files for progressive disclosure
Quick Reference
Required Structure
---
name: skill-name-here
description: What it does and when to use it. Always third person.
---
[Instructions go here]
Naming Rules
- Max 64 characters
- Lowercase letters, numbers, hyphens only
- No "anthropic" or "Codex" in name
- Prefer gerund form:
processing-pdfs, analyzing-code, writing-tests
Description Rules
- Max 1024 characters
- Third person only ("Processes files", not "I process files")
- Include WHAT it does AND WHEN to use it
- Include trigger keywords users might say
Key Principles
Concise is key - Context window is shared. Only add what Codex doesn't already know.
Match freedom to fragility:
- High freedom (text instructions) → Multiple valid approaches, context-dependent
- Medium freedom (pseudocode/templates) → Preferred pattern exists, some variation OK
- Low freedom (exact scripts) → Fragile operations, must follow precisely
Progressive disclosure - SKILL.md is the table of contents. Reference files for details.
Detailed References
Full Documentation
For comprehensive guidance, see the Anthropic docs in this project:
Checklist Before Finalizing
