Use an AI agent for long enough and certain explanations begin to repeat. What to check in a review. How to prepare a release. Which sources to trust, and in what order. Leave those instructions in a conversation and they vanish when the conversation ends.
Agent Skills preserve that method as a folder. The centre is a SKILL.md file. References, scripts, and templates can sit beside it when the work needs them.
More than a long prompt
A skill is not a box for miscellaneous knowledge. It describes one piece of work: where to begin, what to inspect, when to stop, and what to return. Another person could follow the same sequence. The agent can too.
The agent does not begin by reading every installed skill in full. It first sees compact metadata. When a request matches, it opens the chosen SKILL.md and then reads any supporting material the instructions call for. Detail arrives when it becomes useful.
A compact index of the jobs a skill can do
Procedure, judgement, definition of done
Deep context, deterministic work, templates
What goes inside a skill
Only SKILL.md is required. The rest earns its place by supporting the job. A small skill should stay small.
SKILL.mdPurpose, trigger, procedure, outputRequiredreferences/Policies, specifications, deeper contextAs neededscripts/Deterministic calculation or file workAs neededassets/Templates and material used in outputsAs neededagents/openai.yamlUI and tool metadataOptionalA useful first version can be this short:
---
name: product-copy-review
description: Review product copy before publication. Use for English,
Japanese, or French web copy; do not use for legal review.
---
1. Read the page in its full context.
2. Flag unclear claims and repeated wording.
3. Preserve technical meaning while revising.
4. Return the revised copy with a short reason for each material change.The description is not marketing copy. It is a routing rule. Stating both the intended job and the boundary helps the agent select it for the right reasons.
Where a skill fits
When two mechanisms look similar, separate them by lifespan and responsibility.
| Mechanism | Best suited to | Character |
|---|---|---|
| Prompt | The request in front of you | Shaped for one piece of work |
AGENTS.md and peers | Standing repository conventions | Applies throughout its scope |
| Skill | A repeatable workflow | Loaded for the relevant job |
| MCP server | Live data, authentication, actions | Provides information and tools |
| Plugin | Distributing skills and connections | Packages related capabilities |
An MCP server may retrieve a customer's account activity. A skill can define how to turn that activity into a briefing, what uncertainty to mark, and what the final document must contain. One supplies the capability. The other supplies the method.
Good skills are narrow
A broad skill sounds convenient until its trigger and definition of done become impossible to state. Keep the boundary around one continuous piece of work, with an input you recognise and an output you can inspect.
What arrives
What gets checked
What must be returned
- Say what input the workflow expects.
- Define what completion looks like.
- Name facts the agent must not invent.
- Mark the points where it should ask or stop.
- Explain when supporting files should be opened.
Testing should go beyond the ideal request. Try a direct invocation, an indirect request, an incomplete request, a request that should not trigger the skill, and an awkward edge case. A routing failure usually points to the description. An inconsistent result usually points to the instructions.
A shared format, with local details
Agent Skills have an open specification, but discovery paths and invocation are not identical in every host. The basic folder and method can be shared. The final placement still belongs to the product using it.
Codex looks for .agents/skills from the current working directory up to the repository root. Personal skills can live in $HOME/.agents/skills; administrator-provided skills can live in /etc/codex/skills. For wider distribution, a skill can be packaged in a plugin.
Do not assume that one folder name produces identical behaviour in every agent. Supported fields, discovery locations, and supplementary metadata still differ.
A skill is not a permission
A skill is an instruction set. It cannot grant access to the network, files, or credentials. Authenticated actions remain subject to the connected service. Sensitive operations remain subject to the agent's approvals, sandbox, and policy.
Files under scripts/ are executable code, not prose. Before installing an unfamiliar skill, read its instructions, scripts, and dependencies.
Making the method visible
The useful part of a skill is not that it makes an agent appear all-purpose. The method remains in a file. You can read it, edit it, review a diff, and decide which part of the work should be repeatable without handing over the judgement around it.
That is a practical reason to use Agent Skills: the instruction stops being magic and becomes material you can examine.
Sources
Product support changes over time. This article was checked against the published documentation available on 7 August 2026.