Agent skills: how to write one SKILL.md that works across agents

Agent skills are folders that teach an AI agent a specific task. Each one holds a SKILL.md file, with a name and a description in YAML front matter and instructions below, plus any scripts, templates or reference files the task needs. The agent reads only the name and description when a session starts, and loads the rest when a request matches. On 22 October 2026 Anthropic donated Agent Skills, the open standard behind the format, to the Agentic AI Foundation (AAIF) at the Linux Foundation. Anthropic says more than 70 agent platforms have integrated it, including ChatGPT, Cursor, GitHub Copilot and VS Code.¹

The donation moved the name, the GitHub organisation and the agentskills.io domain to a vendor-neutral foundation and left the file format alone, so existing skills keep working. What still differs between agents is where each one looks for skills and which extra fields it accepts. A skill that keeps to the specification’s six front-matter fields and lives in .agents/skills/, with a link from .claude/skills/ for Claude Code, fits what every product in this post documents.

This post covers the format, the donation, where nine products load skills, how to write and test a portable skill, and when MCP or AGENTS.md fits better. Sources are the specification, vendor documentation and announcements published on or before 28 October 2026, and we haven’t tested these products ourselves.

What goes in a SKILL.md file

The specification on agentskills.io defines a skill as a folder with at least a SKILL.md file, which holds YAML front matter and then Markdown instructions in any shape. Two front-matter fields are required and four are optional.²

Optional scripts/, references/ and assets/ folders hold code the agent can run, documents it reads on demand, and templates or data files. A skill folder may hold other files as well.²

Agents load a skill in stages, which the specification calls progressive disclosure. At startup they read only name and description, about 100 tokens a skill, so the description is all an agent has to go on when it decides whether to load one.²³ When a request matches, the agent reads the whole SKILL.md body, which the specification suggests keeping under 5,000 tokens and 500 lines. Other files load only when the instructions send the agent to them.²

What changed when Agent Skills moved to the Agentic AI Foundation

Anthropic launched skills in Claude on 16 October 2025 and published Agent Skills as an open standard on 18 December 2025.⁴⁵ On 22 October 2026 the AAIF announced it as one of four new projects, which took the foundation to 10 hosted projects. The AAIF launched on 9 December 2025 with MCP, goose and AGENTS.md, and A2A has joined since.⁶⁷

The foundation now holds the Agent Skills name and logo, the agentskills GitHub organisation and the agentskills.io domain. Engineers from Anthropic, Google, OpenAI and other companies will maintain the standard as individuals, with David Soria Parra and Mahesh Murag as lead maintainers. Nobody has to join the AAIF to use the standard or contribute to it.¹

Anthropic also says 1 million skills have been published and nearly 280 million installed. These are Anthropic’s figures, and its post doesn’t say how it counts an install.¹

The format itself didn’t change. The specification file in the project’s GitHub repository last changed on 4 August 2026, when two wording clarifications were merged, and the repository had no commits between 9 August and 28 October.⁸ The specification has no version number either. Anthropic says it has proposed a roadmap that starts with versioned releases, a formal proposal process and security guidance for people who write and install skills, and it asks for feedback on proposed changes in the project’s Discord.¹ Until then, the contributing guide sends proposals to GitHub Discussions.⁹

Where Claude, Codex, Cursor, Copilot and Gemini CLI load skills

The specification defines what goes inside a skill folder and leaves the folder’s location to each product.¹⁰ This table pulls each vendor’s documentation together as of 28 October 2026. “Not stated” means the documentation doesn’t say.

Sources are each vendor’s documentation.^{111213141516171819202122}

Codex, Cursor, Copilot, VS Code and Gemini CLI all read .agents/skills/ in a project and ~/.agents/skills/ in the home folder. Claude Code’s documentation doesn’t mention .agents/skills/. Cursor, Copilot and VS Code also read a project’s .claude/skills/, but Codex and Gemini CLI don’t list it, so no single folder reaches every agent.

For claude.ai, the table follows Anthropic’s help centre, updated on 23 October 2026, although Anthropic’s developer docs still call claude.ai skills per user.¹²¹³

How to create an agent skill that works across agents

