SKILL.md: The Cross-Agent Open Standard

Intermediate

For a few years every coding agent had its own file: .cursorrules, CLAUDE.md, Codex system prompts, Gemini instructions, a dozen more. Then Anthropic quietly turned their internal Skills format into an open spec — and within 48 hours the biggest agents in the world were reading each other's files. Today one directory called code-reviewer/ with a SKILL.md inside runs unchanged in Claude Code, Codex CLI, ChatGPT, Gemini CLI, Junie, Kiro, Goose and Cursor. This is the closest the agent world has come to a shared plug.

This page is the practical field guide: what the standard actually is at the byte level, the one clever trick (progressive disclosure) that makes 100-skill installs cheap, exactly which fields break portability the moment you touch them, the honest security picture, and a copy-pasteable portable skill you can ship today.

What you'll learn

• Understand what SKILL.md is at the file-format level — required fields, optional fields, directory layout
• Understand progressive disclosure: why 100 skills cost ~10K tokens at startup, not 100× the body
• Know the exact vendor extensions that silently break portability across agents
• Write a skill that runs unchanged in Claude Code, Codex CLI and Gemini CLI
• Weigh the security trade-off honestly before installing skills from any marketplace

Last verified: 2026-07-22.

Adoption counts, marketplace sizes and per-agent activation behavior are moving weekly. The core spec (frontmatter fields, directory layout, progressive disclosure) is stable; the periphery (which agents honor allowed-tools, which marketplaces exist, exact skill counts) is not. Confirm current numbers at agentskills.io and each agent's own docs before quoting them.

Confirm against the official source.

What the standard actually is

Strip away the marketing and the Agent Skills open standard is small enough to hold in your head:

• A directory whose name is the skill's name
• A required SKILL.md file inside it — YAML frontmatter, then Markdown body
• Optional siblings: scripts/ (executables the skill can run), references/ (docs the skill can pull in on demand), assets/ (templates, images, prompt files), and — added later — agents/ for opt-in vendor-specific config

That's the whole surface area. Two required frontmatter fields do most of the work:

• name — up to 64 characters, lowercase-with-hyphens, must match the parent directory
• description — up to 1,024 characters, the sentence the agent uses to decide whether to load this skill for the current task

Everything else — license, compatibility, metadata, and the still-experimental allowed-tools — is optional and safely ignored by tools that don't understand it. Bodies are Markdown; the community convention is to keep them under ~5,000 tokens, and real-world skills mostly do: median skill size on the largest marketplace is about 1,414 tokens with 90% under 3,935 tokens.

The one clever trick: progressive disclosure

The reason SKILL.md works at scale isn't the file format — it's how agents load it. All conformant agents implement three tiers:

Guided walkthrough1 of 3

1. The agent walks the skills directory and reads only the frontmatter of every SKILL.md. That's roughly 100 tokens per skill. Install 100 skills and you've spent ~10K tokens of context before your first prompt — cheaper than a single long system message.

This is why the spec caps description so tightly and treats it as a first-class field: it's the only text the model sees when choosing whether to activate the skill. A vague description is the single most common reason a skill that "should work" never fires.

:::tip Write the description last, and rewrite it Once the body of a skill is solid, go back and treat the description as your ad copy. It has one job: help the model recognize the shape of a task that this skill should own. "Reviews pull requests" is bad. "Reviews a PR diff for logic bugs, missing tests, and violated project conventions; use whenever the user asks for a review, code review, or 'look at this PR'" is good. :::

The universal directory

Every conformant agent expects the same layout. This one works everywhere:

code-reviewer/
├── SKILL.md          # required — the instructions the agent reads
├── scripts/          # optional — executables the skill can invoke
│   └── run-linters.sh
├── references/       # optional — long docs the skill pulls on demand
│   └── style-guide.md
├── assets/           # optional — templates, prompt files, snippets
│   └── pr-comment-template.md
└── agents/           # optional — VENDOR-SPECIFIC, opt-in only
    └── openai.yaml   # ignored by every non-Codex agent

