What Are Agent Skills? How They Work and What They're Used For

Agent Skills are packages of instructions in one open SKILL.md format that many AI agents share. Agents load them in three stages, and six vendors document support. Every example below carries our verdict, score and safety grade.

How an agent discovers, loads and runs an Agent Skill

 [1] DISCOVERY              [2] ACTIVATION             [3] EXECUTION
 name + description   -->   full SKILL.md body   -->   scripts, references
 about 100 tokens           under 5,000 tokens         opened on demand
 read at startup            read when a task matches   read only when needed

 Same format in: Claude | Codex | Copilot | Cursor | Gemini CLI | Microsoft Agent Framework

What are Agent Skills in AI agents?

Agent Skills are folders of instructions, scripts and resources that AI agents load on demand. Each skill centres on a SKILL.md file with a name, a description and instructions. Claude, Codex, Copilot, Cursor and Gemini CLI read the same format.

Anthropic introduced the format in an engineering post on October 16, 2025. Its own definition is short:

"Organized folders of instructions, scripts, and resources that agents can discover and load dynamically to perform better at specific tasks."

Other vendors describe the same thing in nearly the same words. Microsoft calls skills "portable packages of instructions, scripts, and resources." VS Code describes them as "folders of instructions, scripts, and resources that AI agents can load when relevant." Anthropic compares a skill to an onboarding guide written for a new hire.

The physical form is simple. A skill is a directory, and its one required file is SKILL.md. That file opens with YAML frontmatter and continues with Markdown instructions. Three optional folders can sit beside it: scripts/ for code, references/ for documentation and assets/ for templates.

The frontmatter needs only two fields, name and description. The agent reads the description to decide when the skill applies. The body tells it what to do once the skill is active. Nothing loads until a task calls for it, so an agent can hold many skills at little cost.

Anyone can publish a skill, and quality varies widely. Before you install one, you can see which Agent Skills pass our verdicts.

What does an Agent Skill look like?

An Agent Skill looks like a small folder with one Markdown file at its centre. The agentskills.io quickstart builds a working roll-dice skill as one file, under 20 lines. Here is an illustrative skill in the same shape:

roll-dice/
├── SKILL.md          required: frontmatter + instructions
├── scripts/          optional: code the agent can run
├── references/       optional: docs read on demand
└── assets/           optional: templates and files

---
name: roll-dice
description: Rolls dice and reports the result. Use when the user asks to roll dice.
---

The two lines between the dashes are the whole required metadata. Everything below the closing dashes is plain instructions for the agent. For the optional fields and their limits, read the SKILL.md file, field by field.

Which "agent skills" does this page mean?

This page covers SKILL.md packages that AI agents load. It does not cover human abilities for a support or sales agent. The A2A protocol uses the word differently. Its Agent Card holds a skills array listing what a remote agent offers (section 4.4.5). That array describes capabilities; nothing in it gets loaded into an agent.

Is an Agent Skill just a prompt?

No. An Agent Skill is a packaged procedure that loads only when a task matches its description. It can bundle scripts and reference files. A prompt applies once, and an MCP server connects live tools.

A prompt lives in one conversation and disappears with it. A skill stays on disk and returns whenever its description matches the task.

Google's explainer draws the same line. It says "Agent skills provide the procedural memory." It adds that "MCP provides a standardized protocol" for tools. The two work well together. A skill often tells the agent how to use an MCP server's tools in the right order.

Anthropic's Help Center separates skills from projects, MCP and custom instructions in a similar way. Projects hold background documents for one workspace. Custom instructions shape every reply. Skills hold a procedure that loads only for the matching task. Anthropic Academy draws a parallel split between skills, CLAUDE.md files and slash commands.

One more option matters for rules that must never be skipped. A hook runs every time an event fires, whatever the model decides. Claude Code's docs recommend hooks for that job, because a skill loads only when the model chooses it.

