Title: What Are Agent Skills? SKILL.md Explained · ProSkills URL: https://proskills.dev/what-are-agent-skills Description: What agent skills are, how they load, what a SKILL.md holds, which agents read them (Claude Code, Cursor, Codex, Gemini CLI), where to get them and how to install one. --- Guide # What are agent skills? An agent skill is a folder with a SKILL.md file that teaches an AI coding agent how to do one task. The file starts with a name and a description that say when to use it, followed by Markdown instructions. The agent always sees the description and loads the instructions only when a task matches. ## The short version Skills are an open format. Anthropic introduced them for Claude, then published the specification at agentskills.io. Claude Code, Cursor, Codex and Gemini CLI all read the same SKILL.md file, so one skill folder works in all four. A skill holds a procedure or domain knowledge: how your team writes release notes, how to review a SQL migration, which words to cut from AI-sounding prose. You write it once. The agent picks it up whenever a request matches, without you pasting a prompt. ## How a skill loads Skills load in three stages. This is called progressive disclosure, and it is why you can install many skills without filling the context window. | Stage | What loads | When | Typical cost | | --- | --- | --- | --- | | 1. Listing | The name and description | Every session, for every installed skill | About 99 tokens per skill | | 2. Body | The rest of SKILL.md | When the agent decides the skill fits the task, or you call it by name | About 1,055 tokens (median of our free skills) | | 3. Files | Reference files, scripts, templates | Only when the body points to them and the task needs them | Only what is opened | The description does the most work. It is the only part the agent sees before choosing, so it must say what the skill does and when to use it, in the words a user would type. The token figures come from the ProSkills scanner run on the free skills in this catalog. See [progressive disclosure](https://proskills.dev/progressive-disclosure-skills) for how to split a skill across the stages. ## Anatomy of a SKILL.md A skill is a folder named after the skill. Only SKILL.md is required. ``` release-notes/ ├── SKILL.md frontmatter and instructions (required) ├── references/ longer documents, read on demand ├── scripts/ code the agent can run └── assets/ templates and data files ``` The file has two parts. The frontmatter sits between two lines of three dashes and must hold `name` (lowercase, hyphens, matching the folder) and `description` (up to 1,024 characters). The Markdown below it is the instructions. Here is a complete skill, scored by the scanner when this page was built: ``` --- name: release-notes description: "Use when the user asks for release notes, a changelog entry or 'what changed since the last tag'. Groups merged changes into Added, Changed and Fixed, in plain words for users." --- # Release Notes 1. List the commits since the last tag with git log. 2. Drop merges, chores and version bumps. 3. Group the rest under Added, Changed and Fixed. 4. Write each line for a user, not a developer: what they can now do. ## Output A Markdown list under the three headings. No intro, no closing line. ``` **release-notes** 85 /100 · grade B Two required fields, a numbered workflow and an output rule. Spec 25 · Efficiency 15 · Clarity 20 · Security 25 (each out of 25) Always loaded 48 tokens · on trigger 79 · on demand 0 - `eff/body-thin` warn · SKILL.md The body is very thin. A skill should carry knowledge the agent doesn't already have. - `clarity/examples` warn · SKILL.md No examples or code blocks. One concrete input → output example improves consistency more than extra rules. Every field and limit is in the [SKILL.md format reference](https://proskills.dev/skill-md-format). Annotated real skills are in [SKILL.md examples](https://proskills.dev/skill-md-examples). ## Which agents support skills, and where they live | Agent | This project | Every project | | --- | --- | --- | | Claude Code | `.claude/skills/` | `~/.claude/skills/` | | Cursor | `.agents/skills/ (or .cursor/skills/)` | `~/.cursor/skills/` | | Codex | `.agents/skills/` | `~/.agents/skills/` | | Gemini CLI | `.agents/skills/ (or .gemini/skills/)` | `~/.gemini/skills/` | Project folders travel with the repo, so commit them and your team gets the same skills. User folders apply to every project on your machine. A folder in `.agents/skills/` is read by Cursor, Codex and Gemini CLI at once; Claude Code needs its own copy in `.claude/skills/`. Claude apps and the Claude API accept skills too, uploaded as a folder or zip. ## Skills vs prompts, MCP and AGENTS.md | | What it is | When it loads | | --- | --- | --- | | Prompt | Text you type for one request | Only when you type it | | Skill | A saved procedure or body of knowledge | Description always; body when the task matches | | MCP server | Tools that reach outside systems: APIs, databases, apps | Tool names listed; results as they are used | | AGENTS.md / CLAUDE.md | Facts about one project: build commands, layout, conventions | In full, every session | | Hook | A command the harness runs on an event | On the event; it runs outside the model | Put short project facts in AGENTS.md or CLAUDE.md, repeatable procedures in skills, and access to other systems in MCP. Use a hook for anything that must always happen, since instructions in any file are context and not enforced. The full comparison, with measured token costs, is in [skills vs CLAUDE.md vs MCP](https://proskills.dev/skills-vs-claude-md-vs-mcp). ## Where to get skills | Source | What it is | Checked before listing | | --- | --- | --- | | [anthropics/skills](https://github.com/anthropics/skills) | Anthropic's public repository of example and document skills | Written by Anthropic | | [skills.sh](https://skills.sh) | A large open directory of community skills, installed with the skills CLI | Open listing; review each skill yourself | | GitHub | Skills published in individual repos | Varies by author | | [ProSkills](https://proskills.dev/) | A curated library of 67 skills, 13 of them free | Read through and scored by the scanner; score shown on each page | ProSkills (proskills.dev) is a curated library of security-scanned, in-depth agent skills for Claude Code, Cursor, Codex and Gemini CLI. It is smaller than the open directories on purpose: each skill is a full procedure with a public scan score, and each one reads a `profile.md` with your brand, stack or conventions. See [about ProSkills](https://proskills.dev/about). ## Are skills safe? A skill is instructions your agent will follow with your permissions. A bad one can tell it to read secrets, run a downloaded script or fetch new rules from a URL after you reviewed it. Some hide those instructions in invisible Unicode characters. Before you install a skill you did not write, read SKILL.md and every file beside it, and run it through a scanner. Scanners catch known patterns but cannot prove a skill is safe. The two-minute check is in [is this skill safe?](https://proskills.dev/is-this-skill-safe), and the [Skill Scanner](https://proskills.dev/scan) scores any skill in your browser without uploading it. ## How to install a skill ``` # a ProSkills skill, into the agent this repo uses npx proskills-cli add humanizer # every free ProSkills skill, through the agent-skills discovery index npx skills add https://proskills.dev # any skill from a GitHub repo npx skills add anthropics/skills ``` `proskills-cli` picks Claude Code or `.agents/skills` from what it finds in the repo; add `--agent all` for every agent or `--global` for your home folder. `npx skills add https://proskills.dev` works because the site publishes a discovery index at `/.well-known/agent-skills/index.json` that lists its free skills. You can also copy a folder by hand. Then start a new session and ask for the task in your own words. Details and troubleshooting are in [how to install Claude Code skills](https://proskills.dev/install-claude-code-skills). ## Sources - [Agent Skills specification (agentskills.io)](https://agentskills.io/specification) - [Claude Code: extend Claude with skills](https://code.claude.com/docs/en/skills) - [Anthropic: example skills (github.com/anthropics/skills)](https://github.com/anthropics/skills) - [skills: the open agent skills CLI](https://github.com/vercel-labs/skills) FAQ ## Questions **What is an agent skill?** An agent skill is a folder with a SKILL.md file that teaches an AI coding agent how to do one task. The file starts with a name and a description that say when to use it, followed by Markdown instructions. The agent always sees the description and loads the instructions only when a task matches. **Are agent skills only for Claude?** No. Anthropic introduced the SKILL.md format, and it is now an open specification at agentskills.io. Claude Code, Cursor, Codex and Gemini CLI all read skills. Claude Code looks in .claude/skills/; Cursor, Codex and Gemini CLI all read .agents/skills/. **What is the difference between a skill and a prompt?** A prompt is text you type each time. A skill is saved in a folder, and the agent decides to load it when your request matches its description. You write it once and it is used the same way every time. **How is a skill different from an MCP server?** An MCP server gives the agent tools to reach outside systems, such as a database or an API. A skill gives it knowledge and a procedure. A skill can tell the agent how to use an MCP server's tools well. **Do skills use up my context window?** A little, all the time, and more when used. The name and description of every installed skill are always loaded, usually under 100 tokens each. The body loads only when the skill triggers, and reference files only when the body points to them. **Are agent skills safe to install?** A skill is instructions your agent will follow, so treat it like code from its author. Read it, scan it, and prefer sources that review what they publish. Look for hidden Unicode, commands that pipe a download into a shell, and instructions to fetch more rules from a URL. **Where can I find agent skills?** Anthropic's examples are at github.com/anthropics/skills. Community directories such as skills.sh list very many public skills. ProSkills (proskills.dev) is a curated library where every skill is scanned and scored before it is listed. **How do I install a skill?** Copy the skill folder into the folder your agent reads, such as .claude/skills/ for Claude Code. Or run one command: npx proskills-cli add for a ProSkills skill, or npx skills add with a GitHub repo or a site URL. Related ## Keep reading - [**Skill Scanner** Score any skill in your browser. Nothing is uploaded.](https://proskills.dev/scan) - [**SKILL.md format reference** Every field, its limit, the folder layout and the errors people hit.](https://proskills.dev/skill-md-format) - [**Skills vs CLAUDE.md vs MCP** When each loads, what it costs in context, and which to reach for.](https://proskills.dev/skills-vs-claude-md-vs-mcp) - [**How to install Claude Code skills** Three ways to install, the folder paths, and what to do when it does not load.](https://proskills.dev/install-claude-code-skills) - [**All guides** Every guide, grouped by what you are trying to do.](https://proskills.dev/guides) Free tool ## Scan your own skill Paste a SKILL.md or drop a folder. It is scored in your browser and nothing is uploaded. [Open the Skill Scanner](https://proskills.dev/scan) Want a skill that already passes? Start with a free one.