Anthropic Agent Skills

Anthropic has introduced Agent Skills, a framework that allows users to equip general-purpose agents with domain-specific expertise through organized folders of instructions, scripts, and resources. This system enables agents to transform from generalists into specialized agents by dynamically discovering and loading the capabilities they need for specific tasks.

The Architecture of Agent Skills

Agent Skills utilize a directory-based structure to provide agents with additional capabilities. A skill consists of a directory containing a SKILL.md file, which serves as the primary entry point for the agent.

Progressive Disclosure of Context

To manage the context window efficiently, Agent Skills employ a design principle called "progressive disclosure." This ensures the agent only loads the information necessary for the current task across three levels of detail:

  1. Metadata Level: Every SKILL.md file begins with YAML frontmatter containing a name and description. These are pre-loaded into the agent's system prompt at startup, allowing the agent to identify when a skill is relevant without loading the entire content.
  2. Core Instruction Level: If the agent determines a skill is relevant, it reads the full SKILL.md file into its context window.
  3. Deep Detail Level: For complex skills, authors can bundle additional files (e.g., reference.md or forms.md) within the skill directory. The agent can navigate and discover these files only as needed, making the amount of bundled context effectively unbounded.

Integration with Code Execution

Agent Skills can include pre-written scripts that the agent can execute as tools. This approach provides deterministic reliability and efficiency for tasks that are better suited for traditional code than token generation, such as sorting lists or extracting form fields from a PDF.

Implementation and Best Practices

Developing effective skills requires an iterative approach focused on evaluation and scalability.

Development Guidelines

  • Evaluation-First Approach: Identify capability gaps by running agents on representative tasks and building skills incrementally to address those shortcomings.
  • Scaling Structure: Split unwieldy SKILL.md files into separate referenced files to reduce token usage and separate mutually exclusive contexts.
  • Agent-Centric Design: Monitor the agent's trajectories and refine the name and description metadata, as these are the primary triggers for skill activation.
  • Collaborative Iteration: Use the agent to help capture successful approaches and common mistakes into reusable context and code within the skill.

Security Considerations

Because skills can include executable code and instructions to connect to external sources, Anthropic recommends installing skills only from trusted sources. Users should audit bundled files, code dependencies, and network requests before installation.

Availability and Future Roadmap

Agent Skills are currently supported across Claude.ai, Claude Code, the Claude Agent SDK, and the Claude Developer Platform. Additionally, Agent Skills have been published as an open standard for cross-platform portability as of December 18, 2025.

Future Directions

Anthropic plans to expand the lifecycle of creating, editing, and sharing skills. Future developments include:

  • MCP Integration: Exploring how skills can complement Model Context Protocol (MCP) servers to teach agents complex workflows involving external software.
  • Autonomous Evolution: Enabling agents to create, edit, and evaluate their own skills to codify their own behavioral patterns into reusable capabilities.

Sources

Related

  • Dispatch
    Anthropic Agent Skills Release

    Anthropic has introduced Agent Skills, a portable and composable framework of instructions and scripts that allow Claude to perform specialized tasks across Claude apps, Claude Code, and the API.

  • Project
    agentskills/agentskills

    A standardized, open format for packaging specialized knowledge and workflows into portable folders that AI agents can load on demand to gain domain expertise.

  • Dispatch
    Anthropic Building Effective AI Agents – Practical Patterns and Guidance

    Anthropic outlines practical patterns for building LLM‑augmented agents and workflows, emphasizing simple composable designs, when to use each pattern, and best practices for tool engineering.

  • Dispatch
    Anthropic Trustworthy Agents Framework and Implementation

    Anthropic outlines a multi-layered approach to building trustworthy AI agents by combining model training, system harnesses, tool permissions, and open standards to mitigate risks like prompt injection and unintended autonomy.

  • Project
    kangarooking/kangarooking-skills

    A collection of structured, open-source Agent Skills and workflows for AI agents to automate tasks ranging from content creation and 3D generation to complex software engineering.