For the full trade-off with tool servers, read Agent Skills vs MCP servers.

How do agents load Agent Skills?

Agents load Agent Skills in three stages called progressive disclosure. At startup they read only each skill's name and description. They read the full SKILL.md when a task matches, then open scripts or references only when needed.

The specification names the three stages Discovery, Activation and Execution:

1. Discovery: The agent reads the name and description of every installed skill at startup.
2. Activation: The agent reads the full SKILL.md body when a task matches a description.
3. Execution: The agent opens scripts, references or assets only when the instructions point to them.

Microsoft's Agent Framework counts four stages instead of three. It splits execution into reading resources and running scripts. Both models describe the same flow, with the last step cut differently.

A large body costs context every time the skill activates.

The discovery stage has limits too. Codex caps its skill list at 2% of the context window or 8,000 characters. Each description competes for that space. A library of 200 skills with long descriptions fills it fast. Short, specific descriptions keep the catalog cheap and the matching accurate.

Where do agents look for Agent Skills?

Agents look for Agent Skills in folders that the client chooses. The specification leaves the location to each client. A shared convention has grown around .agents/skills/ for one project and ~/.agents/skills/ for one user.

Codex, VS Code, Cursor and Gemini CLI read the cross-client folders. Claude Code reads its own pair instead. For the exact paths and precedence rules, see where Claude Code stores skills.

What triggers an Agent Skill?

The description triggers an Agent Skill. Three rules decide when it fires:

• Description match: The agent compares the task with each description, capped at 1,024 characters by the spec.
• Explicit call: You name the skill with /skill-name in Claude Code, VS Code and Cursor, or $skill-name in Codex.
• Capability gap: Agents consult skills only for tasks beyond their own ability, per the agentskills.io guide on descriptions.

The 1,024-character limit appears in the spec, Google's explainer, VS Code's docs and Cisco's guide. A vague description gives the agent nothing to match against. For Claude's selection logic, read how Claude decides which skill to load.

What is the Agent Skills open standard?

The Agent Skills open standard is the SKILL.md specification published at agentskills.io. Anthropic developed it and released it as an open standard on December 18, 2025. One skill then works across compatible agents.

Six facts define the standard:

• Specification: agentskills.io/specification
• Created by: Anthropic
• Open standard since: December 18, 2025
• Spec repository: agentskills/agentskills on GitHub, created December 16, 2025
• Licence: Apache-2.0 for code, CC-BY-4.0 for documentation
• Clients listed: 46 on the agentskills.io client page, counted on 2026-10-20

The spec defines six frontmatter fields. Two are required: name and description. Four are optional: license, compatibility, metadata and allowed-tools. Our reference covers every frontmatter field in the spec with its limits.

Governance is less clear than the format. The spec repository sits under the agentskills organisation on GitHub. The agentskills.io site names no foundation or neutral steward. Third-party posts disagree on who coordinates the standard.

Which agents and vendors support Agent Skills?

Six vendors document Agent Skills support in their agents: Anthropic, OpenAI, Google, Microsoft, GitHub and Cursor. The agentskills.io client page lists 46 products. Our reviews show that support for a given skill is often claimed, not verified.

Six vendors document the format in their own products. Each one picks its own folders and activation method:

The table shows real differences under the shared format. Anthropic and Cursor activate skills automatically and accept a slash command. Codex adds a $skill-name prefix and a /skills menu. Gemini CLI asks for confirmation before its activate_skill tool loads a skill. Microsoft goes further and requires approval for all three skill tools by default. GitHub Copilot reads .claude/skills/ from Claude Code projects as well as its own folders. Cursor ships 19 built-in skills of its own.

Vendor support for the format is one question. Support for a given skill is another. A publisher can list ten agents in a README without testing any of them.

