What are agent skills?

The one required file: SKILL.md

Every agent skill has exactly one required file, SKILL.md, at the root of the skill folder. It starts with a frontmatter block (metadata between two lines of three dashes) and is followed by plain instructions written for the agent to read, not for a human to click through.

• name: a short identifier for the skill, usually the folder name.
• description: the single line the agent matches against a user's request to decide whether this skill applies. This is the field that decides whether the skill triggers at all.
• Everything below the frontmatter is instructions in plain language: what the skill does, the steps to follow, and any constraints the agent should respect.

The description is doing more work than it looks like it is. It is not a summary for a reader; it is the routing signal the agent checks before it ever opens the rest of the file.

Folder anatomy

A minimal skill is just SKILL.md on its own. Most real skills add supporting files alongside it, in the same folder or a subfolder:

• Reference files: extra markdown the agent reads only when it needs more detail than fits comfortably in SKILL.md itself.
• Scripts: small helper programs the skill tells the agent to run for a repeatable step, instead of asking the agent to freehand it each time.
• Templates or examples: fixed text or code the skill wants copied into the user's project rather than generated fresh.

None of this is enforced by a schema the way a package.json is. A skill folder is a convention, not a compiler-checked format, which is exactly why claims and content can drift apart without anything failing loudly.

How Claude Code and Codex load a skill

Both agents work the same way at a high level: the agent has a list of installed skills, each represented by its description. When a user makes a request, the agent checks that request against the descriptions and, if one matches well enough, reads the full SKILL.md (and any files it points to) before acting.

The skill is not loaded into context all the time. It sits dormant until its description matches, which keeps the agent's working context small and is also why a badly written description can leave a genuinely useful skill unused.

What portable means

A portable skill is one written to the shared convention rather than to one agent's private format: plain SKILL.md, plain frontmatter, no vendor-specific syntax buried in the instructions. A portable skill can move from Claude Code to Codex to another compatible agent with no rewrite, because nothing in it assumes a feature only one of them has.

Portability is a spectrum in practice. A skill that references a Claude-only tool, or assumes a shell the target agent does not have, still runs on the agent it was written for but is not really portable, whatever the folder looks like.