mirror of
https://github.com/openai/codex.git
synced 2026-05-03 19:06:58 +00:00
61 lines
2.2 KiB
Markdown
61 lines
2.2 KiB
Markdown
# Skills
|
|
|
|
Codex can automatically discover reusable "skills" you keep on disk. A skill is a small bundle with a name, a short description (what it does and when to use it), and an optional body of instructions you can open when needed. Codex injects only the name, description, and file path into the runtime context; the body stays on disk.
|
|
|
|
## Where skills live
|
|
|
|
- Location (v1): `~/.codex/skills/**/SKILL.md` (recursive). Hidden entries and symlinks are skipped. Only files named exactly `SKILL.md` count.
|
|
- Sorting: rendered by name, then path for stability.
|
|
|
|
## File format
|
|
|
|
- YAML frontmatter + body.
|
|
- Required:
|
|
- `name` (non-empty, ≤100 chars, sanitized to one line)
|
|
- `description` (non-empty, ≤500 chars, sanitized to one line)
|
|
- Extra keys are ignored. The body can contain any Markdown; it is not injected into context.
|
|
|
|
## Loading and rendering
|
|
|
|
- Loaded once at startup.
|
|
- If valid skills exist, Codex appends a runtime-only `## Skills` section after `AGENTS.md`, one bullet per skill: `- <name>: <description> (file: /absolute/path/to/SKILL.md)`.
|
|
- If no valid skills exist, the section is omitted. On-disk files are never modified.
|
|
|
|
## Validation and errors
|
|
|
|
- Invalid skills (missing/invalid YAML, empty/over-length fields) trigger a blocking, dismissible startup modal in the TUI that lists each path and error. Errors are also logged. You can dismiss to continue (invalid skills are ignored) or exit. Fix SKILL.md files and restart to clear the modal.
|
|
|
|
## Create a skill
|
|
|
|
1. Create `~/.codex/skills/<skill-name>/`.
|
|
2. Add `SKILL.md`:
|
|
|
|
```
|
|
---
|
|
name: your-skill-name
|
|
description: what it does and when to use it (<=500 chars)
|
|
---
|
|
|
|
# Optional body
|
|
Add instructions, references, examples, or scripts (kept on disk).
|
|
```
|
|
|
|
3. Keep `name`/`description` within the limits; avoid newlines in those fields.
|
|
4. Restart Codex to load the new skill.
|
|
|
|
## Example
|
|
|
|
```
|
|
mkdir -p ~/.codex/skills/pdf-processing
|
|
cat <<'SKILL_EXAMPLE' > ~/.codex/skills/pdf-processing/SKILL.md
|
|
---
|
|
name: pdf-processing
|
|
description: Extract text and tables from PDFs; use when PDFs, forms, or document extraction are mentioned.
|
|
---
|
|
|
|
# PDF Processing
|
|
- Use pdfplumber to extract text.
|
|
- For form filling, see FORMS.md.
|
|
SKILL_EXAMPLE
|
|
```
|