# What are Agent Skills?

> Agent Skills are folders that teach an AI agent one job, such as writing release notes. Each holds a SKILL.md file with a name, a description and plain instructions, and can carry scripts and reference files. The agent reads only the name and description until a request matches, then loads the rest. Claude, Claude Code and several other coding agents read the format.

Mindket editors · Published 2026-11-02 · Updated 2026-11-03 · https://mindket.com/blog/what-are-agent-skills

## In short

- If a skill never loads by itself, rewrite its description before anything else.
- Keep a skill meant for every agent in both `.claude/skills/` and `.agents/skills/`.
- Read every file in a stranger's skill, scripts included, before you switch it on.

## 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](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview): the name and description sit in context from the start, and everything else waits. The [open specification](https://agentskills.io/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](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills), the form-filling instructions sit in a separate `forms.md`, and Claude opens `forms.md` only when a form needs filling.

> Building a skill for an agent is like putting together an onboarding guide for a new hire.
>
> Anthropic, in its engineering post on Agent Skills, [Anthropic Engineering, 16 October 2025](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) (read 2026-11-03)

| Stage | What the agent loads | Context cost |
| --- | --- | --- |
| At startup | The name and description of every installed skill | About 100 tokens per skill |
| When a task matches | The full body of SKILL.md | Under 5,000 tokens recommended |
| As the task needs it | Reference files and assets, or a script's output | Nothing until read or run |

[![Claude's post on X: Claude can now use Skills, packaged instructions that teach Claude your way of working, with a video card of a desk lamp and a page, posted 16 October 2025](https://mindket.com/blog/shots/x-claudeai-skills-launch.webp?v=b112a861c948)](https://x.com/claudeai/status/1978855432123723909)

Claude on X, 16 October 2025

[![Alex Albert's post on X: Skills arrive in Claude.ai, Claude Code and the API as capabilities that Claude loads on demand, with a diagram of skill folders, posted 16 October 2025](https://mindket.com/blog/shots/x-alexalbert-skills-on-demand.webp?v=2f34b3787c36)](https://x.com/alexalbert__/status/1978877498411880550)

Alex Albert of Anthropic on X, 16 October 2025

> 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](https://agentskills.io/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`.

**Three limits the specification sets on the frontmatter**

- **64** characters at most in a skill's name (Source: [Agent Skills specification](https://agentskills.io/specification), read 2026-11-03)
- **1,024** characters at most in its description (Source: [Agent Skills specification](https://agentskills.io/specification), read 2026-11-03)
- **500** characters at most in the optional compatibility field (Source: [Agent Skills specification](https://agentskills.io/specification), read 2026-11-03)

````markdown
---
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](https://learn.chatgpt.com/docs/build-skills) 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](https://support.claude.com/en/articles/12512180-using-skills-in-claude). 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.

**Skills support, as each vendor dated it**

1. **October 16, 2025** Anthropic introduces Agent Skills. In Claude.ai, Claude Code and the API.
2. **December 18, 2025** Anthropic publishes Agent Skills as an open standard. A note added to its engineering post says so.
3. **December 18, 2025** GitHub Copilot adds Agent Skills. In its coding agent, its CLI and agent mode in VS Code Insiders.
4. **January 22, 2026** Cursor 2.4 ships skills. Defined in SKILL.md files, which the agent applies when a task fits.

Sources: [Anthropic Engineering](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) (read 2026-11-03), [GitHub changelog, 18 December 2025](https://github.blog/changelog/2025-12-18-github-copilot-now-supports-agent-skills/) (read 2026-11-03), [Cursor changelog 2.4, 22 January 2026](https://cursor.com/changelog/2-4) (read 2026-11-03)

| Agent | Project folders | Personal folders |
| --- | --- | --- |
| Claude Code | `.claude/skills/` | `~/.claude/skills/` |
| OpenAI Codex | `.agents/skills`, in the working directory and up to the repository root | `$HOME/.agents/skills` |
| GitHub Copilot and VS Code | `.github/skills/`, `.claude/skills/`, `.agents/skills/` | `~/.copilot/skills/`, `~/.claude/skills/`, `~/.agents/skills/` |
| Cursor | `.agents/skills/`, `.cursor/skills/` | `~/.agents/skills/`, `~/.cursor/skills/` |
| Gemini CLI | `.gemini/skills/`, `.agents/skills/` | `~/.gemini/skills/`, `~/.agents/skills/` |

## 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](https://modelcontextprotocol.io/docs/getting-started/intro) such as files, databases and search engines.

| Compared by | Agent Skill | MCP server | Prompt or custom instructions |
| --- | --- | --- | --- |
| What it is | Instructions in a SKILL.md file, with optional scripts and references | A connection from an AI app to data sources, tools and workflows | Text you type into a chat, or a file such as GEMINI.md that holds standing guidance |
| How it reaches the agent | Loaded on demand, in stages, when a task matches | The app connects to the server and gains its tools and data | Typed for one conversation, or loaded as background for the workspace |
| What it can bundle | Scripts and templates | Tools and data from an outside system | Mostly guidelines |

## What makes a skill fire

`Helps with PDFs.` is the weak example in the specification's [guide to descriptions](https://agentskills.io/skill-creation/optimizing-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](https://mindket.com/blog/how-to-create-agent-skill), near-misses included, before you trust a description.

Once a skill fires, every line of SKILL.md costs context, so the [Agent Skills guide](https://agentskills.io/skill-creation/best-practices) 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](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills).

In Claude Code, a skill's code has the [same network access as any other program on your computer](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview). 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](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-skills).

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](https://github.com/anthropics/skills) 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](https://mindket.com/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](https://mindket.com/sell) there, free or for credits. Its [kits](https://mindket.com/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

### Are Agent Skills only for Claude?

No, but a skill written with one product in mind can break in another, for instance when it names that product's tools. The optional `compatibility` field is where a skill states what it needs.

### Can a skill and an MCP server work together?

Yes. If the release-notes skill read its pull requests through an MCP server, its steps could name that server's tools and the order to call them in. [Anthropic's authoring guide](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) asks you to put the server's name in front of each tool's, as `ServerName:tool_name`, so the agent picks the right tool when several servers are connected.

### Do skills sync between Claude.ai, the API and Claude Code?

No. [Claude.ai uploads belong to one person, while API skills are shared across a workspace](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview), and Claude Code skills live on your own filesystem. An API skill doesn't show up in Claude.ai either.

### How do I install a skill from Mindket?

Open the listing and press Get it for a free one, or Buy for a paid one, signed in with a Mindket account. There you can read the skill and copy it into any AI chat, with your text where it says {{input}}. Nothing runs until you paste it. A kit downloads as a zip that you unzip into your project, with any skills folder going in `.claude/skills/`. Nothing in a kit runs by itself.

## Sources

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

[Browse skills](https://mindket.com/skills)