AI agent skills: the complete guide to what they are and how they work (2026)

An AI agent skill is a folder with a SKILL.md file in it. The file has two parts: a short YAML header that says what the skill does and when to use it, and a Markdown body with the instructions. An agent reads every installed skill’s header at startup, and when your request matches one, it loads that skill’s body and follows it. That is the whole idea. The rest of this guide is the detail that makes it work well.

Skills exist because the alternatives were bad. People were pasting the same 40-line procedure into chat every morning, or stuffing every procedure into one always-on instruction file that cost thousands of tokens on every message whether relevant or not. Skills fix both: the instructions live in a file the agent owns, and they cost almost nothing until the moment they are needed.

The format, exactly

The Agent Skills specification is an open standard published at agentskills.io in December 2025 and adopted since by Anthropic, OpenAI, Cursor, GitHub, Microsoft, Google, and dozens of independent agents. A skill is a directory:

pdf-table-extract/
├── SKILL.md          # required: frontmatter + instructions
├── scripts/          # optional: code the agent can run
├── references/       # optional: docs the agent reads on demand
└── assets/           # optional: templates, images, data files

And SKILL.md looks like this:

---
name: pdf-table-extract
description: "Extracts tables from PDF files into CSV or JSON, handling multi-page tables and merged headers. Use when a task needs structured data pulled out of a PDF report, invoice, or form."
license: MIT
---
## Steps
1. Identify every page that contains a table.
2. Extract rows and columns, preserving header labels.
3. Merge tables that continue across a page break.
4. Normalize whitespace and currency formatting before returning output.

## Error handling
If a page is a scanned image with no text layer, say so instead of guessing.

The frontmatter fields the spec defines:

Field	Required	Constraint
name	Yes	1 to 64 characters. Lowercase letters, digits, and hyphens. No leading, trailing, or doubled hyphens. Must match the folder name.
description	Yes	1 to 1,024 characters. What the skill does and when to use it.
license	No	A license name or a pointer to a bundled license file.
compatibility	No	Up to 500 characters of environment requirements (tools, network, OS).
metadata	No	A string-to-string map for anything else (author, version).
allowed-tools	No	Experimental. Space-separated tools pre-approved for the skill.

Individual agents add their own optional fields on top (Claude Code has about a dozen, Cursor has paths, icon, and color), and every agent ignores fields it does not recognize. The compatibility matrix lists them all.

Progressive disclosure: why skills are cheap

The design property that makes skills practical is that they load in three stages.

1. Metadata, always loaded. At startup the agent reads only name and description from every installed skill. That is roughly 100 tokens per skill, so fifty installed skills cost about the same as one long paragraph.
2. Instructions, loaded on activation. When the agent decides a skill applies, it pulls the full SKILL.md body into context. The spec recommends keeping this under 500 lines and about 5,000 tokens.
3. Resources, loaded on demand. Files under scripts/, references/, and assets/ load only when the body points the agent at them for the current task.

Codex makes the budget explicit: the initial skill list is capped at 2% of the model’s context window, or 8,000 characters when the window is unknown. Every other tool applies the same principle without publishing a number. The practical consequence for authors is that the description is the only part of your skill the agent sees before deciding to use it, so it does most of the work.

How an agent picks a skill

There is no keyword index. The model reads all the descriptions and your request together and decides which, if any, applies. This is why “Helps with PDFs” is a poor description and “Extracts text and tables from PDF files, fills PDF forms, and merges PDFs. Use when the user mentions PDFs, forms, or document extraction” is a good one: the second contains the words a user is likely to type and states the trigger condition explicitly.

Once triggered, most agents also let you override the decision:

Agent	Force a skill	Make a skill manual-only
Claude Code	/skill-name [arguments]	disable-model-invocation: true
Cursor	/ picker for one message; Custom Mode for the session	disable-model-invocation: true
Codex	$skill-name	policy.allow_implicit_invocation: false in agents/openai.yaml
ChatGPT	@skill-name	Same openai.yaml policy
GitHub Copilot	Automatic by description; gh skill to manage	Not in frontmatter

Manual-only is the right setting for anything with side effects: deploying, committing, sending a message. You do not want the agent deciding on its own that the code looks ready.

Where skills live in each tool

Every agent reads skills from a project directory (committed to the repo, shared with teammates) and a personal directory (in your home folder, private to you). The paths differ per tool, and several tools also read a vendor-neutral .agents/skills path.

Agent	Project	Personal
Claude Code	.claude/skills	~/.claude/skills
Cursor	.cursor/skills, .agents/skills (also scans Claude and Codex dirs)	~/.cursor/skills, ~/.agents/skills
OpenAI Codex	.agents/skills (walks parent folders to the repo root)	~/.agents/skills
GitHub Copilot	.github/skills, .claude/skills, .agents/skills	~/.copilot/skills, ~/.agents/skills
Gemini CLI	.agents/skills	~/.gemini/skills
Windsurf	.windsurf/skills	~/.codeium/windsurf/skills
Cline	.agents/skills	~/.agents/skills
OpenCode	.opencode/skills	~/.config/opencode/skills

The full table for 60+ agents, with a machine-readable .txt guide per agent, is at skillmd.com/agents. If your repository serves a mixed team, .claude/skills is currently the most widely read single path, and a CLI that writes to every detected agent removes the question entirely.

Skills vs everything that looks like a skill

