EXPLAINER
What are agent skills?
An agent skill is a folder containing a SKILL.md file: a few lines of frontmatter that tell an agent when the skill applies, and markdown instructions the agent loads only when it does. That is the whole format, and it is why hundreds of them now exist.
Written by Additionupdated 11 September 2026
The definition, from the specification
The Agent Skills specification, published at agentskills.io and used by Claude Code, Claude.ai, Cursor, Codex and other agents, defines a skill as a directory containing at minimum a SKILL.md file. Optional subdirectories hold scripts (executable code), references (documentation loaded on demand) and assets (templates and data).
The frontmatter has two required fields and four optional ones. Everything after the frontmatter is markdown with no format restrictions; the specification recommends step-by-step instructions, examples and edge cases, and keeping the file under 500 lines.
| Field | Required | Rule |
|---|---|---|
| name | yes | 1 to 64 characters, lowercase letters, digits and hyphens; must match the folder name |
| description | yes | 1 to 1,024 characters; says what the skill does and when to use it, with the keywords a request would contain |
| license | no | a licence name or a bundled licence file |
| compatibility | no | up to 500 characters of environment requirements (product, packages, network) |
| metadata | no | string key-value pairs, for example author and version |
| allowed-tools | no | space-separated pre-approved tools; marked experimental |
Why the description matters more than the body
Agents load skills progressively. At startup they read only the name and description of every installed skill, about a hundred tokens each. When a request matches a description, the agent loads the full SKILL.md. Reference files are loaded only when an instruction calls for them.
So the description is the routing layer. A skill whose description says "helps with SEO" is never chosen; one that says "use when the user says audit, full SEO check, analyze my site" is. The 25 skills on this site were selected partly on that: each item page shows the trigger phrases from the description.
Skill, prompt, MCP server, Cursor rule
| Thing | What it is | When it loads | Can it act |
|---|---|---|---|
| Prompt | text you paste into a conversation | when you paste it | no; it instructs the model for that turn |
| Skill | a folder with SKILL.md and optional scripts and references | when a request matches its description, or when you invoke it by name | through the agent’s own tools; scripts in the folder can run if the agent allows |
| MCP server | a program that exposes tools and resources over the Model Context Protocol | when the agent starts, if configured | yes; each tool is a function the agent can call, such as running a GA4 report |
| Cursor rule | a rules file Cursor applies to a project or to matching files | always, or by file pattern | no; it shapes behaviour |
A skill is the structured form of a prompt you kept pasting. An MCP server is how an agent reaches something outside the conversation. The two combine: the analytics skill on this site plans GA4 events; the Google Analytics MCP on the toolkit shelf reads the property those events land in.
Where skills run
Claude Code reads personal skills from ~/.claude/skills/ and project skills from .claude/skills/, and any of them can be invoked directly with a slash and its name. Claude.ai and the desktop app take skills as uploaded folders on plans that support custom skills, and can sync them to Claude Code. Cursor, Codex, Windsurf and others read the same SKILL.md format from their own folders; the npx skills add installer detects which agents you have and places the files.
The call-centre meaning of "agent skills" (a rep’s competencies) is unrelated and shares the phrase; if a search brought you here for that, this page is about software.
What a skill can do to your machine
Instructions only, in most cases. Twenty of the 25 skills on this site have no scripts at all; they are markdown the agent reads. The other five call a plugin’s Python scripts that fetch web pages and render them in a browser. A skill with scripts can do whatever those scripts do, which is why every item page here carries a four-row review: network, shell, secrets, deletes.
Questions
Questions people ask before installing
Is a skill the same as a Claude Code plugin?
A plugin is a package that can carry several skills plus agents, hooks and scripts, installed from a marketplace. claude-seo on this site is a plugin with 25 sub-skills; seo-audit is one of them.
Can I write my own?
Yes: a folder, a SKILL.md with name and description, and instructions. Our install page has the minimal file and the validator command.
Do skills work offline?
The instructions do. A skill that fetches pages or calls an API needs the network for those steps.