Agent Skills

What & why

Choose the right customization surface

• One-off prompt → constraints or context needed only for the current task. Do not create a permanent package for an instruction with no repeat use.
• AGENTS.md → small, durable repository rules that should affect nearly every task in a scope: commands, conventions, and review expectations.
• Skill → a task-specific, reusable workflow with enough procedure, examples, references, or scripts to deserve loading only when relevant.
• Script or CLI → a deterministic operation with a stable input/output contract. A skill may teach the agent when and how to use it, but prose should not replace code where exactness matters.
• MCP server or connector → live access to external data and actions. MCP supplies the capability; a skill supplies the procedure for using that capability well.
• Plugin → the Codex distribution unit for one or more skills, optionally bundled with connectors, MCP configuration, app mappings, and presentation assets. Author the workflow as a skill; package it as a plugin when others need to install it [1].
• Memory → facts, preferences, and past context that should be recalled. A skill stores how to perform a task, not what happened in one session.
• Sub-agent → an isolated worker with its own context and task. A skill can specialize that worker, but does not itself create a new agent or a separate permission boundary.

Mental model: a package with a routing function

Anatomy of a production skill

• skill-name/SKILL.md — required. YAML frontmatter declares name and description; the Markdown body contains the core workflow.
• scripts/ — optional deterministic helpers for logic that must be exact, is expensive to regenerate, or repeatedly appears in execution traces.
• references/ — optional schemas, policies, API notes, edge-case catalogs, and long examples that only some branches need.
• assets/ — optional templates, fonts, icons, fixtures, and starter files used in the final deliverable rather than read as instructions.
• agents/openai.yaml — optional Codex metadata for display name, description, icons, default prompt, implicit-invocation policy, and tool dependencies [1].
• evals/ — optional but strongly recommended test prompts, fixtures, expectations, and assertions. The open format does not require it; mature ownership does.
• The open specification also defines optional frontmatter such as license, compatibility, metadata, and experimental allowed tools. Host support can vary, so keep the portable core valid with only the required fields and document runtime assumptions explicitly [2].

Build one from real expertise

1. 01
   Start with a recurring, completed task

   Choose a task that has succeeded at least once and required non-obvious guidance, corrections, source material, or repeated helper code. Mine the transcript, patch, runbook, review comments, incident report, and operator feedback. The highest-value skill content is usually the correction a domain expert had to make, not the generic first draft [4] [7].

   Do not begin with 'write a skill about databases.' Begin with evidence such as 'our analyst repeatedly joins these schemas incorrectly and omits the privacy filter.' The gap defines the capability.

2. 02
   Write examples and counterexamples before instructions

   Collect realistic prompts that should activate the skill, including casual wording and incomplete requests. Then collect adjacent prompts that must not activate it. These examples define both the boundary and the future routing eval.

   Also state what success produces: changed files, a report, a draft, a JSON object, or a verified system state. If the output cannot be named, the skill's responsibility is probably still too broad.

3. 03
   Scope one coherent job

   Use the function test: can the skill be named with one clear verb and object, and can another skill compose with it? prepare-release-notes is coherent; manage-engineering is an organization chart disguised as a workflow.

   Split workflows when they have different triggers, permissions, outputs, or rarely shared reference material. Keep them together when splitting would force the agent to rediscover the same state or pass a fragile intermediate result between skills.

4. 04
   Design the description as a classifier

   Say what the skill does and when it should be used, in the vocabulary users and repositories actually contain. Put every trigger condition in frontmatter—the body is unavailable until after activation. Front-load the key noun, action, and artifact type so truncation preserves the signal [1] [3].

   Name exclusions when a close neighbor would otherwise cause false positives, but avoid turning the description into a mini-manual. The goal is a clean decision boundary, not full execution detail.

5. 05
   Draft the smallest useful workflow

   Write imperative, ordered steps covering inputs, inspection, transformation, verification, and deliverables. Include non-obvious constraints, decision points, recovery from known failures, and conditions for asking the user or stopping.

   Prefer a clear default with a narrow escape hatch over a menu of equal options. Explain the reason behind critical rules; models generalize a causal constraint better than a pile of brittle ALWAYS and NEVER statements [4] [6].