• Use only the specification’s fields. Uploads to claude.ai and the Skills API reject any other field with a hard error, and so does skills-ref, the reference validator.¹¹²³ Claude Code ignores fields it doesn’t recognise without a warning, so a misspelt one fails quietly there.¹¹
• Give the folder and the skill the same name. The specification requires it, and VS Code skips a skill with an invalid name without reporting an error.²²⁰ The Claude apps and API also reserve “claude” and “anthropic”.¹³
• Write the description as a trigger. Say what the skill does and when to use it, in a user’s words, and name close cases it shouldn’t handle.³ Put the main use case first. By default, Claude Code cuts each entry at 1,536 characters and drops descriptions when its list passes 1% of the context window, and Codex shortens them past 2%.¹¹¹⁵
• Keep the YAML plain. Leave out angle brackets, since the Claude API rejects XML tags in a description. Quote a description that contains a colon followed by a space. That is invalid YAML, and Claude Code then loads the skill with no description, so Claude can’t match it.¹³¹⁰¹¹
• Keep SKILL.md short. Stay under 500 lines and move detail into references/, with a line saying when to read each file.²²⁴ After compacting a conversation, Claude Code keeps only the first 5,000 tokens of each loaded skill, so put the important rules first.¹¹
• Use paths relative to the skill folder, such as scripts/check_entry.py, with forward slashes.²²⁰ Leave out features only Claude Code supports, such as placeholders like ${CLAUDE_SKILL_DIR} and ! command lines, which Anthropic says don’t run in the Claude apps or API.¹¹
• Write scripts that need nothing installed. The Claude API allows no network access or package installs, so use the Python standard library or plain shell.¹³ Agents run scripts in non-interactive shells, so a script must never prompt. Give it --help, clear errors and JSON output, and declare any packages inline, with PEP 723 for Python.²⁵

Here is a skill written to those rules. It drafts a changelog entry in a team’s format and checks it with a script that uses only Python’s standard library.

.agents/skills/changelog-entry/
├── SKILL.md
├── scripts/
│   └── check_entry.py
└── references/
    └── breaking-changes.md
.claude/skills/changelog-entry -> ../../.agents/skills/changelog-entry

---
name: changelog-entry
description: Writes and checks a CHANGELOG.md entry for the current change in this team's format. Use when the user asks for a changelog or release-note line, or is finishing a pull request that changes what users see, even if they don't mention the changelog. Not for release announcements or blog posts.
license: Apache-2.0
metadata:
  owner: platform-team
  version: "1.0"
---

# Changelog entry

1. Read the diff and pick one section for the change: Added, Changed, Fixed,
   Removed or Security.
