NAME
SKILL.md — instruction file for Claude Code, OpenAI Codex CLI
SYNOPSIS
.claude/skills/*/SKILL.md
.agents/skills/*/SKILL.md
~/.codex/.agents/skills/*/SKILL.md
METADATA
DESCRIPTION
SKILL.md defines a modular agent capability using a progressive disclosure model shared by both Claude Code and Codex CLI. Each SKILL.md file represents a single skill the agent can perform: YAML frontmatter is loaded at startup so the agent knows what skills are available, while the full Markdown body is only loaded when the skill is invoked.
This design keeps startup costs low even with dozens of skills. The frontmatter contains the skill name, a short description, and optional configuration (tools list for Claude Code, allow_implicit_invocation for Codex). The body can be as detailed as needed — step-by-step instructions, prerequisites, rollback procedures, and examples — without affecting sessions that don't use the skill.
For Claude Code, skills live in .claude/skills/ and create /slash-commands named after the skill. Claude can also auto-invoke skills when it determines a task matches the description (unless disable-model-invocation is set). Custom commands (.claude/commands/*.md) have been merged into the skills system — both create /slash-commands and work the same way.
For Codex CLI, skills live in .agents/skills/ and can be invoked via /skills or $ mention. Codex scans from CWD up to the repo root, plus user-global and system locations. Per-skill overrides (enabled/disabled) can be set in config.toml via [[skills.config]] entries.
Lower numbers load first. Higher-priority files override lower ones.
STRUCTURE
ANNOTATED EXAMPLE
1---
2name: deploy-staging
3description: Build, test, and deploy the application to the staging environment
4tools:
5 - bash
6 - github
7---
8
9# Deploy to Staging
10
11## Prerequisites
12- All tests must pass on the current branch
13- Branch must be up to date with main (rebase if needed)
14- No unresolved merge conflicts
15
16## Steps
17
181. Run the full test suite: `pnpm test`
192. Build the production bundle: `pnpm build`
203. Tag the commit: `git tag staging-$(date +%Y%m%d-%H%M%S)`
214. Push the tag: `git push origin --tags`
225. Trigger deploy: `gh workflow run deploy-staging.yml`
23
24## Rollback
25
26If the deploy fails or monitoring shows errors:
271. Identify the previous stable tag: `git tag -l 'staging-*' | tail -2 | head -1`
282. Re-deploy the previous tag via the GitHub Actions UI
29
30## Post-deploy
31- Monitor error rates for 15 minutes
32- Notify #deployments channel with the deploy summary
COMMON MISTAKES
Frontmatter is loaded on every agent startup for all skills. Bloated frontmatter wastes tokens across every session. The body is only loaded when the skill is actually invoked, so lengthy instructions belong there.
The agent indexes skills by name at startup. Duplicate names cause undefined behavior — one skill will shadow the other. Use descriptive, unique names like 'deploy-staging' instead of generic names like 'deploy'.
The progressive disclosure model depends on one skill per file. The frontmatter identifies the skill, and the body provides its full instructions. Combining multiple skills in one file breaks the lazy-loading mechanism.
The skill format (SKILL.md with YAML frontmatter + markdown body) is shared, but the directory locations differ. Claude Code scans .claude/skills/; Codex CLI scans .agents/skills/. If you support both tools, you need skill files in both locations.
Claude Code: set disable-model-invocation: true in frontmatter to prevent auto-invocation. Codex: set allow_implicit_invocation: false. When disabled, skills can only be triggered explicitly via /slash-command (Claude Code) or $ mention (Codex).