Anthropic Agent Skills: An Open Standard for Composable Agent Expertise

As AI agents become capable of interacting with complex computing environments, Anthropic has introduced Agent Skills, an open standard designed to provide composable and portable domain-specific expertise to general-purpose agents.

This system allows developers to package procedural knowledge—such as specialized instructions, scripts, and resources—into reusable units, transforming general-purpose agents into highly specialized tools without requiring the creation of fragmented, custom-designed agents for every use case.

Defining Agent Skills

Agent Skills are organized directories that contain a SKILL.md file, which bundles instructions, scripts, and resources that grant agents additional capabilities. The core purpose of Skills is to enable the specialization of agents by capturing and sharing procedural knowledge, effectively acting as an onboarding guide for an agent to a specific domain.

Skills extend the capabilities of models like Claude by allowing expertise to be packaged into composable resources. This approach moves beyond building monolithic, custom agents toward a modular system where agents can dynamically discover and load relevant expertise based on the task at hand.

The Anatomy of a Skill: Progressive Disclosure

The structure of a Skill is built around the principle of progressive disclosure, ensuring that agents only load the context they need for a specific task, which dramatically improves scalability and efficiency.

Skill Structure and Metadata

At the simplest level, a Skill is a directory containing a SKILL.md file. This file must begin with YAML frontmatter that includes required metadata: name and description. When an agent starts, it pre-loads the name and description of every installed skill into its system prompt. This metadata serves as the first level of progressive disclosure, allowing the agent to determine when a skill is relevant without loading its entire content.

Context Layering and File Bundling

As skills become more complex, Anthropic designed a multi-layered system to manage context size. The actual body of the SKILL.md file constitutes the second level of detail, which the agent reads into context only if it determines the skill is relevant to the current task. For even greater complexity, skills can bundle additional files within the skill directory (e.g., forms.md or reference.md) and reference them from the core SKILL.md.

These additional linked files represent the third level (and beyond) of detail. By separating specialized instructions into distinct files, the skill author keeps the core SKILL.md lean, allowing the agent to choose to navigate and discover these deep instructions only when absolutely necessary.

Skills and Context Window Management

Agent Skills enable effectively unbounded context bundling because agents with filesystem and code execution tools do not need to load the entirety of a skill into their context window for every task.

The process of skill activation follows a specific sequence within the context window:

Initialization: The context window begins with the core system prompt, the metadata for all installed skills, and the user's initial message.
Skill Trigger: The agent invokes a tool (e.g., a Bash tool) to read the contents of the skill's SKILL.md file.
Context Selection: The agent chooses to read specific bundled files (e.g., forms.md) based on the task requirements.
Task Execution: The agent proceeds with the user's task, now having loaded only the relevant instructions from the skill.

This mechanism ensures that the agent loads information only as needed, similar to a well-organized manual that uses a table of contents, specific chapters, and detailed appendices.

Integrating Code Execution

Skills can incorporate pre-written code, such as Python scripts, to function as deterministic tools that the agent can execute at its discretion. This is crucial because certain operations are better suited for traditional code execution than for token generation.

For instance, a PDF skill can include a script that reads a PDF and extracts form fields. The agent can run this script without needing to load either the script or the PDF content into its context window. This approach provides the deterministic reliability required for consistent and repeatable workflows.

Developing and Evaluating Skills

Developers should follow several guidelines when authoring and testing skills to ensure they are effective and scalable:

Start with Evaluation: Identify specific gaps in the agent’s capabilities by running it on representative tasks and observing where it struggles before building skills to address those shortcomings.
Structure for Scale: If the SKILL.md file becomes too large, split its content into separate, referenced files. Separating mutually exclusive or rarely used contexts reduces token usage.
Think from the Agent's Perspective: Monitor how the agent uses the skill in real scenarios, paying close attention to the name and description. These elements are critical for the agent deciding whether to trigger the skill.
Iterate with the Agent: Ask the agent to self-reflect on its successful approaches and common mistakes while using a skill. This helps discover the exact context the agent requires, rather than trying to anticipate all needs upfront.

Security Considerations

Because Skills grant agents new capabilities through instructions and code, they introduce potential vulnerabilities. Malicious skills could be used to introduce environmental vulnerabilities, direct the agent to exfiltrate data, or cause unintended actions.

Anthropic strongly recommends installing skills only from trusted sources. When using skills from less-trusted origins, a thorough audit is mandatory. This audit must include reading all bundled files to understand their function, paying close attention to code dependencies, and scrutinizing instructions that might direct the agent to connect to untrusted external network sources.