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.

StageWhen it loadsContext cost
Name and descriptionAt startup, for every installed skillAbout 100 tokens per skill
SKILL.md bodyWhen a request matches the descriptionUnder 5k tokens
Reference files and scriptsWhen the instructions call for themNothing 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:

SurfaceHow a skill gets thereWho can use itNetwork access for the skill
claude.aiAnthropic 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 provisionsFull, partial or none, depending on user and admin settings
Claude CodeA folder with a SKILL.md on diskWhoever runs Claude Code on that machine or in that repositoryFull: “the same network access as any other program on the user’s computer”
Claude APIUploaded through the /v1/skills endpoints and named in each request, with the code execution toolEvery member of the workspaceNone, 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.md inside 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.md in 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.md in 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:

FeatureWhat it isWhen it loadsContext cost
CLAUDE.mdPersistent instructions for the projectEvery session, automaticallyEvery request
SkillInstructions, knowledge and workflowsDescriptions at session start, the body when usedLow: descriptions on every request
SubagentAn isolated worker that returns a summaryWhen spawnedIsolated from the main session
Custom slash commandA file in .claude/commands/Now merged into skillsSame as a skill
HookA shell command, HTTP request, MCP tool call, prompt or subagent fired by an eventOn its lifecycle eventZero unless the hook returns output
MCP serverTools and data from an external serviceTool names at session start, schemas on demandLow 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 Skill tool to switch skills off, or deny individual skills with Skill(name) rules (allow rules don’t limit Claude to the skills they name)
  • allowManagedPermissionRulesOnly, which makes Claude Code ignore allowed-tools in project and personal skills, from Claude Code v2.1.282
  • disableSkillShellExecution, which replaces the ! commands in user, project, plugin and added-directory skills with a placeholder
  • disableBundledSkills, and skillOverrides to 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.