6. 06
   Factor references, scripts, and assets

   Move material off the hot path when it is long or applies only to a branch. Link directly from the decision point—'read references/api-errors.md after a non-2xx response'—instead of saying 'see references.' Avoid reference chains several files deep; they hide required instructions behind extra retrieval decisions.

   When traces show the agent rewriting the same parser, validator, chart generator, or conversion logic, bundle and test it once. Add assets when fidelity comes from reusing a real template rather than describing one [3] [4].

7. 07
   Add a validation gate

   Make verification a workflow step, not an optional reminder. For ordinary work: execute, validate, repair, revalidate. For batch, expensive, or destructive work: plan into a structured intermediate artifact, validate it against a source of truth, then execute [4].

   A validator may be a script, schema, test command, rendered preview, reference checklist, or read-back from the target system. Define what evidence must exist before the skill claims completion.

8. 08
   Install at the narrowest useful scope

   For Codex, put team skills under .agents/skills in the relevant repository path; Codex scans from the current working directory up to the repository root. Use $HOME/.agents/skills for personal cross-repository workflows, /etc/codex/skills for admin-managed defaults, and plugins for installable distribution [1].

   Avoid duplicate skill names—Codex does not merge them, and both may appear in selectors. It detects file changes automatically; restart only if a change does not appear. Symlinked skill directories are supported [1].

9. 09
   Run activation and outcome evals, then ship narrowly

   Validate the folder structure, run the scripts, test positive and negative trigger prompts, and compare real task outcomes with the skill against a baseline. Start with a few representative cases, fix the largest failure pattern, and repeat.

   Release to a small group first. Execution traces reveal missing context, unnecessary detours, over-strong rules, and accidental activations that final outputs conceal. A skill is finished only provisionally; real use is the next test set [3] [6].

Write a description that triggers reliably

• Lead with the capability: Review Go cookbook Markdown for deprecated APIs, recognized bad practices, code smells, and shallow examples.
• Follow with observable triggers: Use when asked to review a Go cookbook article or create an adjacent recommendations file.
• Use real user nouns, file extensions, tool names, and task verbs. Semantic matching cannot recover vocabulary you omitted.
• Include a boundary when collision is plausible: Do not use for implementing the fixes. A boundary that never distinguishes a real neighbor is just noise.
• Keep all activation logic in the description. A When to use section in the body cannot help the agent decide to load the body [3].
• Test paraphrases, terse prompts, multilingual or domain shorthand where relevant, and prompts containing trigger words in an unrelated sense.
• Measure false negatives and false positives separately. Broaden language to recover misses; sharpen scope to eliminate hijacks. Do not optimize recall by making every nearby task match.
• Keep a held-out validation set—roughly 40% is a practical starting point—so description edits do not overfit the exact phrases used during tuning [9].
• For high-risk or surprising workflows, set policy.allow_implicit_invocation: false in agents/openai.yaml; users can still invoke the skill explicitly [1].

What belongs in SKILL.md

• Mission and boundary: the outcome this workflow owns, plus any adjacent work it must leave alone.
• Inputs and discovery: required files, data, credentials, context, and the exact order for locating them. State how to proceed when one is missing.
• The default path: concise ordered actions written in imperative form, with a reason attached to load-bearing constraints.
• Decision points: observable conditions mapped to actions. Use 'if the file is scanned, run OCR' rather than a vague request to handle edge cases.
• Tool and resource routing: exact relative paths, when to read each reference, when to run each script, and what its result means.
• Output contract: filenames, structure, required fields, destinations, and what the user should receive in the final response.
• Verification loop: commands or checks, expected evidence, repair behavior, and the definition of done.
• Safety and authority: read/write boundaries, approval points, dry-run requirements, prohibited data, and when to escalate instead of guessing.
• A small number of representative examples when format or judgment is otherwise ambiguous. Prefer one complete example over many superficial variants.
• Only information the agent lacks. General tutorials, motivational prose, changelogs, and exhaustive background steal attention from the live task. As a practical ceiling, keep the core below roughly 500 lines or 5,000 tokens and split sooner when branches are mutually exclusive [4].

Engineer scripts for agents

1. 01
   Use code where determinism pays

   Bundle logic that the agent repeatedly recreates, that must be exact, or that is cheaper to execute than to express through tokens: parsers, converters, schema checks, calculations, renderers, and validators. Keep judgment and orchestration in instructions [3] [5] [7].

