Claude skills are folders Claude reads when a task calls for them: a SKILL.md file holding a name, a description and instructions, plus whatever scripts or reference files the task needs. Until a request matches, Claude keeps only the name and description in context, about 100 tokens per skill. Anthropic ships the format as Agent Skills and published it as an open standard, so a skill written for Claude also works in Cursor, Codex and other agents that read the format.
What are Claude skills?
A Claude skill turns a procedure you’d otherwise paste into every chat into a reusable instruction set that Claude picks up by itself. You write the steps, conventions or reference material once in a SKILL.md file, say in one sentence when they apply, and Claude loads them when your request matches that sentence. Skills can carry scripts as well as text, which is what separates them from a saved prompt.
Anthropic’s Help Center sorts skills by where they come from. Anthropic skills are built and maintained by Anthropic, such as the document skills for Word, Excel, PowerPoint and PDF files, and Claude uses them with no setup. Custom skills are the ones you or your organization write. The Owner of a Team or Enterprise organization can push a skill to every member, switched on or off by default, which makes it an organization-provisioned skill. Partner skills come from companies such as Notion, Figma and Atlassian through the Skills Directory, written to work with each company’s MCP connector.
The product name is Agent Skills, which is why Anthropic’s docs and the open standard say “agent skills” while most people search for “Claude skills”, “what is Claude skills” or “skills in Claude”. Anthropic launched Agent Skills on October 16, 2025 and published the format at agentskills.io that December. On October 22, 2026 it donated the standard to the Linux Foundation’s Agentic AI Foundation, which also hosts MCP. In that announcement Anthropic counts more than 70 agent platforms using the standard, ChatGPT, Cursor, GitHub Copilot and VS Code among them, along with 1 million published skills and nearly 280 million installs. Those figures are Anthropic’s own, and we haven’t seen an independent count.
What is a SKILL.md file?
Every skill has exactly one required file. SKILL.md is a Markdown file that opens with YAML frontmatter telling the agent what the skill is called and when to use it, followed by the instructions Claude follows once the skill fires.
Two frontmatter fields are required. name is up to 64 characters of lowercase letters, numbers and hyphens. The specification adds that it must match the name of the skill’s folder, and Claude’s platform rejects names containing the reserved words anthropic or claude. description is up to 1,024 characters and has to say what the skill does and when to use it, because that text is what Claude compares your request against. The standard keeps all other metadata in the same frontmatter, through four optional fields (license, compatibility, metadata and an experimental allowed-tools), so there’s no separate manifest file to keep in sync.
Here is what a small team skill could look like. It’s an illustration written for this page, not a skill from any published library:
---
name: incident-postmortem
description: Drafts a blameless postmortem from an incident channel export, a timeline and the alerts that fired. Use when someone asks for a postmortem, incident review or retro after an outage. Don't use for security incidents that legal has to review, or for planning on-call rotations.
---
# Incident postmortem
1. From the timeline, pull the times of the first alert, the first human response, mitigation and resolution.
2. Write a three-sentence summary: what broke, who noticed, what fixed it.
3. Fill in assets/template.md. Name systems and decisions as contributing factors, never people.
4. Close with action items that each have an owner and a due date. Ask for any you can't infer.
The description does two jobs at once. Its first half tells Claude what the skill produces, and the “use when” and “don’t use” sentences keep it from firing on every message that mentions an outage.
Next to SKILL.md, the standard names three optional folders: scripts/ for code the agent can run, references/ for longer documents it reads on demand, and assets/ for templates and other files, which is where the template above would live. These folders are the last stage of progressive disclosure, opened only when the instructions point to them. Claude Code’s skills docs also split skill bodies into two kinds. Reference content is knowledge Claude applies to whatever you’re working on, like an API style guide. Task content is a step-by-step action like a deploy or a commit, usually something you’d rather start yourself. The postmortem skill is task content.
How do Claude skills work?
Claude skills work through what Anthropic calls progressive disclosure: Claude loads each skill in stages, and only as far as the task needs. At startup, every installed skill contributes its name and description to the system prompt and nothing else. A matching request pulls in the SKILL.md body. Files and scripts come last, if the instructions ask for them.
| Stage | When it loads | Context cost |
|---|---|---|
| Name and description | At startup, for every installed skill | About 100 tokens per skill |
SKILL.md body | When a request matches the description | Under 5k tokens |
| Reference files and scripts | When the instructions call for them | Nothing until read; a script’s output enters context, its code never does |
The figures come from Anthropic’s Agent Skills overview, and its engineering post on the design describes the same three levels. Two things follow from them. The description does all the routing, so a vague one (“helps with incidents”) means the skill fires at the wrong moment or never. And because Claude runs a bundled script through bash and receives only what it prints, code from a skill can execute without its source ever passing through the conversation you’re watching.
Installing many skills has a cost too. Anthropic’s guide to skills for enterprise warns that every name and description competes for attention in the system prompt, so with too many active, Claude can pick the wrong skill or miss the right one. API requests are capped at 20 skills each. In Claude Code, setting disable-model-invocation: true takes a skill’s description out of Claude’s context entirely, and you run that skill yourself.
Where Claude skills run and where they’re stored
Where a skill runs decides what its scripts can reach, and Anthropic’s platform docs give each Claude surface a different runtime:
| Surface | How a skill gets there | Who can use it | Network access for the skill |
|---|---|---|---|
| claude.ai | Anthropic skills are built in; custom skills are uploaded as a zip in settings (Pro, Max, Ultra, Team and Enterprise, with code execution on) | The account, or every member for skills an Owner provisions | Full, partial or none, depending on user and admin settings |
| Claude Code | A folder with a SKILL.md on disk | Whoever runs Claude Code on that machine or in that repository | Full: “the same network access as any other program on the user’s computer” |
| Claude API | Uploaded through the /v1/skills endpoints and named in each request, with the code execution tool | Every member of the workspace | None, and no package installs at runtime |
So where are Claude skills stored in Claude Code? In folders on disk, and the folder’s location sets the scope. Claude Code’s skills docs list these places:
.claude/skills/<name>/SKILL.mdinside the managed settings directory, for every user on machines where the organization deploys it~/.claude/skills/<name>/SKILL.md, for all your projects on that machine.claude/skills/<name>/SKILL.mdin a repository, read from the directory you start in and each parent up to the repository root- a
.claude/skills/folder deeper in the tree, loaded the first time Claude reads or edits a file there - the
.claude/skills/folder of any directory you add with--add-dir <plugin>/skills/<name>/SKILL.mdin an installed plugin, run as/plugin-name:skill-name- skills you’ve turned on for your claude.ai account, in Cowork, cloud sessions and terminal sessions signed in with that account
When two of the first three hold a skill with the same name, the enterprise copy beats the personal one and the personal copy beats the project’s. Plugin skills never collide, because of their prefix.
Uploads don’t travel between surfaces: a skill uploaded to claude.ai isn’t available through the API, and the reverse is also true. Claude Code is where the line blurs. Signed in with a claude.ai account, it downloads the skills enabled on that account into ~/.claude/skills/synced/ and checks for changes while the session runs. The overview page still describes Claude Code skills as separate from claude.ai; the Claude Code page describes the sync, and it’s the one to follow.
Claude Code skills: how they’re invoked and restricted
Claude Code skills follow the open standard and add features of their own on top: control over who starts a skill, running a skill in a subagent, and shell commands that run before the skill reaches Claude. By default either side can start one. Claude does when your request matches the description, and you can type /skill-name.
A few frontmatter fields change that. disable-model-invocation: true stops Claude from starting the skill on its own, which the docs recommend for anything with side effects: “You don’t want Claude deciding to deploy because your code looks ready.” user-invocable: false hides a skill from the / menu for background knowledge, though Claude can still use it. context: fork hands the skill to a new subagent that doesn’t see your conversation history, so the instructions have to stand on their own. And allowed-tools pre-approves tools for the turn that invokes the skill, which the security section comes back to.
Claude Code also ships bundled skills, among them /doctor, /code-review, /batch, /debug, /loop and /claude-api. They’re prompt-based: instructions that Claude carries out with its usual tools, where most built-in commands run fixed logic. The disableBundledSkills setting turns them off. Writing your own is covered step by step in Anthropic’s skills docs.
Claude skills examples
Anthropic’s own skills show one end of the range. The pre-built pptx, xlsx, docx and pdf skills create and edit PowerPoint, Excel, Word and PDF files on claude.ai, the Claude API, Claude Platform on AWS and Microsoft Foundry. They aren’t available in Claude Code, which comes with the open-source Claude API skill and the bundled skills above instead. More open-source examples live in Anthropic’s skills repository.
Partner skills sit at the other end. A company that already runs an MCP connector, such as Notion, Figma or Atlassian, publishes a skill telling Claude how to use that connector well. The connector gives Claude access, and the skill carries the know-how.
Inside a team, skills tend to fit a handful of shapes:
- a deploy or release workflow with model invocation switched off, so it only runs when someone types the command
- an incident postmortem or on-call runbook, like the example above, that turns raw notes into a document in the team’s format
- a schema or config check that runs a bundled script, because a script gives consistent answers and a model may not
- an API style guide or naming convention, loaded as reference content whenever Claude works on that part of the code
Claude Code’s docs suggest writing one when you keep pasting the same instructions into chat, or when a section of CLAUDE.md has grown from a fact into a procedure.
Skills vs CLAUDE.md, subagents, slash commands, hooks and MCP
A Claude skill isn’t an agent or a subagent. A skill adds instructions to the conversation Claude is already having, while a subagent is a separate worker with its own context window that does a task and returns a summary. The two meet in context: fork, which gives a skill’s instructions to a fresh subagent as its prompt.
Claude Code’s features overview lays out how each extension loads and what it costs in context:
| Feature | What it is | When it loads | Context cost |
|---|---|---|---|
CLAUDE.md | Persistent instructions for the project | Every session, automatically | Every request |
| Skill | Instructions, knowledge and workflows | Descriptions at session start, the body when used | Low: descriptions on every request |
| Subagent | An isolated worker that returns a summary | When spawned | Isolated from the main session |
| Custom slash command | A file in .claude/commands/ | Now merged into skills | Same as a skill |
| Hook | A shell command, HTTP request, MCP tool call, prompt or subagent fired by an event | On its lifecycle event | Zero unless the hook returns output |
| MCP server | Tools and data from an external service | Tool names at session start, schemas on demand | Low until a tool is used |
CLAUDE.md holds what Claude should always know, and Anthropic suggests keeping it under 200 lines, with reference material moved into skills. Hooks are the deterministic option. They fire on their event whether or not Claude decides anything, which makes them the place for checks that must run, with gaps we tested in what Claude Code hooks can’t stop.
MCP and skills solve different problems. An MCP server gives Claude tools and data from a system it can’t otherwise reach, with the server handling the connection and authentication; a skill gives it the procedure, which can include how to use those tools. Our MCP vs skills guide compares them in depth, including how each looks as network traffic, and the MCP gateway page covers per-tool control of MCP servers.
Are Claude skills safe?
Claude skills are as safe as the instructions and scripts inside them, because both act with whatever access Claude already has. Anthropic’s security guidance says to use skills “only from trusted sources: those you created yourself or obtained from Anthropic,” and warns that a malicious skill “can direct Claude to call tools or run code in ways that don’t match the Skill’s stated purpose.”
What a skill can do on your machine
In Claude Code, a skill’s scripts run as you. Anthropic’s enterprise guide rates scripts in a skill as high risk because “scripts run with full environment access,” and Claude Code gives skills full network access. Its review checklist singles out exactly that combination, a skill that can read files and reach the network, because it can send what it read somewhere else. Upload the same folder to the Claude API and it runs in a container with no network at all.
Two Claude Code features let a skill act before Claude has weighed anything. A line written as !`command` runs a shell command while the skill renders and pastes its output into the prompt. Those commands “never prompt for permission while the skill renders”; Claude Code checks each one against your permission rules and aborts the skill on a deny, and outside auto mode on anything short of an allow. The allowed-tools field pre-approves tools for the turn that invokes the skill, and the skills docs carry this warning: “Claude Code applies a project skill’s allowed-tools even in a -p run in a folder you’ve never trusted.” A cloned repository can ship a skill that grants itself broad tool access. It’s the trap we described in allowlisting some Bash commands, where one approved path often reaches everything. Skills synced from a claude.ai account are handled more strictly in the terminal: Claude Code doesn’t run their ! commands. For the rest of a coding agent’s access, see AI coding agent security.
Where third-party skills come from
Skills arrive the way code does: in a repository someone clones with a .claude/skills/ folder inside, in a plugin from a marketplace, from a registry, as a zip uploaded to claude.ai, or through the claude.ai account sync. Of those routes, the only one Anthropic scans is an upload to claude.ai or Cowork, and only on Enterprise with scanning turned on.
Researchers have started counting what’s in the registries. Liu et al., in a study accepted to USENIX Security 2026, looked at 98,380 skills in two registries. They confirmed 157 malicious ones and found 632 vulnerabilities, grouped into 13 attack techniques, and the two most common strategies were credential theft through remote code execution and adversarial instructions hidden in a skill’s documentation. Snyk’s ToxicSkills research, dated February 5, 2026, pulled 3,984 skills from ClawHub and skills.sh, flagged a critical issue in 534 of them and confirmed 76 malicious payloads. It comes from a company that sells a skill scanner, which is worth knowing when you weigh it.
Instructions are an attack surface as well. Anthropic flags skills that fetch content from external URLs as a particular risk, since the fetched text can carry instructions, and adds that “even trustworthy Skills can be compromised if their external dependencies change over time.” That’s prompt injection by way of a skill: one you reviewed can start following new instructions without a single file in its folder changing. Our guide to agentic AI security covers this supply chain for agent tooling more broadly.
What Anthropic’s scanning covers
Claude Enterprise organizations can turn on “Skill and plugin security scanning” for custom skills that members upload or edit in claude.ai and Claude Cowork. A skill that fails the scan, or whose scan hasn’t finished, is blocked; one that passes with a warning stays usable behind a notice, and Owners can allow some failed skills. The enterprise guide also lists what scanning leaves out: skills uploaded through the Skills API or the Claude Console, skills already in the organization when scanning was switched on, and organizations with configurations such as customer-managed encryption keys, zero data retention or HIPAA readiness. A skill that lives in a local Claude Code folder is never uploaded, so it never meets a scanner.
How teams govern Claude skills
Anthropic’s enterprise guide treats a skill like a software dependency. It rates a skill’s risk indicators in tiers, with scripts, instructions telling Claude to hide what it does, references to MCP tools, network calls and hardcoded credentials all rated high. Its eight-step review asks reviewers to read every file, run the scripts in a sandbox, and look for adversarial instructions, network calls, credentials, redirects and exfiltration patterns. It also asks them to weigh tools in combination: “Consider the combined risk when a Skill uses both file-read and network tools together.” For the sandbox step, our guide to sandboxing Claude Code shows what the built-in sandbox restricts and what it leaves open.
After approval, the same guide recommends keeping skills in Git behind code review, pinning API skills to a version (an unpinned request runs whatever version anyone in the workspace uploaded last), checking reviewed skills against checksums at deployment, and keeping a registry of each skill’s owner, version and dependencies. On claude.ai, Team and Enterprise Owners can then provision the approved set to everyone.
Claude Code adds settings an admin can push through managed settings:
- deny the
Skilltool to switch skills off, or deny individual skills withSkill(name)rules (allow rules don’t limit Claude to the skills they name) allowManagedPermissionRulesOnly, which makes Claude Code ignoreallowed-toolsin project and personal skills, from Claude Code v2.1.282disableSkillShellExecution, which replaces the!commands in user, project, plugin and added-directory skills with a placeholderdisableBundledSkills, andskillOverridesto list a skill by name only, keep it away from Claude while leaving it in the/menu, or turn it off- skills placed in the managed settings directory, which every user on the machine receives
If we were rolling skills out to a team of Claude Code users, allowManagedPermissionRulesOnly would go in first. It closes the case the docs warn about, a cloned repository whose skill pre-approves its own tools, without anyone maintaining a list of skill names. A deny list only covers the names someone thought to add.
Seeing which skills actually run is a separate problem. Claude Code can report skill use through OpenTelemetry once telemetry is turned on: a claude_code.skill_activated event records each invocation, how it was triggered and where the skill was loaded from. By default the event replaces the names of user-defined and third-party plugin skills with custom_skill, and real names appear only with OTEL_LOG_TOOL_DETAILS=1. A repository’s own settings can’t switch telemetry on, so it has to come from managed settings or each user’s environment. A skill copied by hand into ~/.claude/skills/ skips every review step above, which is how skills become shadow AI.
How Formal governs skills in Claude Code traffic
We build a proxy, so we look at skills from the network. Formal Endpoint in Transparent Mode, with a network rule that intercepts llm traffic from known agents, reads the requests Claude Code sends to its model provider. Each one names the skills on offer. It also names the ones loaded into the conversation, which is the data behind our AI governance pages for skills and doesn’t depend on how Claude Code’s own telemetry is set up.
The Shadow AI review lists skills that appear in Claude Code’s requests but aren’t in your Catalog, refreshed every 24 hours, and marks each one Loaded (into a conversation) or On device. A reviewer adds the skill to the Catalog for everyone, adds it with access limited to specific users, or blocks it; the last two outcomes create an access policy. Skills you write or approve go into the Catalog on the platform directly: Add Skill builds a Catalog entry from a SKILL.md, and the entry’s Access Controls choose between Everyone, Specific Users and No One.
Skills outside the Catalog fall to the AI Guardrails recipe, where Unknown Skills is set to Allow and Monitor or to Block. Block stops the LLM request that loads the skill. Our MCP vs skills post shows the policy the recipe generates and how it matches input.llm.loaded_skills against the names of approved skills. The Skills usage page shows which skills are loaded into agent context, who loads them and the policy activity on each load. Our shadow AI detection page walks through the review queue, and the Claude Code integration page covers what else Formal enforces on Claude Code, from spend limits to sign-ins.
Several limits decide whether this fits your fleet. We read skills out of Claude Code’s requests only, so a skill that Cursor or Codex loads never reaches the Skills tab, and Transparent Mode runs on macOS and Linux, with no Windows support yet. The Skills tab refreshes once a day. Formal identifies a skill by the name of the folder holding its SKILL.md and never opens the instructions or scripts. The open standard requires a skill’s name to match that folder, but two different skills in folders with the same name still look identical to a policy, and a script that reads a local file stays invisible until it sends something over the network. A blocked skill gets Formal’s standard block message, where an unknown MCP server gets a list of approved alternatives.
Our view: a skill review tells you what a folder contained on the day someone read it. What the agent sends afterwards is the other half of the picture, and that half can be checked in the traffic.