What an agent skill is

An AI agent has two halves. The brain is the AI model, like Claude Opus, which reads your request and decides each step on the provider’s servers. The hands are the agent program on your computer, such as the Claude Code agent, which reads files and runs commands when the model asks. A tool is one action the agent can take, such as reading a file or running a command.

A skill is a folder that teaches the agent one kind of job: written steps for the model to follow, and sometimes small programs for the agent to run. Anthropic created the format and published it as an open standard, so other agent products can use the same folders.

What’s in a skill

A skill is a folder with one main file, SKILL.md. The .md ending means it’s a Markdown file: plain text with a few marks for headings and lists.

SKILL.md has two parts:

• A header at the top, between two --- lines. Two labelled lines matter most: name, a short label, and description, which says what the skill does and when to use it.
• The instructions below the header: the steps the model should follow, in plain language.

The folder can hold more files: notes, examples, templates, and often a scripts folder. A script is a small program saved in a file. The instructions can tell the agent to run it, and the agent does that by typing a command, the way you would in a terminal (see What a terminal is).

Here is a small skill of our own:

---
name: weekly-report
description: Turns this week's notes into a short status report. Use when the user asks for a weekly report or a status update.
---

1. Read the files in the notes folder.
2. Write a short list under three headings: done, in progress, blocked.
3. Run scripts/count_tasks.py and add its total at the end.

So a skill carries two kinds of thing: words the model follows, and code the agent can run on your computer.

How the agent decides to use one

Anthropic’s docs describe three stages, which they call progressive disclosure:

1. At the start, only each skill’s name and description go into the model’s context: the text it has in front of it while it works.
2. When your request matches a description, the agent loads the rest of SKILL.md, and the model follows it.
3. Other files are read only when the instructions point to them. When a script runs, only its output goes back to the model, not its code.

So the description is the trigger: the docs say it’s what the model compares your request with.

In the Claude Code agent, by default, both you and the model can start a skill. You start one with a slash command: a / and the skill’s name, such as /weekly-report. The model starts one on its own when your conversation fits the description. An author who wants only people to start a skill adds the header line disable-model-invocation: true.

Where skills come from

The Claude Code agent loads skills from folders on your computer, including:

• Personal skills in ~/.claude/skills/ in your home folder, for all your projects.
• Project skills in .claude/skills/ inside a project’s folder, for that project only.

The docs suggest saving project skills into the project’s files that the team shares, so everyone gets them. The flip side: when you download someone else’s project, its skills come with it.

Why a skill is a security question

Installing a skill lets someone else write instructions the model will follow and code the agent will run, with the agent’s access to your computer. Anthropic’s docs warn that a harmful skill can steer the model to use tools or run code in ways that don’t match what the skill says it does. They name data leaving your computer and access to systems nobody approved among the results.

The risk comes from four places:

• The description. Its author picks the words that make the model load the skill.
• The instructions. The model treats them as orders. If they tell the agent to fetch text from the internet, that text can carry harmful instructions too, and the docs add that a trusted skill can turn bad if something it downloads changes later.
• The scripts. They run on your computer. For the Claude Code agent, the docs say a skill has the same network access as any other program there.
• Two features that skip the question, described next.

Normally the agent asks before it runs a command, unless a permission rule already allows it. A permission rule is a line in a settings file that allows, asks about or denies an action.

The first feature is an injected command: an exclamation mark in front of a command written between backticks (the ` key, usually top-left on the keyboard), such as !`date`. The agent runs it while the skill loads, before the model sees the skill, and never shows you a question. It checks your permission rules instead. Auto mode is a setting where a second AI model reviews the agent’s actions instead of you. In every other mode, a command your rules don’t allow stops the skill from loading. In auto mode, the skill loads with a note telling the model to run the command first, and that second model reviews it like any other command.

The second is the allowed-tools header line. It lists tools the model may use without asking you, from the moment the skill starts until you send your next message, and it can pre-approve the injected commands. The docs warn that a skill can grant itself wide access this way, even in a folder you’ve never marked as trusted.

A deny rule beats both: the docs say deny and ask rules still win over allowed-tools.

Before you install a skill

1. Know who wrote it. Anthropic’s docs advise using only skills you wrote yourself or got from Anthropic. Audit anything else first, and treat it like installing software.
2. Read every file, not only SKILL.md. The docs name scripts, images and other files. Look for anything that doesn’t fit the skill’s job, such as a network call or file access you wouldn’t expect.
3. Check the header and the injected commands. Read the allowed-tools line, and search for an exclamation mark in front of a command. Be most careful with a bare Bash there, with no limit in brackets after it: the permissions docs say Bash on its own matches every shell command, so the skill can run any command without asking.
4. Look inside downloaded projects. Before you start the agent in someone else’s project, open its .claude/skills/ folder. Its name starts with a dot, so your file browser may hide it.
5. Block what you don’t use. The deny rule Skill(name) stops one skill. This example, in a project’s .claude/settings.json, blocks the skill above:

{
  "permissions": {
    "deny": ["Skill(weekly-report)"]
  }
}

Skill with no name stops the model from using any skill:

{
  "permissions": {
    "deny": ["Skill"]
  }
}

Put the same rule in your personal settings file, ~/.claude/settings.json in your home folder, and it applies in every project on your computer. The permissions docs add that a deny rule wins even when another settings file allows the same thing.

Note

Setting disableSkillShellExecution to true in your personal settings file goes further: the Claude Code agent then shows a notice in place of each injected command in the skills you add, instead of running it. Skills that ship with the Claude Code agent are not affected.

Skills, MCP and the sandbox

An MCP server is a separate program that hands the agent new tools (What an MCP server is). A skill is know-how in a folder: how to do a job. In October 2025, Anthropic wrote that it would explore skills that work alongside MCP servers, teaching the agent longer workflows that use outside tools. Both extend the agent, so both deserve the same check.

A skill’s injected commands run the same way as the agent’s own commands, and the agent runs a skill’s scripts with commands too. The sandbox guide explains the wall the Claude Code agent can put around its commands, and what that wall leaves outside.

Where to go next

Read .env files and API keys to see the secrets a harmful skill could reach, then the sandbox and MCP guides above. The official pages this guide draws on are listed below.