The AI tooling vocabulary is crowded. Here is where skills sit relative to the neighbors.

Skill vs prompt. A prompt is ephemeral text. A skill is a versioned file the agent owns, finds by description, and can pair with scripts and reference documents. If you have pasted the same instructions twice, you have a skill.

Skill vs always-on instructions (CLAUDE.md, .cursor/rules, copilot-instructions.md, AGENTS.md). Always-on files are in context on every message; they should hold facts and constraints about the project. Skills load on demand; they should hold procedures and reference material. Claude Code’s documentation puts it plainly: when a section of CLAUDE.md grows into a procedure rather than a fact, make it a skill.

Skill vs MCP server. MCP (Model Context Protocol) gives an agent tools and data: a running process that exposes actions like “query this database” or “open this pull request.” A skill gives an agent knowledge: how to do the task well, in what order, with what checks. They compose. A code-review skill tells the agent what a good review covers; a GitHub MCP server lets it read the pull request. The skills vs MCP article covers when to build which.

Skill vs subagent. A subagent is a separate worker with its own context window. A skill is instructions injected into the current context. Claude Code lets a skill launch as a subagent with context: fork, which blurs the line usefully. The Claude Code skills vs plugins vs subagents guide untangles that ecosystem.

Skill vs plugin. A plugin is a distribution bundle: several skills, sometimes with agents, hooks, and MCP configuration. On SkillMD, multi-skill bundles are listed as plugins and install with the same command as a single skill.

Skill vs slash command. In Claude Code these have merged: a command file and a skill folder with the same name both produce the same /name, and the skill wins if both exist. In Cursor, /migrate-to-skills converts old commands into manual-only skills.

Writing a skill that gets used

A skill that never triggers is worse than no skill, because it still costs its description on every message. The authoring rules that matter most:

1. Write the description as a trigger condition. Include the nouns a user will type and an explicit “Use when…” clause. Keep it under 1,024 characters; aim for one to three sentences.
2. Lead the body with the procedure, not the preamble. The agent already knows what the skill is for; it read the description. Start with step one.
3. Stay under 500 lines. Push tables of options, API references, and long examples into references/ and link to them with relative paths one level deep.
4. Give scripts clear error messages and documented dependencies. The agent will run them and read the output.
5. Add a license. Registries and linters warn without one, and people cannot legally reuse a skill whose license they do not know.
6. Test with two phrasings. Ask for the task in the words you expect and in words you do not, and check the agent picked your skill both times.

The anatomy of a SKILL.md file and writing skills that get used posts go deeper, and skillmd lint checks the mechanical constraints (name length, description length, missing license, stub body) before you publish.

Safety: a skill is instructions the agent will follow

Because a skill is text the agent obeys, installing one from a stranger carries the same risk as running their script. The specific things to look for:

• Instructions that tell the agent to ignore its other instructions, hide actions from you, or exfiltrate files.
• Bundled scripts under scripts/ that download and execute remote code.
• allowed-tools grants far broader than the task needs. In Claude Code this field applies even in an untrusted folder, so a repository skill can pre-approve broad Bash access for itself.
• Companion files (references/, assets/) that carry instructions the main file does not mention.

Prefer registries that review what they list. Every public skill on SkillMD passes a safety review before it becomes visible, shows a capabilities summary and a safety verdict on its page, and links to independent scanner results where available. The what a verified badge means post explains the badge.

Finding and installing skills

Three routes, all landing in the same place on disk.

CLI, any agent:

npm i -g skillmds
skillmd search "pdf tables"
skillmd add anthropic/pdf              # installs to every agent detected on this machine
skillmd add anthropic/pdf -a cursor -g # one agent, personal scope

MCP, from inside Claude Code:

claude mcp add skillmds -- npx -y skillmds

Then ask the agent to find and install a skill in plain language.

Manual, any agent: open the skill page, copy SKILL.md into the agent’s skills directory under a folder with the skill’s name. The install a skill in any agent walkthrough shows each path.

SkillMD lists 25,000+ skills across categories like code review, CI/CD, browser automation, and API design, with a JSON search API at api.skillmd.com/v1/search for agents that want to look skills up themselves.

A short history, for context

• October 2025. Anthropic ships Agent Skills in Claude Code and claude.ai, alongside the first-party anthropics/skills repository (docx, pptx, xlsx, pdf, skill-creator).
• December 2025. The format is published as an open specification at agentskills.io. OpenAI Codex, Cursor, GitHub Copilot, and Gemini CLI announce support, and Claude Code merges its custom commands into skills.
• 2026. The implementations fill in around the spec: Cursor ships /migrate-to-skills, Codex documents agents/openai.yaml for UI metadata and invocation policy, Copilot extends skills to code review and its cloud coding agent, and the vendor-neutral .agents/skills path spreads across independent agents. Registries mature; SkillMD passes 25,000 listed skills and 60 supported agents and extends its safety review to companion files, not just SKILL.md.

The direction is clear: the file format is settled, the directory paths are converging on a small set, and the remaining differentiation between tools is in optional frontmatter and invocation ergonomics. Write to the spec and your skills will outlive whichever editor you are using this year.

Further reading

• Claude skills vs Cursor skills
• Claude skills vs Codex skills
• Claude skills vs GitHub Copilot skills
• Agent skills vs MCP servers
• What is an Agent Skill? (short definition page)
• Glossary of agent skills terms