Agent skills cheatsheet

skill-name/
├── SKILL.md
├── scripts/
├── references/
└── assets/

SKILL.md is required; the rest are optional. Scripts execute without loading into context, references load on demand, and assets land in output.

See: Skill structure

---
name: summarize-changes
description: >
  Summarizes uncommitted changes. Use when asked what changed.
---

Run `git diff HEAD`, then list the risks.

Frontmatter first, then plain instructions. The body loads only when the skill activates.

See: SKILL.md format

Codex and Claude Code also scan parent directories; most harnesses read .agents/skills/. Review allowed-tools and scripts before trusting a repo skill.

See: Claude Code skills, Codex skill locations

Names use lowercase letters, numbers, and single hyphens. PDF-Processing, -pdf, and pdf--processing are invalid.

See: Frontmatter fields

# Use one invocation flag, not both
disable-model-invocation: true   # only /name runs it
# user-invocable: false          # only the model runs it
paths: "src/**/*.ts"             # activate on matching files
context: fork                    # run in a subagent

These extras work in Claude Code, but claude.ai uploads and the Skills API accept only the six spec fields.

See: Frontmatter reference

# agents/openai.yaml
interface:
  display_name: "Release notes"
policy:
  allow_implicit_invocation: false

Codex keeps UI metadata and invocation policy in agents/openai.yaml.

See: Optional metadata

description: >
  Extracts text and tables from PDFs, fills forms, and merges files.
  Use when the user mentions PDFs, forms, or document extraction.

Lead with the capability, then words a user would type. Third person: the description is injected into the system prompt. Helps with documents never triggers.

See: Optimizing descriptions

Keep SKILL.md under 500 lines, keep references one level deep, and say when to read each file.

See: Progressive disclosure

## Gotchas

- `users` uses soft deletes: filter `WHERE deleted_at IS NULL`.
- `user_id` (db), `uid` (auth), `accountId` (billing) are one value.
- `/health` returns 200 with the database down; use `/ready`.

Usually the highest-value section: add a line every time an agent gets something wrong it could not have guessed.

See: Gotchas sections

- [ ] Analyze the form: `scripts/analyze.py input.pdf`
- [ ] Map fields into `fields.json`
- [ ] Validate the mapping
- [ ] Fill and verify the output

Validation is the gate: a script checks the plan against the source of truth before anything is written. Fix and re-run until it passes.

See: Plan, validate, execute

python scripts/analyze.py input.pdf > fields.json

Non-interactive only: flags, env vars, or stdin. Data to stdout, diagnostics to stderr, --help works, and say whether to run or read it.

See: Using scripts

[
  { "query": "extract tables from this PDF", "should_trigger": true },
  { "query": "rename this branch", "should_trigger": false }
]

Write about 20 queries (8–10 positive, 8–10 negative), run each three times, and keep a 60/40 train/validation split.

See: Optimizing descriptions

{
  "id": 1,
  "prompt": "Extract text from document.pdf",
  "files": ["evals/files/document.pdf"],
  "expected_output": "Every page read; text saved to output.txt"
}

Cases live in evals/evals.json. Run each with and without the skill, grade the assertions, and read the traces; wasted exploration means vague instructions.

See: Evaluating skills

• Specification
• Best practices
• Anthropic authoring guide
• Claude Code skills
• Codex skills
• OpenAI Skills API
• Cursor skills
• Gemini CLI skills
• Copilot agent skills
• anthropics/skills
• Claude Code cheatsheet (devhints.io)
• Codex cheatsheet (devhints.io)