What are Agent Skills?

How a skill loads, one stage at a time

A skill called writing-release-notes can sit in an agent's folder unread until someone asks for a summary of what shipped. That request matches its description, so the agent opens SKILL.md and starts on its steps, the first of which runs a bundled script.

Anthropic calls this progressive disclosure: the name and description sit in context from the start, and everything else waits. The open specification puts that first stage at about 100 tokens a skill, so twenty installed skills cost roughly 2,000 tokens before any of them fires.

When a step runs a bundled script, the script's code stays out of context and only its output goes in. In Anthropic's PDF example, the form-filling instructions sit in a separate forms.md, and Claude opens forms.md only when a form needs filling.

Both are X's own embeds, captured on 3 November 2026 with times in US Pacific time.

What goes inside a SKILL.md file

The specification requires two fields in a SKILL.md's YAML frontmatter. name takes lowercase letters, numbers and hyphens, and it must match the folder name. description says what the skill does and when to use it. Under the frontmatter come the instructions, in Markdown and in any format you like. The release-notes sample adds one optional field, license.

---
name: writing-release-notes
description: Writes release notes from a git log or a list of merged pull requests. Use when the user asks for release notes, a changelog entry or a summary of what shipped, even if they do not say "release notes".
license: MIT
---

# Writing release notes

1. Run scripts/group_commits.py to sort the commits into Added, Changed and Fixed.
2. Write one plain sentence per change, in the past tense, with what the user sees first.
3. Leave out refactors and dependency bumps unless they change behavior.
4. For wording rules and examples, read references/style.md.

## Gotchas

- Merge commits repeat the pull request title. Skip them.
- Never invent a version number. Ask if the user did not give one.

• scripts/: code the agent can run. Python, Bash and JavaScript are common, but what runs depends on the agent.
• references/: longer documents, such as the style.md the sample points to, or an API reference.
• assets/: templates, images and data files like lookup tables.

Which agents read Agent Skills?

Five coding agents document support. By their own lists, no single folder reaches them all: Claude Code, Cursor and Copilot read .claude/skills/, while .agents/skills/ covers every agent in the table below except Claude Code.

Anthropic built the format for Claude.ai, Claude Code, the Claude Agent SDK and the Claude Developer Platform, then published it as an open standard. Codex skills build on it too.

Claude.ai and the Claude API skip folders and take uploads. In Claude.ai you turn on code execution, then upload a zip file under Customize > Skills. An earlier version of this post said Settings, and we corrected it. On the API you upload through the Skills API and name the skill in a request alongside the code execution tool.

Is a skill the same as an MCP server?

No. The release-notes skill tells the agent which steps to take, in what order, and which merge commits to skip. If the merged pull requests sat in a system the agent couldn't reach, getting at them would take an MCP server. MCP is an open-source standard for connecting AI applications to external systems such as files, databases and search engines.

What makes a skill fire

Helps with PDFs. is the weak example in the specification's guide to descriptions, and its stronger version names the work: extracting text and tables, filling forms, merging files. The sample's description lists the ways people ask for one, down to "a summary of what shipped", because when the agent decides whether to load a skill, the description is all it has read.

Even a good description misses simple requests. Agents usually consult a skill only for tasks they can't handle alone, so a one-step request like reading a PDF may not trigger a matching skill. Models are nondeterministic too, and a request that fires a skill once can miss it the next time. So run each test prompt several times, near-misses included, before you trust a description.

Once a skill fires, every line of SKILL.md costs context, so the Agent Skills guide asks for under 500 lines, with detail moved into references/ and a line saying when to read each file. "Read references/api-errors.md if the API returns a non-200 status code" beats a vague "see references/ for details". Anthropic notes that Claude may only preview a file that another reference links to, so keep references one level deep from SKILL.md.

Is it safe to install someone else's skill?

Not until you've read it. A skill hands an agent instructions and can hand it code, and a bad one can misuse both, so Anthropic recommends installing skills only from trusted sources.

In Claude Code, a skill's code has the same network access as any other program on your computer. A downloaded copy of the release-notes skill would run scripts/group_commits.py with that access. On the Claude API the same script would run in a sandbox, with no network access and no way to install packages.