The agents/ subdirectory is the safety valve for the standard: it lets vendors ship extensions without contaminating the portable core. A file at agents/openai.yaml is Codex-specific and every other agent will simply ignore it. Use it when you need extra power; know it costs you portability.

What actually travels vs what silently doesn't

The whole spec was designed for portability, but real skills in the wild have three failure modes.

What you use	Portable?	Why
name, description, Markdown body	✅ Yes	Core spec. Every conformant agent reads these identically.
scripts/, references/, assets/ referenced from the body	✅ Yes	Directory layout is part of the spec; agents will read them when the body says to.
license, metadata	✅ Yes (safe to ignore)	Optional fields — non-supporting agents skip without erroring.
allowed-tools frontmatter	⚠️ Partial	Marked experimental in the spec; syntax across agents is not standardized. Claude Code honors one form, Codex CLI another, most others ignore it entirely.
Claude Code's when_to_use list	❌ Claude-only	Silently ignored by Codex, Gemini CLI and everyone else.
Claude Code's context: fork subagent flag	❌ Claude-only	Non-portable subagent execution semantics — model behavior differs everywhere else.
agents/openai.yaml extensions	❌ Codex-only	Explicitly vendor-scoped by design. Portable because other agents ignore it.

The lesson is blunt: stick to name + description + Markdown body + the three optional subdirectories and your skill runs everywhere. Reach into any frontmatter field beyond the core two and you're building for one agent. That's a legitimate choice — some skills genuinely need it — but do it deliberately, not because you copy-pasted a template.

How activation actually works (per agent)

The spec standardizes the file, not the decision. Each agent still runs its own activation logic on the descriptions it read at startup:

• Claude Code matches the model's read of the current turn against description and (if present) the Claude-specific when_to_use list; activation is a model decision, not a keyword rule.
• Codex CLI uses the same description-driven activation, with optional overrides in agents/openai.yaml.
• Gemini CLI likewise loads descriptions at startup and lets Gemini choose; behavior tracks Gemini's own tool-selection heuristics.
• Cursor, Junie, Kiro, Goose all implement description-driven activation with light variations in weighting.

Practical consequence: a skill that never fires on one agent but works on another almost always has a description problem, not a body problem. Rewrite the description to describe the user request shape, not the skill's internals, and the fire rate goes up on every agent at once.

A portable SKILL.md you can copy

Here is a minimal, actually-portable code-review skill. Drop it in ~/.agents/skills/code-reviewer/SKILL.md and it will run in Claude Code, Codex CLI, ChatGPT and Gemini CLI without modification.

code-reviewer/SKILL.md

---
name: code-reviewer
description: Reviews a diff or pull request for logic bugs, security issues, missing tests, and violations of project conventions. Use whenever the user asks for a review, code review, PR review, or "look at this diff / patch / change".
license: MIT
---

# Code Reviewer

You review code changes with the discipline of a staff engineer who cares
about the codebase surviving contact with reality. You are opinionated but
short. You never restate what the diff does — the user can read it.

## What to look at

1. **Logic bugs** — off-by-one, wrong operator, swapped arguments, unhandled
 error path, race, silent catch.
2. **Missing tests** — any changed behavior without a test is a finding.
3. **Security** — injection, secrets, missing auth checks, unsafe deserialization,
 unbounded input.
4. **Project conventions** — if a CLAUDE.md, AGENTS.md, .cursorrules, or README
 exists in the repo root, load it and enforce what it says.
5. **Complexity that will hurt future readers** — call it out, propose the
 simpler shape.

## What NOT to do

- Do not comment on formatting the linter will catch.
- Do not praise. No "great work" / "nice refactor".
- Do not summarize the diff. Assume the reader read it.

## Output format

For each finding, one line:

`path:line — <severity>: <problem>. <concrete fix>.`

Severities: 🔴 blocker, 🟠 important, 🟡 nit.

End with a one-line verdict: "ship", "ship with fixes", or "rework".

