Summary: Agent Skills is the open SKILL.md format that Claude Code, Cursor and GitHub Copilot all read, so one folder of instructions can follow you between tools. The catch is that each tool looks in different folders and adds its own frontmatter fields. This guide shows the one folder location all three read today, a minimal skill that passes the official validator, and which extra fields break portability.
Everything here was checked today against the Agent Skills specification at agentskills.io, Anthropic's announcement, the anthropics/skills repository, and the skills pages in the Claude Code, Cursor, VS Code and GitHub Copilot docs. I also installed the reference validator (skills-ref 0.1.0) from the agentskills GitHub repository and ran it against a valid skill and five deliberately broken ones; the real output is in the screenshots at the end of this post. I did not run the skill inside every paid product, so where a doc is the only evidence I say so.
What Agent Skills is, in one paragraph
A skill is a folder with a SKILL.md file in it. The file starts with YAML frontmatter (at minimum a name and a description) followed by plain Markdown instructions. The folder can also hold scripts/, references/ and assets/. Agents load skills in three steps: at startup they read only the name and description of every skill, when a task matches a description they read the full SKILL.md, and only then do they open the bundled files they need. That is why a good description matters more than a long body.
Anthropic built the format while working on Claude Code, published it as an open standard in December 2025, and on October 22, 2026 donated it to the Agentic AI Foundation (AAIF) under the Linux Foundation, the same home it gave the Model Context Protocol. The announcement says more than 70 agent platforms, including ChatGPT, Cursor, GitHub Copilot and VS Code, have integrated it. The specification now lives at agentskills.io, while github.com/anthropics/skills is Anthropic's own collection of example skills (its README says so at the top).
Step 1: Put the skill where every tool can find it
This is the part most tutorials skip. Each product documents its own folders:
- Claude Code reads project skills from
.claude/skills/<name>/SKILL.mdand personal skills from~/.claude/skills/. Its skills page lists only.claudelocations (plus enterprise, nested,--add-dirand plugin locations); I found no mention of.agents/skillsthere. - Cursor reads
.agents/skills/and.cursor/skills/in the project and~/.agents/skills/and~/.cursor/skills/for your user, and "for compatibility" also loads.claude/skills/,.codex/skills/and their home-folder versions. - GitHub Copilot supports project skills in
.github/skills,.claude/skillsor.agents/skills, and personal skills in~/.copilot/skillsor~/.agents/skills. VS Code's Local sessions also read.claude/skills/and.agents/skills/.
Put those lists side by side and one project folder is on all of them: .claude/skills/. The newer vendor-neutral .agents/skills/ works for Cursor, Copilot and Codex, but according to the docs above it would not be picked up by Claude Code. So for a repository shared by people on different tools, today's safest layout is:
your-repo/
└── .claude/
└── skills/
└── release-notes/
├── SKILL.md
└── scripts/
└── changes.sh
If your team uses only Cursor and Copilot, .agents/skills/ is the cleaner, tool-neutral choice. For personal skills there is no single shared home folder across all three, so you would keep a copy (or, in Claude Code's case, a symlink, which its docs explicitly support) in each tool's location.
Step 2: Write a SKILL.md that passes the spec
The specification allows only six frontmatter fields: name and description (required), plus license, compatibility, metadata and the experimental allowed-tools. Here is the minimal skill I validated:
---
name: release-notes
description: Drafts release notes from merged pull requests using the team template. Use when the user asks for release notes, a changelog, or a summary of what shipped.
license: MIT
metadata:
author: example
version: "1.0"
---
# Release notes
1. Run scripts/changes.sh
The rules for name: 1 to 64 characters, lowercase letters, digits and hyphens only, no leading or trailing hyphen, no double hyphen, and it must match the folder name. The description can be up to 1,024 characters and should say both what the skill does and when to use it, with the words a user would actually type. "Helps with PDFs" is the spec's own example of a poor description.
For the body, the spec recommends step-by-step instructions, input and output examples and edge cases, keeping SKILL.md under 500 lines (roughly under 5,000 tokens) and moving long material into references/. Reference files with relative paths from the skill root, and keep them one level deep.
Step 3: Validate it before you commit
The agentskills project publishes a reference library called skills-ref. I installed it into a Python virtual environment straight from the GitHub repository (the package is in the skills-ref subfolder of agentskills/agentskills) and ran skills-ref validate ./release-notes. It printed "Valid skill: release-notes". Then I broke things on purpose. These are the exact failures it reported:
- Folder
notes-dirwithname: release-notes: "Directory name 'notes-dir' must match skill name 'release-notes'". name: Release-Notes2: "must be lowercase".name: double--hyphen: "cannot contain consecutive hyphens".- No description: "Missing required field in frontmatter: description".
- A 1,100-character description: "Description exceeds 1024 character limit".
- A skill using
disable-model-invocationandpaths: "Unexpected fields in frontmatter".
That last result is the interesting one, because both of those fields are documented and useful in Claude Code and Cursor. The tool also has a to-prompt command that prints the <available_skills> block an agent would see, which is a quick way to read your description the way the model reads it.
Step 4: Decide how much vendor-specific frontmatter to use
Each product extends the six standard fields. Claude Code adds disable-model-invocation, user-invocable, context: fork, paths, model, hooks and more, and it even treats name as optional (it defaults to the folder name). Cursor adds paths, disable-model-invocation, icon and color. VS Code adds argument-hint, user-invocable, disable-model-invocation and an experimental context: fork.
My rule of thumb: keep shared skills to the six spec fields so the validator stays green, and only add vendor fields in a skill that you know is used by one tool. disable-model-invocation: true is the most widely shared extra (Claude Code, Cursor and VS Code all document it as "only run when I type /name"), so it is the one I would accept if you need manual-only skills, knowing the strict validator will flag it.
Where each tool reads skills
| Tool | Project folders | Personal folders | Extra frontmatter (examples) | Access notes from the docs |
|---|---|---|---|---|
| Claude Code | .claude/skills/ (also nested and --add-dir) | ~/.claude/skills/ | disable-model-invocation, user-invocable, context, paths, model | Custom skills on claude.ai are separate uploads (Pro, Max, Ultra, Team, Enterprise with code execution); skills do not sync between claude.ai, the API and Claude Code |
| Cursor | .agents/skills/, .cursor/skills/ (also reads .claude/skills/, .codex/skills/) | ~/.agents/skills/, ~/.cursor/skills/ (also ~/.claude/skills/, ~/.codex/skills/) | paths, disable-model-invocation, icon, color | Only ~/.cursor/skills/ can sync to Cloud Agents; automations need the skill in the repo |
| GitHub Copilot (incl. VS Code) | .github/skills, .claude/skills, .agents/skills | ~/.copilot/skills, ~/.agents/skills | argument-hint, user-invocable, disable-model-invocation, context (experimental) | Copilot CLI on all Copilot plans; cloud agent on paid plans |
Editor's note
Good fit: teams whose members use different coding agents and keep repeating the same multi-step chores (release notes, test runs, deploy checklists, review rules). One skill in .claude/skills/ replaces three copies of the same prompt.
Not a fit: always-on coding style rules. VS Code's docs draw this line clearly: custom instructions such as AGENTS.md are always applied, skills load on demand. Put formatting rules in instructions, workflows in skills.
Gotchas I hit or confirmed:
- A skill silently not loading in VS Code is often the name: its docs say slashes, colons, dots or prefixes like
myorg:skillinnamemake the skill "silently fail to load". Plugins add the prefix for you. - Folder and
namemismatch is the most common validator failure, and Claude Code hides it because it falls back to the folder name. - Personal skills do not follow you into the cloud. Claude Code's cloud sessions and Cursor's automations do not read your home folder; commit the skill to the repository instead.
- Skills can contain scripts. Both Anthropic and VS Code tell you to review every bundled file before installing a skill from someone else.
FAQ
Is anthropics/skills the standard?
No. Its README says it is Anthropic's implementation and examples for Claude; the standard itself is at agentskills.io and is now maintained under the AAIF. The repository is still the best place to read real, production-sized skills such as the docx, pdf, pptx and xlsx ones, which it says are Apache 2.0 licensed.
Can I use a skill from the repository directly in Copilot or Cursor?
Yes, as long as you copy the whole folder (not just SKILL.md) into a supported location. GitHub's docs name anthropics/skills and github/awesome-copilot as sources and mention gh skill for installing skills from repositories. Cursor's docs say repository imports go through a plugin marketplace rather than being pulled in automatically.
Do I need to pay to use Agent Skills?
The format and the validator are free and open. Whether the agent that reads them costs money depends on the product: GitHub's docs list Copilot CLI on all Copilot plans and the cloud agent on paid plans, and Claude's docs list custom skill uploads on claude.ai for paid plans with code execution enabled.
Related reading on this blog: Claude Code Errors Fixed: Login, PATH, 429 and Usage Limits if Claude Code itself will not start, GitHub Copilot Pricing: Free, Pro, Pro+ and Max Credits to see which Copilot plan you need, and Promptfoo Tutorial: Test Your LLM Prompts Before You Ship for testing the instructions you put in a skill.
Start with one boring, repeated task, put it in .claude/skills/, run the validator, and let every agent on your team share it.
See the official screenshots at the end of this post. Image credit: my own screenshots of the public Agent Skills specification (agentskills.io), Cursor Docs and VS Code Docs, plus my own terminal output from skills-ref.
Last verified: 2026-11-11
Sources: Agent Skills specification, Agent Skills overview, Anthropic: Donating Agent Skills to the Agentic AI Foundation, anthropics/skills, skills-ref reference library, Claude Code: Skills, Claude Docs: Agent Skills overview, Cursor Docs: Agent Skills, VS Code: Use Agent Skills, GitHub Docs: Agent skills.
댓글
댓글 쓰기