Our verdicts show both for each skill. Claimed support comes from the publisher. Verified support means an independent run or a reproducible report shows the skill working there. Of the skills we have reviewed, 28 are verified in Claude Code, 7 in Codex, 2 in the Claude app and 1 in Cursor. Outside Claude Code and Codex, verified support is rare. Read what "verified" means in our verdicts for the evidence rules.

Three things break portability:

• Client-only frontmatter: Claude Code fields get rejected by uploaders that accept only the spec's fields.
• Runtime differences: The Claude API runs skills without network access, so scripts that fetch data fail there.
• OS-bound scripts: Skill Creator's scripts failed on Windows in reports our verdict cites.

Claude Code has the deepest verified record so far. Browse Claude Code skills with verified support to start there.

What are Agent Skills used for?

Agent Skills are used to give an agent domain expertise, repeatable multi-step workflows and team context it lacks. Examples include brand rules, review checklists and deployment steps, packaged once and reused across compatible agents.

The specification names three main uses:

• Domain expertise: A skill teaches knowledge the model lacks, such as brand rules or a legal review checklist.
• Repeatable workflows: A skill turns a multi-step job into one procedure, such as a release checklist with fixed steps.
• Cross-product reuse: A skill written once works in every compatible agent, so a team keeps one copy.

Claude Code's docs give a simple test for when to write one. Make it a skill when you keep pasting the same instructions, checklist or multi-step procedure into chat. A pasted block costs effort every time. A skill costs it once.

Google lists five common jobs: code review, document processing, data analysis, security auditing and brand compliance. Anthropic ships four pre-built skills for its own document formats. Those cover PowerPoint, Excel, Word and PDF files.

The format does not require code. A skill can hold instructions alone. Of the skills we have reviewed, 17 contain no executable code at all. Style guides, review checklists and report templates all fit that shape.

What are some examples of Agent Skills?

Some examples of Agent Skills are Anthropic's Frontend Design, obra's Systematic Debugging and Remotion Best Practices. Vendors such as Neon, Supabase and Vercel publish skills for their own products. Of the skills we have reviewed, 10 rate Recommended.

The table below lists 10 real skills ordered by job, not by rank. Each row shows our verdict, score, safety grade, confidence and the commit we reviewed. The last row is a counter-example.

Four rows are vendor skills for the vendor's own product: Remotion, Neon, Supabase and Vercel Labs. Two come from Anthropic's own collection. The counter-example scores 50 and earns Not Recommended despite a clean A safety grade.

Across the skills we have reviewed, the spread is uneven. 10 earn Recommended and 10 earn Recommended with caveats. 18 are Conditional and 1 is Not Recommended.

Addy Osmani's Agent Skills pack on GitHub is another example. Cisco's Iris network-operations skill is an enterprise example from Cisco's blog; we have not evaluated it.

For a ranked view, open the full ranking of skills by verdict. To search by job or publisher, browse every skill we've judged.

What changed since our review?

Three skills on this page shipped new releases after our 2026-09-30 review. Their verdicts stand until we review them again.

• Addy Osmani's Agent Skills pack: we reviewed v0.6.11 at commit 2686b62. Version 0.6.13 shipped on 2026-10-13. Its PR #678, merged that day, says test-driven development applies to code pasted inline. That is a partial response to issue #620, which is still open.
• Systematic Debugging: we reviewed Superpowers v6.4.2. Superpowers v7.0.0 shipped on 2026-10-10.
• Find Skills: we reviewed vercel-labs/skills v1.7.0. Version 1.7.4 shipped on 2026-10-19.

Are Agent Skills safe to install?

No, not every Agent Skill is safe to install. A skill can run scripts and direct tool use. In our reviews, 17 skills hold no executable code, while 10 need credentials or broad permissions.

A skill is instructions plus optional code, and both reach your agent with its full permissions. The safety grade in each verdict sums up that risk. Here is how the skills we have reviewed break down:

