Agent Skills：如何建立一份可供 Claude Code、Codex、Cursor、ChatGPT 與 Copilot 共用的 SKILL.md

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

What changed on 22 October 2026 — Agent Skills got a neutral home

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.

Who steers it now — and what's next

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.)

What Anthropic did NOT donate: your skills

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.

What did not change: every agent still reads a different folder

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.

What an Agent Skill is (the 60-second version)

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:

1. The description is the product. It decides whether your skill ever fires. Write it like a trigger, not a summary: what the skill does and the exact situations that should activate it, trigger words first. Some agents cap how much description text they ingest (Codex, for example, budgets roughly 2% of its context window for skill descriptions across all skills), so front-load the keywords.
2. Skills cost almost nothing to keep installed. Dozens of skills can sit in your folders for the price of a paragraph of context — the opposite of an always-loaded system prompt.

The cross-platform folder map

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:

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.

The one-canon setup (don't maintain five copies)

1. Keep the master copy of every skill in .agents/skills/<skill-name>/ (in your repo for team skills, ~/.agents/skills/ for personal ones).
2. On macOS/Linux, symlink the per-agent folders to the master: ln -s ~/.agents/skills ~/.claude/skills (or link individual skill folders if a tool already has its own skills).
3. On Windows, symlinks need developer mode/admin — use a directory junction instead: 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.

Build one skill, step by step

Step 1 — Pick a repeat prompt

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 first, then convert it.

Step 2 — Write frontmatter with ONLY the portable fields

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.

Step 3 — Write the instructions

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.

Step 4 — Add a script only where a step has exactly one correct answer

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.

Step 5 — The worked example (copy this)

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, then run it through the Quality Check Builder before installing it anywhere.

Test it in three agents before you ship it

The 5-prompt trigger test

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.

Security check — read skills like packages

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.

Skills vs MCP vs AGENTS.md — which layer is which

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.

Troubleshooting — the 6 failures everyone hits

FAQ

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.

Start now

Take one prompt you reuse weekly and turn it into a skill: draft it in the Skill Builder, validate it with the 5-prompt trigger test, and install it from one master folder. Want ready-made starting points? The Skills Directory 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.