One SKILL.md, Every Agent: How to Build a Single Agent Skill That Works in Claude Code, Codex, Cursor, ChatGPT & Copilot

Anthropic donated the Agent Skills specification to the Linux Foundation's Agentic AI Foundation on 22 October 2026, making the SKILL.md format a vendor-neutral standard now integrated across 70+ platforms with over 1 million skills published and roughly 280 million installs. The handover, announced at AGNTCon + MCPCon North America in San Jose, also brought in OpenAI's Open Responses, Hugging Face's OpenEnv and Alibaba's OpenSandbox, with David Soria Parra and Mahesh Murag named as lead maintainers. Anthropic proposed a roadmap including versioned releases, a formal change process and published security guidance for skill authors and installers.

Quick Answer: Yes — one SKILL.md can run across agents. Since 22 October 2026, Agent Skills is a vendor-neutral standard under the Linux Foundation, already adopted by 70+ platforms. A skill works everywhere if it 1 uses only the spec's frontmatter fields, 2 lives in the shared .agents/skills folder, and 3 is copied or linked into each agent's own folder. Below: the full folder map, the portability rules, and a complete tested example you can copy. Last verified: October 2026 On 22 October 2026, Anthropic donated the Agent Skills specification — the name, the format, the GitHub organisation and the agentskills.io reference site — to the Agentic AI Foundation AAIF , the Linux Foundation's home for agentic standards. The same day, AAIF also took in OpenAI's Open Responses, Hugging Face's OpenEnv and Alibaba's OpenSandbox, growing from 3 to 10 hosted projects. Why it matters to you: the donation removes the last reason to hesitate. Agent Skills is no longer "a Claude feature other tools copied" — it is the shared standard, with 70+ platforms integrated, over 1 million skills published and roughly 280 million installs reported at the handover. Stewardship sits with the AAIF, but day-to-day the standard is maintained by engineers from Anthropic, Google, OpenAI and other companies acting as individuals — David Soria Parra and Mahesh Murag are named as the lead maintainers . Anthropic has proposed a starting roadmap: versioned releases, a formal process for proposing changes, and published security guidance for people who write and install skills . That last item is the official acknowledgement of the trust problem: with roughly 1 million skills published and ~280 million installs, install-time safety can no longer be tribal knowledge. The handover was announced on 22 October at AGNTCon + MCPCon North America in San Jose — Agent Skills was one of four new AAIF projects, and Anthropic's second donation to the foundation after MCP. Governance of the format moved; ownership of your skills did not. A skill you write remains your file, in your repo, under your licence. You do not need an AAIF membership, a paid account, or anyone's permission to publish one. The spec is shared; the folders are not. Claude Code, Codex, Cursor, Copilot and Gemini CLI each scan their own directories. Portability is therefore a file-organisation problem — and it is fully solvable, which is the rest of this guide. An Agent Skill is a folder containing a SKILL.md file: YAML frontmatter name and description are required plus plain-language instructions, optionally with scripts/ , references/ and assets/ subfolders for supporting files. The mechanism that makes skills cheap is progressive disclosure : at startup, an agent reads only each skill's name and description — a few dozen tokens. The full instructions load only when your request matches the description. Two consequences: Source one canonical copy in the shared .agents/skills folder — the location the standard points at and several agents already read directly — then link or copy it into the folders the others scan: | Agent | Personal all projects | Project this repo | |---|---|---| | Shared standard | ~/.agents/skills | .agents/skills | | Claude Code | ~/.claude/skills | .claude/skills | | GitHub Copilot | ~/.copilot/skills or ~/.agents/skills | .github/skills , .claude/skills or .agents/skills | | OpenCode | global config skills folder | .opencode/skills , also reads .claude/skills and .agents/skills | | Codex / Cursor / Gemini CLI | ~/.agents/skills shared | .agents/skills shared | Paths follow each vendor's current documentation — check your agent's docs page, as vendors are converging on .agents/skills and older per-tool folders are being kept as compatibility aliases. .agents/skills/<skill-name / in your repo for team skills, ~/.agents/skills/ for personal ones . ln -s ~/.agents/skills ~/.claude/skills or link individual skill folders if a tool already has its own skills . mklink /J %USERPROFILE%\.claude\skills %USERPROFILE%\.agents\skills , or a two-line PowerShell copy script you run after edits. Whichever you choose, edit only the master copy. Any task you have written a reusable prompt for at least twice can become a skill. Start from a prompt that already works — if you need one, draft it in the Prompt Generator https://promptstaging.site/ first, then convert it. The spec defines a small set of fields every agent understands. Tool-specific extras are ignored by some agents — and outright rejected by some upload flows the claude.ai skill upload is strict — so keep the shared file to spec fields and put tool extras in per-tool copies or metadata . | Field | Portable? | Rule | |---|---|---| | name | ✅ Required | 1–64 chars, lowercase letters/numbers/single hyphens, must match the folder name | | description | ✅ Required | What it does + when to trigger; keywords first | | license | ✅ | e.g. MIT or Proprietary | | compatibility | ✅ | Note any required tools/environment | | metadata | ✅ | Free-form key/values author, version… | | allowed-tools | ⚠️ Partial | Honoured by some agents, ignored by others — never rely on it alone | | Tool-specific fields e.g. Claude-only options | ❌ | Keep out of the shared file | Structure the body as: When to use and when not to → numbered steps → exact output format → edge cases . Keep the body under 500 lines / roughly 5,000 tokens ; move long reference material into references/ files the agent opens only when needed. Deterministic steps date maths, file renaming, format conversion belong in scripts/ . Judgement steps belong in prose. Every extra script is also attack surface — see the security check below. A complete, non-coding skill — chasing unpaid invoices, the kind of task professionals repeat weekly: --- name: invoice-chaser description: Draft a polite-but-firm payment reminder for an overdue invoice. Use when the user mentions an unpaid, overdue, or late invoice, a client who hasn't paid, or asks for a payment follow-up email. Not for quotes, receipts, or first invoices. license: MIT metadata: author: PromptStaging version: 1.0 --- Invoice Chaser When to use - An invoice is past its due date and the user wants a reminder drafted. - Do NOT use for issuing a first invoice, quotes, or payment receipts. Steps 1. Ask for or extract : invoice number, client name, amount + currency, due date, days overdue. 2. Choose tone by days overdue: 1–7 days = friendly nudge; 8–21 = firm, restate terms; 22+ = final notice, state next step. 3. Draft the email: subject Payment reminder: Invoice number — amount , body under 120 words, include amount, due date, and a clear pay-by date 7 days out. 4. End with one line: what changes if they don't pay late fee / pause of work , only if the user confirms one applies. 5. Output ONLY the email subject + body unless the user asks for explanation. Build this in the Skill Builder https://promptstaging.site/skill-builder.html , then run it through the Quality Check Builder https://promptstaging.site/quality-check-builder.html before installing it anywhere. Run five fresh prompts in each agent: three that should trigger the skill phrased differently each time — formal, casual, typo-ridden and two that should not adjacent tasks: a quote request, a receipt . Score: 3/3 triggers + 0/2 false fires = ship it. If it under-triggers, the description is too narrow — add the missing phrasings. If it over-triggers, add explicit "not for…" cases. A skill's scripts execute with your credentials . Before installing anyone else's skill: read the SKILL.md end to end, read every script, and only install from sources you would trust with code — because that is literally what it is. Pin a version; re-read on update. | Layer | What it carries | Loads | Example | |---|---|---|---| | SKILL.md | Know-how: procedure, format, judgement | On trigger progressive | "How we write release notes" | | MCP server | Capability: tools, data access, actions | Tool schemas upfront agents increasingly defer this cost | Query the billing database | | AGENTS.md | Always-on project rules | Every session | "Use pnpm; never edit migrations" | New since September 2026: MCP's SEP-2640 extension lets an MCP server publish skills alongside its tools — the layers are converging, not competing. When you need the capability half, build it in MCP Studio https://promptstaging.site/mcp-builder.html . | Symptom | Likely cause | Fix | |---|---|---| | Skill never triggers | Description too vague or missing user phrasings | Rewrite description trigger-first; add real user wording | | Skill triggers on everything | Description too broad; no exclusions | Add "Not for…" cases to the description | | Description seems cut off | Agent's context budget for descriptions | Front-load keywords; shorten; fewer skills installed | | Upload rejects the file | Tool-specific frontmatter fields | Strip to spec fields table above for the shared file | | Agent ignores parts of the instructions | Body too long / buried rules | Under 500 lines; critical rules first; bulk to references/ | | Edits don't show up on Windows | Edited a copy, not the master junction/copy setup | Edit only .agents/skills ; re-run the copy script | Does one skill work in Claude Code, Codex and Cursor? Yes — the Agent Skills format is a shared standard, and all three read SKILL.md files. What differs is the folder each one scans; keep the master in .agents/skills and link or copy it into each agent's folder map above . Where do I put SKILL.md files? In a folder named exactly after the skill, inside a skills directory: .agents/skills/<name /SKILL.md for the shared standard location, .claude/skills/<name /SKILL.md for Claude Code, .github/skills/<name /SKILL.md for Copilot projects — personal skills live in the matching folders under your home directory. How long should a SKILL.md be? Keep the body under 500 lines about 5,000 tokens . Longer material belongs in references/ files inside the skill folder, which the agent opens only when the task needs them. Do I need to code to write a skill? No. A skill is a Markdown file with a small YAML header. Scripts are optional and only worth adding when a step has exactly one correct answer. The invoice-chaser example above is prose only. Is SKILL.md the same as AGENTS.md? No. AGENTS.md holds always-on project rules and loads every session. A SKILL.md loads only when a request matches its description — it is on-demand know-how, not standing rules. Most setups use both. Are Claude Skills and Agent Skills the same thing? Agent Skills is the open standard Anthropic created and donated to the Linux Foundation's Agentic AI Foundation in October 2026. "Claude Skills" is Anthropic's implementation of that same standard inside Claude products — skills written to the standard also work in other agents. Take one prompt you reuse weekly and turn it into a skill: draft it in the Skill Builder https://promptstaging.site/skill-builder.html , validate it with the 5-prompt trigger test, and install it from one master folder. Want ready-made starting points? The Skills Directory https://promptstaging.site/skills-directory.html collects production skills — including release notes for developers and listing copy, invoice and HR skills for professionals — that you can copy, customise and run through the same test before they go anywhere near your agents.