Skill Management
Manage local SKILL.md files with /skill commands. Shared execution, delegation,
state, hook, team, cancellation, verification, and escalation invariants live in
templates/AGENTS.md; follow that contract instead of repeating it here.
Scopes and commands
Canonical roots are ${CODEX_HOME:-$HOME/.codex}/skills/ (user) and .codex/skills/
(project). A skill lives at <root>/<name>/SKILL.md.
| Command |
Contract |
/skill list |
Scan both roots, parse frontmatter, and show name, description, triggers, scope, and quality/usage (N/A when unavailable). |
/skill add [name] |
Run the authoring wizard, validate the name, choose scope, create SKILL.md, and report its path. |
/skill edit <name> |
Find one scope, show metadata, then update description, triggers, argument hint, body, or rename and report the change. |
/skill remove <name> |
Find the skill, show scope and metadata, confirm explicitly, then remove its directory. |
/skill search <query> |
Case-insensitively search name, description, triggers, and body; rank name/trigger matches first and show context. |
/skill info <name> |
Show parsed metadata, scope, path, and full body; suggest /skill search when absent. |
/skill sync |
Compare user/project skills, show user-only/project-only/common entries, and confirm every copy or overwrite. |
/skill setup |
Ensure both roots exist, scan them, then offer add, list, pattern scan, import, or done. |
/skill scan |
Run setup's scan/inventory without its interactive menu. |
/skill validate |
Validate every skill in both roots and report each path's pass/fail result; never rewrite files. |
With an argument, use direct command mode; without one, use the guided setup menu.
Authoring contract
Ask for any missing values:
name: lowercase letters/digits separated by single hyphens ([a-z0-9]+(?:-[a-z0-9]+)*).description: a concise, non-empty one-line purpose.triggers: comma-separated recognition terms.argument-hint: optional invocation arguments.scope: user or project.
Write this frontmatter at the start of every skill; optional metadata may add id,
source, and quality without replacing required fields:
---
name: <name>
description: <one-line purpose>
triggers: [<trigger1>, <trigger2>]
argument-hint: "<args>"
# optional: id, source, quality
---
Use an actionable body. The minimum recommended shape is:
# <Skill title>
## Purpose
What durable, codebase-specific outcome does this skill provide?
## When to Activate
Recognition signals, scope, and explicit non-goals.
## Workflow
1. Inspect the named files or inputs.
2. Apply the precise approach and record important assumptions.
3. Verify observable behavior and report evidence.
## Examples / Gotchas
Concrete invocation, edge cases, and failure recovery.
Prefer hard-won, non-obvious knowledge over generic programming advice. Include
exact paths, commands, error text, and expected evidence when they materially help.
Validation and errors
Before reporting success, check that the file exists, starts with --- frontmatter,
has non-empty name and description, uses a valid name, and has a non-empty body.
Reject malformed or unterminated YAML, multiline required scalar values, duplicate
names in one scope, missing directories/files, permission failures, and invalid
arguments. Report errors consistently:
✗ Error: <clear message>
→ Suggestion: <specific next step>
Exit contract
Every command ends with one concise result: ✓ plus the affected skill/path and
next action, or ✗ plus the error and suggestion. Preserve files on cancel or
validation-only runs. For add/edit/sync, report changed scope and metadata; for
list/search/info/scan/validate, report counts or matched paths and any failures.
1---2name: skill3description: Manage local skills - list, add, remove, search, edit, setup wizard4---56# Skill Management78Manage local `SKILL.md` files with `/skill` commands. Shared execution, delegation,9state, hook, team, cancellation, verification, and escalation invariants live in10`templates/AGENTS.md`; follow that contract instead of repeating it here.1112<Purpose>13Create, inspect, validate, update, and organize user- or project-scoped skills.14Keep each skill specific, actionable, evidence-based, and useful to this codebase.15</Purpose>1617<Use_When>18- The user asks to list, add, edit, remove, search, inspect, sync, set up, scan, or validate skills.19- A durable, codebase-specific solution or workflow should be captured as a skill.20</Use_When>2122<Do_Not_Use_When>23- Use `/learner` to extract a skill from a conversation and `/note` for a short note.24- Do not use this prompt to change runtime code, catalogs, hooks, or installation logic.25</Do_Not_Use_When>2627## Scopes and commands2829Canonical roots are `${CODEX_HOME:-$HOME/.codex}/skills/` (user) and `.codex/skills/`30(project). A skill lives at `<root>/<name>/SKILL.md`.3132| Command | Contract |33|---|---|34| `/skill list` | Scan both roots, parse frontmatter, and show name, description, triggers, scope, and quality/usage (`N/A` when unavailable). |35| `/skill add [name]` | Run the authoring wizard, validate the name, choose scope, create `SKILL.md`, and report its path. |36| `/skill edit <name>` | Find one scope, show metadata, then update description, triggers, argument hint, body, or rename and report the change. |37| `/skill remove <name>` | Find the skill, show scope and metadata, confirm explicitly, then remove its directory. |38| `/skill search <query>` | Case-insensitively search name, description, triggers, and body; rank name/trigger matches first and show context. |39| `/skill info <name>` | Show parsed metadata, scope, path, and full body; suggest `/skill search` when absent. |40| `/skill sync` | Compare user/project skills, show user-only/project-only/common entries, and confirm every copy or overwrite. |41| `/skill setup` | Ensure both roots exist, scan them, then offer add, list, pattern scan, import, or done. |42| `/skill scan` | Run setup's scan/inventory without its interactive menu. |43| `/skill validate` | Validate every skill in both roots and report each path's pass/fail result; never rewrite files. |4445With an argument, use direct command mode; without one, use the guided setup menu.4647## Authoring contract4849Ask for any missing values:501. `name`: lowercase letters/digits separated by single hyphens (`[a-z0-9]+(?:-[a-z0-9]+)*`).512. `description`: a concise, non-empty one-line purpose.523. `triggers`: comma-separated recognition terms.534. `argument-hint`: optional invocation arguments.545. `scope`: `user` or `project`.5556Write this frontmatter at the start of every skill; optional metadata may add `id`,57`source`, and `quality` without replacing required fields:5859```yaml60---61name: <name>62description: <one-line purpose>63triggers: [<trigger1>, <trigger2>]64argument-hint: "<args>"65# optional: id, source, quality66---67```6869Use an actionable body. The minimum recommended shape is:7071```markdown72# <Skill title>7374## Purpose75What durable, codebase-specific outcome does this skill provide?7677## When to Activate78Recognition signals, scope, and explicit non-goals.7980## Workflow811. Inspect the named files or inputs.822. Apply the precise approach and record important assumptions.833. Verify observable behavior and report evidence.8485## Examples / Gotchas86Concrete invocation, edge cases, and failure recovery.87```8889Prefer hard-won, non-obvious knowledge over generic programming advice. Include90exact paths, commands, error text, and expected evidence when they materially help.9192## Validation and errors9394Before reporting success, check that the file exists, starts with `---` frontmatter,95has non-empty `name` and `description`, uses a valid name, and has a non-empty body.96Reject malformed or unterminated YAML, multiline required scalar values, duplicate97names in one scope, missing directories/files, permission failures, and invalid98arguments. Report errors consistently:99100```text101✗ Error: <clear message>102→ Suggestion: <specific next step>103```104105## Exit contract106107Every command ends with one concise result: `✓` plus the affected skill/path and108next action, or `✗` plus the error and suggestion. Preserve files on cancel or109validation-only runs. For add/edit/sync, report changed scope and metadata; for110list/search/info/scan/validate, report counts or matched paths and any failures.
Yeachan-Heo