Every line of that skill runs on every conformant agent. Nothing in the frontmatter is vendor-scoped. The body uses plain Markdown headings that any agent parses.

Now compare to a non-portable variant — subtly, it's Claude-only:

Claude-only variant (do not use if you want portability)

---
name: code-reviewer
description: Reviews a diff or pull request.
when_to_use:
- user asks for a review
- user pastes a diff
context: fork
allowed-tools: [Bash, Read, Grep]
---

Three things break portability at once: when_to_use (Claude Code only), context: fork (Claude Code subagent semantics), and allowed-tools (experimental, not honored consistently). Codex will read the description as "Reviews a diff or pull request" — which is so vague it will barely ever activate — and ignore the rest.

The security picture (be honest with yourself)

The uncomfortable truth about installing skills from any marketplace: a skill is arbitrary instructions to a highly capable agent that runs in your environment with your permissions. The standard specifies no code signing, no sandboxing, no mandatory review, and no runtime permission model. It is by design a text-file spec, not a security spec.

The concrete numbers, from independent analyses of large public skill catalogs (verify at source before quoting):

• Roughly one in three publicly-shared skills contains at least one security-relevant flaw — over-broad shell instructions, hardcoded secrets, calls to untrusted URLs, or curl | sh-style bootstrap steps.
• A smaller but non-zero set of skills has been flagged as outright malicious — attempting exfiltration, credential harvesting, or destructive operations.
• Skills inherit whatever the agent inherits. If your agent can read ~/.ssh/, so can any skill you install.

Practical defenses that actually work:

Guided walkthrough1 of 4

1. It is Markdown. It takes a minute. If the description says 'formats prose' and the body contains `curl` to a URL you don't recognize, that is the moment you stop.

For a deeper dive on how skills get compromised and what to check, see Vetting Agent Skills and Coding Agents Under Attack.

When to write a skill vs when to just prompt

New maintainers of a skill catalog often over-produce them. A useful rule:

• Prompt for a one-off task or a shape you'll use in one project. Skills carry startup cost — even if it's small — and clutter your description budget.
• Write a skill when the same instructions apply across many chats or projects (code review, commit-message writing, changelog generation, invoice extraction) and the description would be unambiguous. If you can't write a crisp description, the skill won't fire reliably anyway.
• Reach for a subagent instead when the task needs its own tool set, its own model choice, or genuine parallelism. Skills instruct the main model; subagents run separately. See Subagents.

Related reading

• Skills in Claude Code — the Claude-side surface: activation, tool scopes, hooks, on-disk conventions.
• Skills & Plugins for Pros — production patterns, testing, catalogs.
• First Skill walkthrough — hands-on from scratch.
• Coding Agent CLIs Compared — the same landscape from the CLI angle.
• Porting Prompts Across Models — the sister topic for the reasoning-layer side of portability.

Check your grip

Check yourself

0/4

1. 1You install 100 skills. Roughly how many tokens do their descriptions cost your agent at startup?
2. 2Which of these frontmatter fields will silently break your skill on Codex CLI and Gemini CLI even though it works in Claude Code?
3. 3A skill you wrote fires reliably on Claude Code but almost never on Codex CLI. What's the highest-leverage thing to fix first?
4. 4Why is the security posture of Agent Skills fundamentally weaker than, say, npm packages with lockfiles and audit tooling?

Sources & further reading

• agentskills.io — the open specification and canonical directory.
• Agent Skills Open Standard Explained (paperclipped.de) — release timeline, adopting tools, marketplace scale.
• Portable SKILL.md across Codex CLI, Claude Code, and 30+ Tools (codex.danielvaughan.com) — extension surface and per-agent gotchas.
• SKILL.md: The Open Standard for AI Agent Skills (agensi.io) — protocol view and file structure.
• Anthropic Agent Skills Cross-Vendor Guide (qcode.cc) — per-agent activation and portability tips.
• AI Agent Skills Guide 2026 (thepromptindex.com) — practical author-side patterns and security notes.