What are agent skills?

An agent skill is a folder with a SKILL.md file that tells an agent how to do one kind of task. The agent sees only the skill’s name and description until a task matches, then reads the full instructions. The Agent Skills spec calls it “a lightweight, open format for extending AI agent capabilities with specialized knowledge and workflows.”

Anthropic originally developed the format and released it as an open standard, and the spec says a growing number of agent products have adopted it. A skill written once can be used by any compatible agent.

What is inside a skill

The specification requires only a directory with a SKILL.md file. Everything else is optional.

skill-name/
  SKILL.md       required: metadata + instructions
  scripts/       optional: executable code
  references/    optional: documentation
  assets/        optional: templates, resources

The frontmatter of SKILL.md has two required fields and three optional ones.

Field	Required	Constraint in the spec
name	Yes	Up to 64 characters; lowercase letters, numbers and hyphens; no leading, trailing or doubled hyphens; must match the directory name
description	Yes	1 to 1024 characters; should say what the skill does and when to use it
license	No	A license name or a bundled license file
compatibility	No	Up to 500 characters on environment needs
metadata	No	A string-to-string map for extra properties
allowed-tools	No	Space-separated pre-approved tools; the spec marks it experimental and says support varies

Below the frontmatter, the body is plain Markdown. The spec suggests step-by-step instructions, examples and edge cases, and says to keep SKILL.md under 500 lines and move detail into separate files, referenced one level deep.

How an agent uses a skill

Agents load skills in stages, which the spec calls progressive disclosure. Anthropic’s engineering team called it “the core design principle that makes Agent Skills flexible and scalable.”

Stage	What loads	Size
Discovery	name and description of every installed skill, at startup	About 100 tokens per skill
Activation	The full SKILL.md body, when a task matches the description	Under 5,000 tokens recommended
Execution	Bundled files, only when the instructions point to them	Nothing until read

The sizes come from the spec and Anthropic’s docs. One detail from those docs matters for cost: when a skill runs a bundled script, the script’s code never enters the context window. Only its output does.

Because the description is all the agent has when deciding, it carries the whole trigger. The spec’s weak example is “Helps with PDFs.” Its good one names the actions and says when to use the skill: “Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.”

Skills vs prompts, MCP and other context

	Skill	System prompt or prompt	MCP server
What it is	A folder of instructions, scripts and files	Text in the conversation	A running program exposing tools
When it loads	On demand, when the description matches	Every request	Tool definitions are listed at connection time
Best for	Repeatable procedures and domain knowledge	Standing rules and one-off tasks	Reaching live systems and data

Anthropic’s docs contrast skills with prompts, which are “conversation-level instructions for one-off tasks”, while skills “load on demand, so you don’t have to repeat the same guidance across conversations.” That makes a skill one way to do context engineering: the procedure stays on disk until the task needs it, instead of sitting in a system prompt on every call.

A skill does not replace a tool server. A skill can say how to use a tool, but a Model Context Protocol server is what lets the agent reach a live system. See MCP vs API for how tool access differs.

Where skills run

Support differs by product. This is from Anthropic’s docs as of 8 November 2026.

Surface	Where skills live	Notes
Claude Code	~/.claude/skills/ (personal) or .claude/skills/ (project), also plugins	Full network access; invoked automatically or with /skill-name
Claude API	Uploaded through the Skills API, listed in the container parameter	Needs the code execution tool; sandbox has no network access and no runtime package installs
claude.ai	Uploaded as a zip in settings	Custom skills need a paid plan with code execution enabled

Custom skills do not sync across these surfaces: a skill uploaded to claude.ai has to be uploaded again to the API. Anthropic also ships pre-built skills for PowerPoint, Excel, Word and PDF on the API and claude.ai, but not in Claude Code.

Claude Code extends the standard with fields such as disable-model-invocation and user-invocable. Outside Claude Code only the six standard fields are allowed, so a skill that uses the extras can fail packaging for claude.ai or the API. Claude also reserves the words anthropic and claude in skill names. Check the target product before relying on either.

Security

A skill is instructions plus code, so it deserves the care you give installed software. Anthropic recommends installing skills only from trusted sources and auditing less trusted ones, including their dependencies and any external network connections. Its docs add that skills fetching external URLs carry particular risk, since the fetched content might contain malicious instructions, and that even a trustworthy skill can be compromised if its dependencies change.

This is the same class of problem as prompt injection: text the agent reads can steer what it does. Review the whole folder, not just SKILL.md. Limit what tools the agent has while it runs an unfamiliar skill.

Writing a good skill

The spec and Anthropic’s docs agree on a few habits:

• Put the trigger in the description: what the skill does and when to use it, with keywords a user would say.
• Keep SKILL.md short and move detail into references/.
• Put steps that must run the same way every time into scripts/, so they are code rather than text the model re-reads.
• Validate the result with the spec’s skills-ref validate ./my-skill command.

Skills for HoneyHive

HoneyHive publishes three official skills at github.com/honeyhiveai/skills for coding agents: honeyhive-instrument adds tracing to LLM, agent and RAG applications, honeyhive-evaluate sets up evaluations and experiments, and honeyhive-improve uses traces and evaluation results to improve application behavior. Each installs with a command such as npx skills add honeyhiveai/skills --skill honeyhive-instrument, and the skills need the HoneyHive CLI and an HH_PROJECT_API_KEY environment variable. The coding agents guide has the full setup. For what the traces then show, see agent tracing.

FAQ

What is a SKILL.md file?

It is the one required file in a skill. It starts with YAML frontmatter (a name and a description) followed by Markdown instructions, and the spec puts no format restrictions on the body.

Are agent skills the same as MCP?

No. A skill is a folder of instructions an agent reads. An MCP server is a running program that exposes tools over a protocol. A skill can tell an agent how to use a tool, and Anthropic's engineering team wrote that it planned to explore how skills complement MCP servers.

Do skills work outside Claude?

Yes. The format began at Anthropic and was released as an open standard that a growing number of agent products have adopted. Some frontmatter fields are specific to Claude Code and make packaging or upload fail elsewhere.

Are skills safe to install?

Treat them like software. Anthropic advises using skills only from trusted sources and auditing every bundled file, because a malicious skill can direct an agent to call tools or run code in ways its description does not suggest.