Anthropic's docs say to treat a skill like installed software. Before switching on one from a less trusted source, read SKILL.md, every file in scripts/ and any code dependencies, and stop at unexpected network calls, odd file access or data leaving through tools. Search the files, too, for paths outside the project and for instructions that send the agent to untrusted outside sources, then try the skill in a throwaway project. A skill that fetches content from outside URLs is only as safe as those pages, which can change after you've checked it.

GitHub is blunter about skills installed with its CLI: they are not verified by GitHub and may contain prompt injections, hidden instructions or malicious scripts.

The optional allowed-tools field can pre-approve the shell tool, so terminal commands run without a confirmation. The specification marks it experimental, and support varies between agents. Gemini CLI, for one, asks you to confirm before it activates a skill.

Where to find skills and where to share yours

The anthropics/skills repository holds Anthropic's own examples, many open source under Apache 2.0, while the Word, PDF, PowerPoint and Excel skills are source-available. Its README calls them all demonstration material to test in your own environment first. In Claude Code, /plugin marketplace add anthropics/skills adds it as a plugin marketplace, and plugins are also how Anthropic suggests handing your own skills to people outside the repository.

Mindket is an independent store, not affiliated with or endorsed by Anthropic, OpenAI or Google. Its skills page lists prompt skills you paste into an AI chat, a different thing from SKILL.md folders. Its MCP servers page shows, for each server, the line that adds it to Claude Code. If you've written a skill other people would use, you can sell it there, free or for credits. Its kits are zips of ready-made files, and one can hold a skills folder for Claude Code.

We read the pages under Sources on November 2, 2026, and the GitHub Docs page, the specification, Anthropic's engineering post and the two changelogs again the next day, without trying any skill hands-on. Folder names and optional fields change between product versions.

Frequently asked questions

Sources

1. Anthropic Engineering: Equipping agents for the real world with Agent Skills (read November 3, 2026)https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
2. Agent Skills specification (read November 3, 2026)https://agentskills.io/specification
3. Agent Skills overview (read November 2, 2026)https://agentskills.io/home
4. Agent Skills: Best practices for skill creators (read November 2, 2026)https://agentskills.io/skill-creation/best-practices
5. Agent Skills: Optimizing skill descriptions (read November 2, 2026)https://agentskills.io/skill-creation/optimizing-descriptions
6. Agent Skills: Using scripts in skills (read November 2, 2026)https://agentskills.io/skill-creation/using-scripts
7. Claude Platform docs: Agent Skills overview (read November 2, 2026)https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
8. Claude Platform docs: Skill authoring best practices (read November 2, 2026)https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
9. Claude Help Center: Using Skills in Claude (read November 2, 2026)https://support.claude.com/en/articles/12512180-using-skills-in-claude
10. GitHub: anthropics/skills (read November 2, 2026)https://github.com/anthropics/skills
11. OpenAI: Build skills for ChatGPT and Codex (read November 2, 2026)https://learn.chatgpt.com/docs/build-skills
12. GitHub Docs: About Agent Skills (read November 2, 2026)https://docs.github.com/en/copilot/concepts/agents/about-agent-skills
13. GitHub Docs: Creating agent skills for Copilot (read November 3, 2026)https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-skills
14. VS Code docs: Use Agent Skills in VS Code (read November 2, 2026)https://code.visualstudio.com/docs/copilot/customization/agent-skills
15. Cursor docs: Agent Skills (read November 2, 2026)https://cursor.com/docs/context/skills
16. Gemini CLI docs: Agent Skills (read November 2, 2026)https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/skills.md
17. Model Context Protocol: What is MCP? (read November 2, 2026)https://modelcontextprotocol.io/docs/getting-started/intro
18. GitHub Changelog: GitHub Copilot now supports Agent Skills (read November 3, 2026)https://github.blog/changelog/2025-12-18-github-copilot-now-supports-agent-skills/
19. Cursor Changelog 2.4: Subagents, Skills, and Image Generation (read November 3, 2026)https://cursor.com/changelog/2-4