Agent Skills
Folders of instructions, scripts and resources (SKILL.md) that an agent discovers by description and loads on demand through progressive disclosure; an open standard read by Claude, Codex, Gemini CLI and Cursor.
Contents
An Agent Skill is a directory containing a SKILL.md file (YAML frontmatter with a name and a description, then Markdown instructions) and, optionally, scripts, reference documents and assets. The agent sees only each skill’s name and description at startup. When a task matches a description, it reads the body, and it opens bundled files or runs bundled scripts only if the task needs them. Anthropic introduced skills in October 2025 as a way to package procedural knowledge, the “how we do X here” that a new hire would get in an onboarding guide. Anthropic published the format as an open standard on 2025-12-18 at agentskills.io, and coding agents such as Codex, Gemini CLI and Cursor now read it (Anthropic, spec, Codex, Gemini CLI, Cursor). Skills are a context engineering mechanism. They don’t add new actions the way tools or MCP do. They add knowledge about how to use the actions an agent already has.
How progressive disclosure works
flowchart TD
A["Session start: name + description of every enabled skill injected into system prompt (~100 tokens each)"] --> B{"User task matches a description? (or user types /name, $name)"}
B -- no --> Z["Skill costs only its listing entry"]
B -- yes --> C["Level 2: agent reads SKILL.md body into context (target < 5k tokens, < 500 lines)"]
C --> D{"Body points to a reference or script relevant to this task?"}
D -- "reference" --> E["Level 3: read references/finance.md etc. (only that file)"]
D -- "script" --> F["Run scripts/x.py via bash: only stdout enters context, code never does"]
D -- no --> G["Follow instructions"]
E --> G
F --> GAnthropic’s documentation gives these costs for each level (overview, spec):
| Level | Loaded | Typical cost |
|---|---|---|
1. Metadata (name, description) | always, at startup | ~100 tokens per skill |
2. SKILL.md body | when triggered | under 5k tokens recommended |
| 3. Bundled files and scripts | when read or run | zero until accessed; scripts cost only their output |
Because files stay on disk until the agent reads them, Anthropic calls the total content a skill can bundle “effectively unbounded” (Anthropic). The design has two prerequisites: the agent needs a filesystem and a shell or code-execution tool. This is why the Claude API only runs skills inside the code-execution container (see code execution sandboxes) (API guide).
Level 1 is not free at scale. Every model-invocable skill puts its description in front of every request:
- Claude Code caps the listing at about 1% of the context window. Once over the cap, it drops descriptions starting with the least-used skills and keeps only their names. It also truncates each description at 1,536 characters (Claude Code skills).
- Codex caps its list at 2% of the window (8,000 characters if the window size is unknown), shortens descriptions first and then omits skills.
skills.max_context_tokensraises the cap to at most 10k tokens (Codex).
Synthesis: a truncated description loses the keywords the model matches against. So past a few dozen skills, the usual failure isn’t context bloat. Skills simply stop triggering.
The format
The open spec requires two fields (spec):
name: 1–64 characters, lowercasea-z0-9-, no leading, trailing or doubled hyphens, and it must equal the directory name.description: 1–1024 characters, saying what the skill does and when to use it.
Optional fields are license, compatibility (≤500 characters), metadata (a string map) and an experimental allowed-tools. Anthropic’s API also rejects XML tags in either required field, and rejects names containing anthropic or claude (best practices). By convention, scripts/ holds executables, references/ holds on-demand docs and assets/ holds templates and data. References should sit one level deep from SKILL.md.
Harnesses extend the frontmatter in different ways:
| Harness | Locations | Invocation | Notable extensions |
|---|---|---|---|
| Claude Code | ~/.claude/skills, .claude/skills (walks up to repo root; nested dirs load lazily), managed, plugins | auto by description; /name | disable-model-invocation, user-invocable, allowed-tools/disallowed-tools, context: fork (run in a subagent), model, effort, paths, hooks, arguments, !`cmd` pre-execution |
| Codex | .agents/skills (repo), ~/.agents/skills, /etc/codex/skills, bundled | auto; $name or /skills | agents/openai.yaml: allow_implicit_invocation, UI metadata, MCP tool dependencies |
| Gemini CLI | .gemini/skills or .agents/skills (workspace > user > extension > built-in) | model calls activate_skill; user approves before body loads | skill dir becomes an allowed path on activation |
| Cursor (2.4+) | .cursor/skills, .agents/skills, plus .claude/skills and .codex/skills for compatibility | auto; /name; Custom Mode for whole session | paths, disable-model-invocation, icon/color |
| Claude API | uploaded via /v1/skills; container.skills (≤20 per request) | auto | pre-built pptx, xlsx, docx, pdf; versions pinned or latest |
Sources: Claude Code, Codex, Gemini CLI, Cursor, API guide.
The table shows a portability trap. Claude Code ignores unknown frontmatter keys without warning, but uploads to claude.ai or the Skills API hard-error on any key outside the open standard. Custom skills also don’t sync between claude.ai, the API and Claude Code (Claude Code skills, overview). Runtime environments differ too. API skills have no network access and cannot install packages, claude.ai network access depends on admin settings, and Claude Code has full network access (overview).
Slash commands converged into skills
A slash command is a user-triggered prompt template. Vendors are folding these into skills:
- Claude Code merged custom commands into skills:
.claude/commands/deploy.mdand.claude/skills/deploy/SKILL.mdboth create/deploy(Claude Code skills). - Cursor ships a
/migrate-to-skillscommand that converts slash commands into skills withdisable-model-invocation: true(Cursor). - Gemini CLI still keeps commands as a separate TOML format:
prompt,{{args}},!{shell}(which asks for confirmation before running) and@{file}injection (Gemini commands).
In Claude Code the remaining difference is who may invoke the skill:
| Frontmatter | User can invoke | Model can invoke | Context cost before use |
|---|---|---|---|
| default | yes | yes | description every request |
disable-model-invocation: true | yes | no | zero |
user-invocable: false | no | yes | description every request |
Mark skills with side effects (deploy, send, delete) disable-model-invocation: true. That way they run only when named, and their descriptions use no context (extend overview).
Skills vs tools, MCP, hooks, instruction files, subagents
| Mechanism | What it adds | Loaded | Deterministic? |
|---|---|---|---|
| Agent instruction file (CLAUDE.md/AGENTS.md) | always-on rules | every request | no (model may ignore) |
| Skill | on-demand procedure/knowledge + scripts | description always, body on match | no |
| Tool / MCP server | new actions and data access | tool names (schemas often deferred) | the action is; choosing it is not |
| Hook | handler run by the harness at a lifecycle event | nothing unless it returns output | yes |
| Subagent | isolated context window | when spawned | no |
| Plugin / extension | packaging of all the above | n/a | n/a |
Sources: extend overview, hooks.
Anthropic frames the MCP–skill relationship as complementary. MCP provides the connection to a system. A skill teaches how to use it well, for example a database schema plus the team’s query patterns (extend overview). Inside a skill, refer to MCP tools by their fully qualified Server:tool names (best practices). Skills and subagents combine in both directions. A subagent definition can preload skills, and a skill with context: fork runs in a subagent that sees only the skill content (Claude Code skills).
Hooks are the enforcement counterpart of skills. Claude Code, Codex and Gemini CLI have converged on a similar contract (Claude Code hooks, Codex hooks, Gemini hooks):
- A command runs on an event such as
PreToolUse/BeforeTool,PostToolUse,UserPromptSubmit,StoporSessionStart. - It receives JSON on stdin. Exit 2 blocks the action, with stderr sent back to the model as the reason. On
Stop-type events, blocking means the agent keeps working; Codex’sPostToolUsecannot undo a command that already ran, it only replaces the result the model sees. Exit 0 can return JSON decisions such as deny, ask, rewritten input or added context. - In Claude Code (and Gemini CLI), any other non-zero exit (including 1) is only a warning and the action proceeds. In Claude Code a failing or timed-out hook fails open unless a
command/httphook setsonFailure: "block"(v2.1.295+; no effect onStop,SubagentStopor async hooks).
Because hooks run arbitrary code, Codex and Gemini CLI tie trust to a hash or fingerprint of each project hook, so an edited hook has to be approved again. In Claude Code, a rule the model keeps skipping belongs in a hook. The skill can declare that hook in its own hooks frontmatter (Claude Code skills, best practices for Claude Code).
Plugins package skills, commands, subagents, hooks, MCP and LSP servers into one versioned unit, namespaced as /plugin:skill. Claude Code distributes them through marketplaces, Codex through plugins with connectors, and Gemini CLI through extensions installed from GitHub (plugins reference, Codex, Gemini extensions). A CLAUDE.md inside a plugin is not loaded. Instructions a plugin wants in context must be packaged as a skill (plugins reference).
Do skills work? Evidence
SkillsBench (v4, 2026-06), a benchmark, ran 87 tasks across 18 model-harness configurations, each scored by a deterministic verifier (SkillsBench):
- Curated skills raised the average pass rate from 33.9% to 50.5%. Per-configuration gains ranged from +4.1 to +25.7 points.
- Focused skills with at most three modules beat exhaustive documentation bundles.
- Smaller models with skills could match larger models without them.
- Skills the model wrote for itself did not help: v1 reported no average benefit, and v4 reports self-generated skills landing below the no-skill baseline on all three configurations tested.
- Curated skills are not uniformly positive: 13 of 87 tasks had negative deltas, typically when a skill prescribed a single “correct” pipeline with no applicability boundaries or fallback.
- The authors call their setting optimistic: high-quality skills on containerised tasks.
Synthesis: skills pay off when they carry knowledge the model doesn’t have (proprietary procedures, verifier quirks, domain rules). Restating what the model already knows doesn’t help, and asking the model to write its own skills without human review or evals can make things worse.
Authoring guidance
From best practices unless noted:
- The description is the trigger. Write it in the third person, cover both what and when, and include the words users actually say. “Helps with documents” fails, and the model may be choosing among 100+ skills.
- Be concise; assume competence. Include only what the model lacks. Keep
SKILL.mdunder 500 lines and split by domain (reference/finance.md,reference/sales.md) so irrelevant files are never read. - Keep references one level deep. The model may only preview nested files (e.g.
head -100). Add a table of contents to any reference file over 100 lines. - Set degrees of freedom by fragility. Use prose heuristics for judgement calls and an exact script with “do not modify” for migrations.
- Prefer scripts for deterministic steps. Scripts should handle errors themselves and avoid magic constants. Say explicitly whether the model should run or read each one. A validator loop (run, fix, repeat) or a plan-validate-execute step with an intermediate file catches errors before destructive changes.
- Put the most important rules at the top. In Claude Code, an invoked skill stays in the conversation and is never re-read. After compaction, only its first 5,000 tokens are re-attached (Claude Code skills).
- Develop eval-first. Find the gaps without a skill, write at least three evals, measure a baseline, then write minimal instructions. Test with every model tier you’ll deploy on. Claude Code’s skill-creator automates with/without-skill benchmarks and description tuning with should-trigger and should-not-trigger prompts (Claude Code skills). See verification and evals.
- Encode verification in skills. The owner’s loop tutorial treats a skill as the place where the agent’s self-check criteria live, so unattended loops can tell when they’re done (notebook).
Failure modes
- Silent non-triggering. Malformed YAML (or
---not on line 1) loads the body with empty metadata, so/namestill works but automatic matching never fires. Validate withskills-ref validateorclaude plugin validate(spec, Claude Code skills). - Over-triggering or overlap. Vague or overlapping descriptions make the model load the wrong skill. Fix by narrowing the descriptions or making the skill manual-only (extend overview).
- Mistaking
allowed-toolsfor a sandbox. In Claude Code it pre-approves tools for the invoking turn and restricts nothing (Claude Code skills). - Supply-chain and prompt injection risk. A skill is instructions plus code running with the agent’s permissions. A malicious one can exfiltrate data, and a skill that fetches external URLs can pull in hostile instructions even if its author is trustworthy. Audit skills like any software you install (overview, Anthropic). Gemini CLI’s per-activation consent prompt and Codex’s hook trust are partial mitigations. See LLM security risks.
- Compliance. As of 2026-11, Agent Skills on Anthropic’s API are not eligible for zero data retention (ZDR) or HIPAA (see PII and data privacy) (overview). Custom API skills are workspace-wide, so multitenant apps need one workspace per tenant (API guide).
When to use / when not
Use a skill when:
- a multi-step procedure, house style or domain reference is needed sometimes, not on every turn;
- you’d otherwise paste the same playbook into chat for the third time;
- deterministic helper scripts should ship alongside the instructions.
Don’t use a skill when:
- the rule must hold every time: use a hook or permission rule;
- every session needs the fact: use an instruction file;
- the agent needs a new capability or live data: use a tool or MCP server;
- the work would flood the main context: use a subagent.
Sources
- Equipping agents for the real world with Agent Skills (Anthropic)
- Agent Skills specification
- Agent Skills overview (Claude Platform)
- Using Agent Skills with the API
- Skill authoring best practices
- Claude Code skills docs
- Extend Claude Code
- Claude Code hooks reference
- Claude Code plugin manifest reference
- Best practices for Claude Code
- Codex: Build skills
- Codex: Hooks
- Gemini CLI: Agent Skills
- Gemini CLI: Custom commands
- Gemini CLI: Hooks
- Gemini CLI: Extensions
- Cursor: Agent Skills
- SkillsBench (Li et al., 2026)
- Loop Engineering (Loic’s Notebook)