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:

1. Naming the trigger conditions clearly
2. Putting the highest-signal symptoms in the description
3. Using the same vocabulary users will naturally type
4. 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

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."