What is an agent skill?

An agent skill is a folder that gives an AI coding agent instructions for one repeatable task, plus any scripts, reference files, or assets the task needs. The only required file is SKILL.md: YAML frontmatter with a name and description, followed by Markdown instructions. Hosts read the frontmatter first and only load the rest of the folder when a task looks like a match, a pattern called progressive disclosure.

How progressive disclosure works

The Agent Skills specification describes three stages, each loaded only when needed:

1. Metadata: the name and description fields, roughly 100 tokens. A host keeps this for every skill it knows about, so it can decide which one might apply.
2. The SKILL.md body: the actual instructions, recommended to stay under 5,000 tokens and 500 lines. A host loads this once it decides the skill is relevant to the current task.
3. Supporting files: anything under scripts/, references/, or assets/ in the skill folder. These load only when the instructions in SKILL.md point to them.

Those size figures are recommendations, not hard limits. The spec is explicit about that, except where it states an actual field limit (see the SKILL.md format for the fields that are and aren’t optional).

Where the format came from

Anthropic introduced Agent Skills for Claude on October 16, 2025, and says it published the format as an open standard on December 18, 2025. Those are two different milestones; don’t date the open standard to October. Documented adoption as of September 27, 2026 includes Claude Code, Codex, Cursor, and GitHub Copilot (Copilot support was announced on December 18, 2025).

A compatible folder format doesn’t mean identical behavior across hosts. Claude Code, Codex, and Cursor each document their own install locations and their own rules for automatic selection versus direct invocation, and none of that is guaranteed by the folder format alone. We cover the concrete path differences in how to create an agent skill.

What we tested it on

We built one small skill, explain-error, and used it as the worked example across this set of guides. It explains a pasted error message or stack trace and suggests one concrete fix. Its full contents are in the SKILL.md format.

What we checked

Format

npx skills-ref validate ./explain-error (v0.1.5) returned Valid skill: ./explain-error. This only confirms frontmatter shape; it doesn’t confirm the skill works. See how references and assets work inside a skill for what it misses.

Installs

We copied the folder to .claude/skills/explain-error/ (Claude Code, project scope) and to both .agents/skills/explain-error/ and .codex/skills/explain-error/ (Codex, project scope; both paths are live on Codex CLI 0.157.1). We also installed it with npx skills add <path> -a claude-code -y and -a codex -y (skills CLI v1.7.0); both wrote full copies of the folder, not symlinks, to .claude/skills/ and .agents/skills/ respectively. The installer doesn’t target .codex/skills/, which we reached only by hand-copy.

Loads

On Codex CLI 0.157.1, the skill appeared in the agent’s own skill listing, and a pasted Python traceback triggered it: the trace showed cat .agents/skills/explain-error/SKILL.md, and the reply opened with the marker line we’d asked for, Checked with explain-error. A control prompt (“Write a haiku about tea.”) did not trigger it.

On Claude Code 2.1.283, claude -p could not authenticate from our test setup. Every invocation, including a plain claude -p "say hi", returned Not logged in · Please run /login, even though the session running the test was itself an authenticated, interactive Claude Code session. claude auth status and claude doctor both confirmed no usable credential was reachable from that shell; this held with the sandbox on and off, and network to api.anthropic.com was fine. That’s a credential-isolation problem in our setup, not something we can attribute to the skill, but it means we did not test live loading in Claude Code. We did not install Cursor, so Cursor is untested for every check past format.

Helps

Not measured. We confirmed the skill loads; we did not run a paired comparison of answer quality with and without it. /methodology/ explains why that’s a separate check from loading.

What we didn’t check

Live skill loading in Claude Code and any behavior in Cursor. Personal-scope paths (~/.claude/skills, ~/.agents/skills) were documented from the brief only, not tested.

Common problems

Assuming a shared folder path means shared behavior is a common mistake: .agents/skills/ is a convention several hosts document, but a host listing a skill as “available” isn’t evidence it actually loads or follows it. Only a live test on that specific host is. An Anthropic repository discussion shows how easily path and format portability get conflated.

Treating a passing format check as proof the skill works is another: it only means the frontmatter parses. Loading, following references, and improving the task outcome are separate, unproven claims until tested.

Sources

• Agent Skills overview
• Agent Skills specification
• Anthropic: equipping agents for the real world with Agent Skills
• Claude Code skills docs
• Codex: build skills
• Cursor skills docs
• GitHub Copilot: about agent skills