Anthropic's Agent Skills: Composable Expertise for Claude Agents

TL;DR

• Agent Skills are organized folders (SKILL.md + resources) that Claude loads dynamically to gain domain-specific capabilities
• Progressive disclosure keeps context lean: metadata loads at startup, full skill loads on-demand, additional files load only when needed
• Skills can bundle executable code that runs outside the context window for deterministic, efficient operations
• Now an open standard across Claude.ai, Claude Code, and the Agent SDK — designed for sharing procedural knowledge at scale

The Big Picture

General-purpose AI agents hit a wall when they need specialized knowledge. You can cram domain expertise into system prompts, but that doesn't scale. You can build custom agents for every use case, but that fragments your tooling. Anthropic's answer is Agent Skills: a standardized way to package instructions, scripts, and resources that agents discover and load only when needed.

Think of it like onboarding documentation for a new hire, except the hire is Claude and the documentation is executable. A skill is just a directory with a SKILL.md file containing YAML metadata and instructions. Claude reads the metadata at startup, loads the full skill when it's relevant, and can even navigate to additional bundled files if the task requires deeper context.

The design solves a real problem. As long-running agents tackle complex workflows, they need access to specialized knowledge without bloating the context window. Skills give you composability without the token tax. You're not choosing between a general-purpose agent that's mediocre at everything or a dozen fragmented custom agents. You're building one agent that loads expertise on demand.

Anthropic published Agent Skills as an open standard in December 2024. It's live in Claude.ai, Claude Code, the Claude Agent SDK, and the Developer Platform. The format is intentionally simple: YAML frontmatter, markdown instructions, optional code bundles. No proprietary tooling required.

How It Works

Agent Skills use progressive disclosure to manage context efficiently. At startup, Claude loads only the name and description of every installed skill into its system prompt. This is the first level of detail. When Claude encounters a task that matches a skill's description, it reads the full SKILL.md file into context. That's the second level.

If the skill references additional files — like a forms.md guide for PDF form-filling or a reference.md with API documentation — Claude can navigate to those files as needed. That's the third level and beyond. The key insight: agents with filesystem access don't need to load everything upfront. They can explore skill directories like a developer reading documentation.

Take Anthropic's PDF skill, which powers Claude's document editing abilities. The SKILL.md starts with YAML frontmatter:

---
name: PDF
description: Manipulate and fill out PDF forms
---

The body of SKILL.md contains core instructions for working with PDFs. But form-filling logic lives in a separate forms.md file. Claude only reads forms.md when it's actually filling out a form. This keeps the base skill lean and lets Claude navigate to specialized context only when the task demands it.

Skills can also bundle executable code. The PDF skill includes a Python script that extracts form fields from a PDF. Claude can run this script without loading the PDF or the script itself into the context window. This is critical for operations that need deterministic reliability or would be inefficient to perform via token generation. Sorting a list, parsing structured data, running cryptographic operations — these are better handled by code execution than by asking an LLM to generate the result token by token.

The context window management is elegant. Before Claude triggers a skill, the window contains the core system prompt, skill metadata, and the user's message. When Claude decides the PDF skill is relevant, it invokes a Bash tool to read pdf/SKILL.md. If it needs form-filling instructions, it reads forms.md. If it needs to extract form fields, it executes the bundled Python script. Each step loads only what's necessary.

This architecture mirrors how code execution with MCP reduces token waste. Instead of forcing the agent to process everything through the context window, you give it tools to operate on data outside that window. Skills extend this principle to procedural knowledge: instructions and code that the agent discovers and loads dynamically.

What This Changes For Developers

Agent Skills shift how you think about customizing AI agents. Instead of writing monolithic system prompts or building separate agents for each domain, you package expertise into composable units. Need Claude to handle Kubernetes deployments? Write a skill. Need it to follow your company's code review process? Write a skill. Need it to interact with a legacy API? Write a skill with bundled scripts and documentation.

The format is deliberately low-tech. A skill is a folder with a markdown file. You don't need to learn a new framework or deploy infrastructure. You write instructions in natural language, bundle any relevant scripts or reference docs, and drop the folder into Claude's skills directory. Claude handles discovery and loading.

This makes skills shareable. Teams can build internal skill libraries that codify institutional knowledge. Open-source projects can distribute skills alongside their codebases. You could imagine a future where installing a Python package also installs a skill that teaches Claude how to use that package's API.

The security model is straightforward but important: skills can execute code and access your filesystem. Only install skills from trusted sources. If you're pulling a skill from a less-trusted repository, audit it first. Read the bundled files, check for external network calls, inspect any code dependencies. Skills are powerful because they give Claude new capabilities. That power requires trust.

For organizations, skills solve the knowledge transfer problem. When a senior engineer leaves, their expertise often leaves with them. Skills let you capture procedural knowledge — how to debug a specific subsystem, how to deploy to a particular environment, how to handle edge cases in your data pipeline — in a format that agents can execute. It's not a replacement for documentation, but it's documentation that does something.

Try It Yourself

The simplest skill is a single SKILL.md file. Here's a minimal example for a skill that helps Claude follow a specific code review process:

---
name: Code Review
description: Follow company code review guidelines
---

# Code Review Process

When reviewing code, check for:

1. **Security**: No hardcoded credentials, proper input validation
2. **Performance**: No N+1 queries, appropriate caching
3. **Style**: Follows team conventions in STYLE_GUIDE.md

For database changes, read db-review-checklist.md before approving.

Drop this in a code-review/ directory, and Claude will load it when reviewing pull requests. If you reference STYLE_GUIDE.md or db-review-checklist.md, bundle those files in the same directory. Claude will navigate to them as needed.

For skills with executable code, include scripts in the skill directory and reference them in SKILL.md. Claude can run them directly or read them as documentation, depending on context.

Start by identifying where your agents struggle. Run Claude on representative tasks and watch where it needs additional context or makes repeated mistakes. Build skills incrementally to address those gaps. Use Claude itself to help: ask it to capture successful approaches into reusable instructions, or to self-reflect on what went wrong when it fails.

Anthropic's official docs and cookbook have more examples and best practices.

The Bottom Line

Use Agent Skills if you're building agents that need domain-specific expertise without bloating the context window. This is especially valuable for teams that want to codify institutional knowledge or developers working with complex, specialized workflows. The progressive disclosure model means you can bundle extensive documentation and code without paying the token cost upfront.

Skip this if you're working with simple, one-off tasks where a well-crafted system prompt is sufficient. Skills add overhead — you're managing directories, writing structured documentation, thinking about what context to split into separate files. For straightforward use cases, that overhead isn't worth it.

The real opportunity here is portability and sharing. Skills are an open standard, not a proprietary format. If the ecosystem develops around this — skill marketplaces, community-contributed libraries, skills bundled with open-source tools — it could fundamentally change how we distribute procedural knowledge to AI agents. The risk is fragmentation: if every platform invents its own skill format, we're back to building custom integrations for each tool. Anthropic's bet is that simplicity wins. A folder with a markdown file is easy enough that it might actually become a standard.

Source: Anthropic