6bnbn Writing Skills
Overview
Writing skills is TDD for process documentation: establish a failing baseline, write the minimum skill content that fixes the behavior, then refine it until the workflow is reliable.
Personal skills live in ~/.codex/skills.
Core Principle
If you did not observe a realistic failure mode before writing the skill, you do not yet know what the skill needs to prevent.
What a Skill Is
A skill is a reusable guide for patterns, tools, or workflows that future Codex sessions should be able to discover and apply.
Skills are:
- reusable workflows
- decision guides
- tool usage references
- proven implementation patterns
Skills are not:
- project-specific notes better suited for AGENTS.md
- narratives about one past debugging session
- mechanical rules better enforced by automation
Directory Structure
ext skills/ skill-name/ SKILL.md supporting-file.md
Use a flat namespace and keep supporting files only when the main file would otherwise become too heavy.
Required SKILL.md Frontmatter
- Only ame and description
ame uses letters, numbers, and hyphens only
- description starts with Use when...
- description explains when to load the skill, not the whole workflow
Discovery Optimization
Future Codex sessions need to find the skill quickly. Optimize for that by:
- Naming the trigger conditions clearly
- Putting the highest-signal symptoms in the description
- Using the same vocabulary users will naturally type
- Keeping the first screen concise and actionable
Authoring Workflow
RED
- Reproduce the failure mode without the skill
- Capture the rationalizations or mistakes that appear
GREEN
- Write the minimal skill content that closes those gaps
- Include only the steps, examples, and warnings needed to fix the observed failures
REFACTOR
- Test again under pressure
- Add explicit counters for any new loopholes
- Remove anything that does not help discovery or compliance
Quality Checklist
Mirror this checklist in update_plan when actively authoring a skill:
- Validate the trigger description
- Validate the frontmatter
- Keep the overview concise
- Include examples only when they improve execution
- Test discovery and compliance with realistic prompts
- Re-check for loopholes before deployment
Common Mistakes
| Mistake | Fix |
|---|---|
| Description explains what the skill does | Rewrite it to explain when to load it |
| Frontmatter includes extra keys | Keep only |
| ame and description | |
| Long narrative examples | Replace with compact reusable examples |
| Supporting docs loaded by default | Move heavy references into separate files |
| No baseline failure observed | Reproduce a realistic failing scenario first |
Testing
Use subagents or realistic prompts to test:
- discovery
- compliance under pressure
- resistance to shortcut rationalization
The goal is not just "looks good," but "changes behavior predictably."