2. 02
   Make every interface non-interactive

   Accept input through flags, stdin, or environment variables; never block on a TTY prompt. Provide concise --help with required arguments, defaults, and realistic examples. On missing input, return an error that states what was expected and the next valid command [5].

3. 03
   Return machine-shaped results

   Prefer JSON, CSV, or another stable format on stdout, and send progress or diagnostics to stderr. Use meaningful exit codes. Bound large output with summaries, pagination, or an explicit output file so truncation does not remove the evidence the agent needs [5].

4. 04
   Design for retries and preview

   Agents retry. Make operations idempotent where possible, reject ambiguous inputs, give writes a --dry-run or plan mode, and require an explicit target for destructive actions. Safe behavior should be the path of least resistance [5].

5. 05
   Pin and test the runtime

   Pin dependency versions, state system and network requirements, and test scripts by executing them on representative and failure inputs. A script bundled but never run is an unverified dependency, not reliability.

Evaluate the skill as a system

1. 01
   Test activation precision and recall

   Build labeled queries: realistic positives, obvious negatives, and hard near-misses. Observe whether the skill was actually loaded, not whether the final answer merely looked relevant. Keep tuning and held-out sets so description changes must generalize [9].

2. 02
   Test outcomes against a baseline

   Run each representative task with the skill and without it; for an existing skill, compare against a snapshot of the previous version. The same prompt, inputs, environment, and output destination should be used in both conditions [6].

3. 03
   Grade objective assertions

   After the first outputs reveal what success looks like, add specific checks: valid JSON, all required sections, no modified source file, exact row count, tests passing. Avoid vague assertions and brittle wording checks. Record evidence for every pass or failure [6].

4. 04
   Review subjective quality with humans

   A technically valid deliverable can still be unhelpful, ugly, or misjudged. Have a domain reviewer inspect the artifacts and leave actionable feedback. Empty feedback is useful evidence too; it distinguishes a clean result from an unreviewed one [6].

5. 05
   Inspect the execution trace

   Final answers hide the mechanism. Trace review exposes wasted searches, unread references, ignored steps, repeated code generation, late clarifications, and validators that never ran. Fix the underlying routing or procedure instead of patching only the observed output [4] [6].

6. 06
   Track quality, cost, and stability together

   Measure assertion pass rate and human preference alongside tokens, duration, tool calls, retries, and variance across repeated runs. Remove assertions that pass equally without the skill; investigate cases that fail in both conditions; preserve instructions that create the actual delta [6].

Secure the capability

1. 01
   Treat installation as a supply-chain decision

   A skill can shape future behavior and execute bundled code. Install from trusted sources; otherwise audit every file, dependency, asset, network destination, and instruction before enabling it. Record provenance and license, pin versions where distribution supports it, and review updates as diffs [7].

2. 02
   Keep secrets and authority out of the package

   Never hardcode credentials, copied cookies, tokens, production payloads, or customer data. Let the host provide credentials at runtime and preserve its sandbox, approvals, and connector permissions. Retrieval of a skill must never imply permission to perform every action it describes.

3. 03
   Put validation before side effects

   For mutation, spend, deployment, deletion, or external communication, separate inspect, plan, validate, execute, and verify. Use least-privilege tools, read-only discovery where possible, dry runs, narrow targets, and explicit confirmation at the host's required approval boundary [4] [5].

4. 04
   Constrain implicit activation

   Broad implicit triggering is inappropriate for surprising or high-blast-radius behavior. Make such skills explicit-only, state prohibited actions and escalation conditions, and ensure a harmless prompt cannot accidentally route into a mutating workflow [1].

5. 05
   Review external content as untrusted input

   References, web pages, issue text, and tool output may contain instructions hostile to the workflow. Tell the agent which sources are authoritative, keep external content in a data role, and never let retrieved text silently rewrite the skill's rules or destinations.

Operational details for Codex