• Grade A, 17 skills: no executable code.
• Grade B, 12 skills: scripts, with nothing alarming found.
• Grade C, 10 skills: credentials or broad permissions required.
• Grade F, no skills: unsafe.

The grade measures what a skill can do. The verdict measures how well it works. An A-grade skill holds no code, yet it can still give poor instructions. A C-grade skill needs credentials, yet a known vendor can publish it with care. Read the grade next to the verdict, never alone.

Public registries add their own risk. Snyk's ToxicSkills study scanned 3,984 skills from ClawHub and skills.sh. It found a critical issue in 13.4% of them, or 534 skills. 36.82%, or 1,467 skills, had at least one flaw. Snyk confirmed 76 malicious payloads in its report of 2026-02-05.

Three risks matter most:

• Bundled scripts run on your machine with the agent's access.
• Hidden instructions in SKILL.md or references can steer tool use away from your task.
• Credential requests expose API keys or tokens to code you have not read.

Anthropic's platform docs advise using skills "only from trusted sources" and auditing every bundled file. Microsoft's Agent Framework requires approval for all three of its skill tools by default. Before your next install, learn how to vet a skill before you install it.

How are Agent Skills different from Claude skills?

Agent Skills is the open, agent-neutral format. Claude skills are Agent Skills used inside Claude, Claude Code or the Claude API. Claude adds pre-built document skills and Claude Code-only frontmatter fields.

A Claude skill that sticks to the six spec fields can load in other agents. A skill that uses Claude Code's extra fields loses those features elsewhere. Some uploaders reject the extra fields outright.

The Claude side has more moving parts, from the listing budget to the Skill tool. Our guide on how Claude skills work and how Claude picks one covers them.

How do you install, use and create Agent Skills?

Install an Agent Skill by placing its folder where your agent scans, or by a plugin command. The agent then loads it automatically or when you invoke it. To create one, write a SKILL.md with a name and description.

Each agent has its own install route. The table lists the common ones:

Discovery routes vary as much as install routes. The skills.sh registry installs skills into many agents with one command. Vercel Labs publishes Find Skills, a skill that searches that registry from inside your agent. Directories such as agenticskills.io and the agent-skills topic on GitHub collect skills from other publishers. None of these routes reviews quality, so check the verdict before you copy a folder.

Once installed, a skill works in two ways. The agent loads it on its own when a task matches the description. You can invoke it by name with a slash command or the agent's own prefix.

Where can you learn more about Agent Skills?

Five sources cover Agent Skills in depth:

• agentskills.io hosts the specification, the client list and guides on writing descriptions.
• Anthropic's platform and Claude Code docs cover Claude's loading rules and extra fields.
• Anthropic Academy runs a course, "Introduction to agent skills".
• Microsoft Learn documents the Agent Framework's skill sources and approval rules.
• VS Code's docs cover Copilot's skill folders and slash invocation.

To write your first one, follow an Agent Skill tutorial, step by step.

Common questions

Are Agent Skills only for Claude?

No. Six vendors document support, and the agentskills.io client page lists 46 products.

Are Agent Skills worth using?

Yes, for many skills. Of the skills we have reviewed, 10 earn Recommended and 10 earn Recommended with caveats. Another 18 are Conditional and 1 is Not Recommended, so compare the best Claude skills by verdict.

What is the difference between an Agent Skill and an MCP server?

A skill teaches the agent a procedure, while an MCP server connects it to outside systems. Our comparison covers skills or MCP: which to use.

Where do global Agent Skills live?

Global skills live in user folders such as ~/.agents/skills/ or ~/.claude/skills/. Every project on that machine can use them.

Is there an official Agent Skills logo?

Yes, a wordmark. The agentskills.io site shows it, but we found no public usage guidelines for it as of 2026-10-20.

Who governs the Agent Skills standard?

Anthropic maintains the spec repository on GitHub. The agentskills.io site names no foundation or other steward.

Part of the Agent Skills guide on Verify AI Skills.