2. Add one bullet under `## Unreleased` in CHANGELOG.md at the repository root.
   Describe what users will notice. End with the pull request number, as in (#123).
3. Run `python3 scripts/check_entry.py <path to CHANGELOG.md>`. It prints JSON and
   exits non-zero if a rule is broken. Fix the entry and run it again until it passes.
4. If the change breaks an API or a config format, read
   `references/breaking-changes.md` before you write the bullet.

## Gotchas
- Never edit the section of a version that has already shipped.
- One bullet per pull request, even when the change touches several areas.

Claude Code doesn’t list .agents/skills/, so the tree’s last line links the folder into .claude/skills/ with ln -s ../../.agents/skills/changelog-entry .claude/skills/changelog-entry. Claude Code’s docs allow a symlinked skill folder.¹¹ Cursor, Copilot and VS Code read both folders, and none of them says how it treats the same skill found in both, so check their skill lists after adding the link. A Windows clone with core.symlinks off gets a small text file in place of the link, and Claude Code won’t find the skill.²⁶ Windows teams can keep a copy instead, with a CI check that the two match.

Keep vendor-only fields out of the shared SKILL.md

Products add fields of their own and don’t agree on names. Claude Code, Cursor and VS Code read disable-model-invocation: true to stop the agent choosing a skill by itself. Codex skills set the same switch with allow_implicit_invocation: false in a separate agents/openai.yaml file.^11162015 Any vendor field in SKILL.md breaks uploads to the Claude apps and API, and fails skills-ref.¹¹²³

Where a product allows it, set the behaviour outside SKILL.md. Codex reads this sidecar file, and the specification permits extra files in a skill folder.¹⁵²

# agents/openai.yaml, read by Codex
policy:
  allow_implicit_invocation: false

In Claude Code, the skillOverrides setting can hide a skill from Claude without editing it.¹¹ Cursor and VS Code document only the front-matter field, so strip it before uploading the skill to claude.ai.

allowed-tools is in the specification but marked experimental, and its values differ by product. Claude Code takes permission rules such as Bash(python3 *), and Copilot takes tool names such as shell.²¹¹¹⁸ GitHub warns that pre-approving shell or bash can let an attacker-controlled skill or a prompt injection run commands without asking.¹⁸ We’d leave the field out of shared skills and grant tools in each product’s own permission settings.

Agent skills vs MCP vs AGENTS.md: which to use when

GitHub recommends custom instructions for simple guidance that applies to almost every task, and skills for detailed instructions an agent needs only sometimes.¹⁸ Anthropic says MCP connects Claude to data and skills teach Claude what to do with it.²⁷

A skill can also tell the agent which MCP tools to call, as GitHub’s example skill does with the GitHub MCP server.¹⁸ Claude Code, and VS Code in an experimental mode, can run a skill as a subagent with context: fork.¹¹²⁰ Claude Code’s troubleshooting guide moves a rule that must hold every time into a hook, which runs on its event whether or not Claude is still following the skill.¹¹ Our post on AGENTS.md vs CLAUDE.md covers which instruction file each coding agent reads.

Review third-party skills like any other dependency

A skill can carry scripts, and its Markdown tells the agent what to run, so a skill from outside your team is code. Anthropic says to use skills only from trusted sources and to audit every bundled file. GitHub says skills are not verified by GitHub and may contain prompt injections, hidden instructions or malicious scripts.¹³¹⁸ When Snyk scanned 3,984 skills from ClawHub and skills.sh in February 2026, it confirmed 76 as malicious and found at least one critical-level issue in 534, or 13.4%.²⁸

Our post on agent config files that run code covers skills alongside hooks and MCP config, with a CODEOWNERS block and a CI check. That block doesn’t list .agents/, so add it once your skills live there.

• Pin what you install. gh skill install, a public preview that needs GitHub CLI 2.90.0 or later, can pin a skill to a tag or commit, and gh skill preview shows its files before anything is installed.¹⁸
• Keep shell out of allowed-tools for any skill you didn’t write.
• Use the gates products offer, such as Gemini CLI’s approval prompt before a skill activates, and Claude Enterprise’s scanning of skills uploaded in claude.ai.²¹¹³

How to test a skill before your team relies on it

Test whether the agent loads the skill for the right requests, and separately whether the work is better with it than without. Claude Code’s docs make the same split and ask for a fresh session per run, because context left over from writing the skill hides gaps in it.¹¹ The steps below follow the agentskills.io guides. They are advice, and we haven’t run them for this post.

1. Check that it parses and shows up. Run skills-ref validate, which its README calls a demonstration library, or gh skill publish --dry-run. Both check the skill against the specification.²³¹⁸ Then confirm each agent lists the skill, for example by asking Claude Code “What skills are available?”, or with /skills in Codex and /skills list in Copilot CLI and Gemini CLI.^11151921
2. Measure triggering. Write about 20 realistic prompts, 8 to 10 that should load the skill and 8 to 10 near-misses that share its keywords but need something else. Run each three times. A prompt passes when its trigger rate is on the right side of 0.5. Tune the description on about 60% of the prompts, check it on the other 40%, and expect around five rounds. Use requests that need the skill, because agents tend to skip skills for one-step tasks they can do alone.³
3. Measure the output. Start with two or three test cases. Run each with and without the skill in clean sessions, add checkable assertions once you’ve seen the first outputs, and weigh the gain against the extra tokens and time.²⁹ Anthropic’s skill-creator plugin automates this loop in Claude Code.¹¹
4. Repeat for each agent and each change. Each product picks skills in its own way, so a trigger rate measured in one may not hold in another. Test in every agent the team uses, and again when the description, the model or the agent version changes.

Checklist for writing and rolling out a skill

1. Pick a task the team already does well, and write the skill from a real run and its corrections.²⁴
2. Limit the front matter to name and description, plus license or metadata if needed. The name matches the folder and avoids “claude” and “anthropic”. The description says what, when and when not.
3. Keep the body under 500 lines, with gotchas near the top and detail in references/.
4. Write scripts that use the standard library, never prompt and print JSON.
5. Store the skill in .agents/skills/<name>/ and link it from .claude/skills/<name>, or keep a checked copy on Windows.
6. Move vendor-only behaviour into agents/openai.yaml or skillOverrides.
7. Validate in CI with skills-ref or gh skill publish --dry-run, and give .agents/ and .claude/skills/ code owners.
8. Test triggering and output on every agent the team uses, with about 20 prompts at three runs each and two or three output cases.
9. Read third-party skills file by file, pin them and keep shell out of allowed-tools.
10. Re-run the tests when the description, the model or the agent version changes.

Frequently asked questions