writing-skills

name	writing-skills
description	Use when creating new skills, editing existing skills, or verifying skills before deployment in Codex CLI.

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

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