For two years, a single repository could carry three competing instruction files — one per coding agent — with no shared tooling between them. That fragmentation is now optional: a single SKILL.md can drive Claude Code, Codex, and Cursor from the same folder.
What SKILL.md replaces, and the open standard behind the consolidation
SKILL.md replaces the three per-agent instruction formats that previously fragmented a repo: CLAUDE.md for Claude Code, AGENTS.md for Codex, and .cursorrules for Cursor. Those formats shared no tooling and offered zero portability — the same guidance had to be authored and maintained three times. Agent Skills collapses them into one open format built around a required SKILL.md file, so a single skill directory can be discovered by every compliant agent.
The consolidation follows Anthropic's MCP playbook. Anthropic shipped Agent Skills on October 16, 2025 across Claude apps, Claude Code, and its Developer Platform API , then published the format as an independent open standard on December 18, 2025 at agentskills.io — nine days after MCP was donated to the Linux Foundation on December 9, 2025 .
Adoption moved fast. OpenAI and Microsoft added support within roughly 48 hours, and Codex gained official SKILL.md support in December 2025 . Cursor followed in version 2.4 on January 22, 2026, making SKILL.md files discoverable and invokable from its slash-command menu . As of mid-2026, roughly 40 products on the agentskills.io showcase support the standard — including GitHub Copilot, VS Code, Gemini CLI, Goose, and OpenCode — with governance under the Linux Foundation's Agentic AI Foundation .
Portable SKILL.md frontmatter and what goes in the optional subdirectories
A portable SKILL.md needs only two frontmatter fields: name and description. Everything else the format defines is optional, and everything client-specific stays out. The name must be 1–64 characters, lowercase letters, numbers, and hyphens only, and must match the parent directory name exactly . The description runs 1–1024 characters and should state both what the skill does and when to use it, because this is the trigger-matching text every agent reads at startup to decide whether to activate the skill .
Optional frontmatter adds license, compatibility (max 500 characters, for environment needs like required CLIs such as git, jq, or docker), metadata (an arbitrary key-value map for author or version), and the experimental allowed-tools — a space-separated pre-approval list such as Bash(git:*) Bash(jq:*) Read whose support varies by client, so treat it as a bonus, not a guarantee . One spec warning matters: avoid XML angle brackets in frontmatter, since they can inject unintended content into the system prompt .
Beyond the file, a skill directory may hold three optional subdirectories: scripts/ for self-contained Python, Bash, or JS executables, references/ for on-demand docs, and assets/ for templates, schemas, and images . These load only when the instructions call for them — not at startup. Progressive disclosure means agents load just name plus description (~100 tokens each) at startup, the full body only on activation, and referenced files last . Keep SKILL.md under 500 lines and roughly 5,000 tokens; Codex caps its initial skills list at 2% of the context window (or 8,000 characters when that window is unknown), so bloated descriptions get shortened and entries in large skill sets can be omitted entirely .
The following Python snippet — executed and verified — illustrates the consolidation: it writes one SKILL.md and maps the three legacy config files onto it.
from pathlib import Path
skill = """# Codebase Skill
Use this single SKILL.md for agent instructions:
- project conventions
- commands to run
- review and safety rules
"""
old_files = ["CLAUDE.md", "AGENTS.md", ".cursorrules"]
Path("SKILL.md").write_text(skill)
print("One SKILL.md replaces scattered agent instruction files:")
for name in old_files:
print(f"- {name} -> SKILL.md")
print("\nSKILL.md:")
print(skill)
Canonical directory, symlinks, and where Claude Code, Codex, and Cursor look
Keep one authoritative copy of the skill and let each agent find it where it expects. Put the source of truth at .agents/skills/<name>/SKILL.md — Codex's native repo path and the layout the wider ecosystem advertises as the universal project location . Codex resolves skills in priority order: the repo's .agents/skills (searched from the current directory up to the repo root), then $HOME/.agents/skills for the user, /etc/codex/skills for admins, and finally bundled system skills .
The catch is that Claude Code does not scan .agents/skills. It reads .claude/skills/<name>/SKILL.md in the repo and ~/.claude/skills/<name>/SKILL.md for personal skills . Cursor is narrower still: it reads only .cursor/skills/<name>/SKILL.md, added in Cursor 2.4 released January 22, 2026 . Rather than maintain three edited copies, symlink both client paths back to the canonical directory.
| Agent | Discovery path | Mapping |
|---|---|---|
| Codex |
.agents/skills/<name>/ (+ $HOME, /etc/codex) |
Canonical source |
| Claude Code | .claude/skills/<name>/ |
symlink → .agents/skills/<name>
|
| Cursor | .cursor/skills/<name>/ |
symlink or mirrored copy |
To skip the manual ln -s dance, the Vercel skills CLI installs one source into any of the three agents (claude-code, codex, cursor) at project or global scope, with copy or symlink modes — for example, skills install --agent claude-code --scope project --link . Validate the frontmatter before you link it anywhere: run skills-ref validate ./my-skill to confirm spec compliance , and wire that command into CI lint so a contributor's malformed name or description never drifts across the mirrored directories.
Cursor's inconsistency bug and the 36% SKILL.md sourcing hazard
Symlinks map the file into place, but they do not guarantee the agent actually reads it. Around May 2026, Cursor users reported that .agents/skills entries showed up in Settings and the slash-command menu yet never appeared in the injected <available_skills> prompt context in some builds — Cursor staff characterized this as an injection-stage bug and suggested a rule that explicitly lists skill names as a workaround . The practical rule: do not assume a symlink alone is enough. Keep .cursor/skills/ mirrors until you confirm injection behavior for your exact Cursor version, and test by running /skill-name in chat and checking that it lands in the active context .
Sourcing is the sharper risk. Because a skill can bundle executable scripts/, a 2026 audit reportedly found prompt-injection content in roughly 36% of tested community SKILL.md packages . Treat any third-party skill like a dependency: read the full body and every script before running, pin to a commit, and run skills-ref validate . As one framing from the standard's maintainers puts it, "review any skill's source before installing, as you would any dependency" (source: agentskills.io).
Finally, keep client-specific extras out of the shared file. Claude Code's dynamic context injection , Codex's agents/openai.yaml invocation policy such as allow_implicit_invocation: false , and Cursor's hooks all belong in per-agent wrapper files — fold them into the canonical SKILL.md and portability quietly collapses on the next tool update.
What to try next: author a team PR-review or changelog skill, publish it to the agentskills.io showcase, and add skills-ref validate to your CI lint step. One reviewed, standards-compliant file — then let each agent find it where it looks.
Frequently asked questions
Does SKILL.md work across Claude Code, Codex, and Cursor without extra setup?
Not automatically. The file format — YAML frontmatter plus a Markdown body — is shared, but each agent looks in a different place: Claude Code reads .claude/skills/<name>/SKILL.md, Codex reads .agents/skills from the current directory up to the repo root, and Cursor reads .cursor/skills/ . No shared auto-discovery exists across all three. Keep one canonical source (Codex's .agents/skills/<name> is the common project-native path) and use symlinks or the Vercel skills CLI — which installs to claude-code, codex, or cursor at project or global scope — to point every tool at that single directory .
What is the minimum a valid SKILL.md must contain?
Two frontmatter fields. The spec requires only name — 1–64 chars, lowercase letters, numbers, and hyphens, and it must match the parent directory name — and description, 1–1024 chars stating both what the skill does and when to use it . Everything else is optional: license, compatibility, metadata, the experimental allowed-tools list, and the scripts/, references/, and assets/ subdirectories. Keep the body procedural and under roughly 500 lines and 5,000 tokens, pushing long material into referenced files .
Do GitHub Copilot, Gemini CLI, or VS Code support SKILL.md?
Yes. As of mid-2026, roughly 40 products on the agentskills.io showcase support the standard, including GitHub Copilot, VS Code, Gemini CLI, Goose, and OpenCode alongside Claude, Codex, and Cursor, with governance under the Linux Foundation's Agentic AI Foundation . Support means each client reads the same shared file format, but discovery paths and invocation behavior vary — check each tool's docs for its expected skill directory before assuming zero-config portability.
Is the allowed-tools field reliable for limiting what a skill can execute?
No. allowed-tools — a space-separated pre-approved list such as Bash(git:*) Bash(jq:*) Read — is marked experimental, and support varies across clients . Claude Code implements tool pre-approval; other agents may silently ignore the field . Treat it as a usage hint, not a security boundary, and document in the compatibility field which agents actually honor it.
How should I evaluate a community-published SKILL.md before running it?
Review it like any dependency, because skills can bundle executable scripts. A 2026 audit reportedly found prompt-injection content in about 36% of tested community skills . Read the full SKILL.md body and every file under scripts/ before running, pin to a specific commit, and validate frontmatter with skills-ref validate ./my-skill . Be wary of XML angle brackets in frontmatter — the spec warns they can inject unintended instructions into the system prompt — and of undocumented network calls.
Top comments (0)