• Invoke explicitly with $skill-name; in CLI and IDE, /skills and $ help discover available skills. Otherwise Codex may activate a matching skill from its description [1].
• Use the built-in $skill-creator when describing a workflow, or Record & Replay when a stable computer workflow is easier to demonstrate than explain [1].
• Use $skill-installer for curated skills or skills hosted in other repositories. Review third-party contents before installation and restart if a new skill is not detected [1] [3].
• Disable a local skill without deleting it through [[skills.config]] in ~/.codex/config.toml, pointing to its SKILL.md and setting enabled = false; restart after config changes [1].
• Declare an MCP dependency in agents/openai.yaml so the environment can surface the required tool. The declaration improves setup; actual access still follows workspace and provider permissions [1].
• Keep instruction-only as the default. Add scripts only for deterministic behavior or external tooling, and add a plugin only when distribution or bundled integrations justify the extra package layer [1].

Common failure modes

• Generic expertise: asking a model to invent a skill from its own broad knowledge, producing advice the model already knew and no local leverage.
• Megaskill: one package owns several unrelated triggers, permissions, and outputs, so every activation loads irrelevant rules.
• Invisible trigger: the description says only what the skill is, while all when to use language sits in the body that cannot load until after matching.
• Keyword vacuum: omitting the file types, domain terms, and verbs users actually mention, then blaming semantic routing for missed activations.
• Recall at any cost: widening the description until it hijacks adjacent work; false-positive activation can degrade good baseline behavior.
• Documentation dump: placing whole policies and API manuals in SKILL.md, crowding the task and burying the actual workflow.
• Reference maze: indirect links and deep chains with no condition telling the agent when each file matters.
• Menu prompting: listing five equal libraries or strategies instead of choosing a reliable default and a defined exception.
• Prose calculator: making the model repeat exact parsing, conversion, or validation logic that belongs in a tested script.
• Happy-path script: interactive prompts, unbounded stdout, vague errors, ambient dependencies, and no idempotency or dry run.
• Verification theater: saying 'check your work' without a command, schema, reference, evidence requirement, or repair loop.
• One-shot testing: trying one friendly prompt, observing one acceptable result, and declaring the routing and procedure reliable.
• Benchmark illusion: measuring outputs with the skill but never comparing the model's unaided baseline, cost, latency, or variance.
• Implicit danger: allowing a broadly matched skill to send, deploy, delete, spend, or mutate without an explicit plan and approval boundary.
• Skill rot: tool versions, paths, policies, and examples drift while an unowned skill continues to activate with stale authority.

Final checklist

Read next

• Skill Learning Loops — How completed work is distilled, reviewed, stored, retrieved, and improved as reusable skills.
• Context Engineering — Why progressive disclosure matters and how skill content competes for the agent's working context.
• Model Context Protocol — The external tool and data layer that skills can orchestrate into repeatable workflows.
• Evaluation for LLM Features — The broader method for baselines, test sets, graders, human review, cost, and regression gates.
• Agent Memory — Separate reusable procedural knowledge from persistent facts, preferences, and episodes.

References

• [1] OpenAI — Build skills — Current Codex behavior: activation, progressive disclosure, locations, metadata, plugins, installation, disabling, and best practices.
• [2] Agent Skills specification — The portable directory format and the required and optional SKILL.md frontmatter fields.
• [3] OpenAI skill-creator — OpenAI's own creation workflow: concrete examples, resource planning, initialization, validation, and iteration.
• [4] Agent Skills — Best practices for skill creators — Expert guidance on real source material, scope, context economy, defaults, validation loops, and progressive disclosure.
• [5] Agent Skills — Using scripts in skills — Agent-friendly script interfaces: non-interactive inputs, help, structured output, errors, idempotency, dry runs, and bounded results.
• [6] Agent Skills — Evaluating skill output quality — With-skill baselines, assertions, human review, trace analysis, timing, grading, and iterative improvement.
• [7] Anthropic — Equipping agents for the real world with Agent Skills — The original engineering explanation of layered disclosure, executable helpers, evaluation, iteration, and security.
• [8] OpenAI — Introducing the Codex app — How OpenAI uses skills in practice across engineering, evaluation, documentation, operations, design, and knowledge work.
• [9] Agent Skills — Optimizing skill descriptions — Trigger evaluation with positive and negative queries, precision and recall, and held-out validation prompts.
• [10] OpenAI Skills catalog — Curated and system skill implementations to study as working examples rather than blank templates.