Equipping Agents for the Real World with Agent Skills

Published: October 16, 2025

Authors: Barry Zhang, Keith Lazuka, and Mahesh Murag

---

Claude is powerful, but real work requires procedural knowledge and organizational context. This article introduces Agent Skills, described as "organized folders of instructions, scripts, and resources that agents can discover and load dynamically." Skills extend Claude's capabilities by packaging expertise into composable resources, transforming general-purpose agents into specialized ones.

Update (December 18, 2025): Agent Skills were published as an open standard for cross-platform portability at agentskills.io.

The Anatomy of a Skill

The article walks through a real example: the PDF skill that powers Claude's document editing abilities. Claude already understands PDFs well but had limited ability to manipulate them directly (such as filling out forms). The PDF skill provides these new capabilities.

At its simplest, "a skill is a directory that contains a SKILL.md file." This file must begin with YAML frontmatter containing required metadata: name and description. At startup, the agent pre-loads the name and description of every installed skill into its system prompt.

This metadata represents the first level of progressive disclosure — enough information for Claude to determine when a skill is relevant without loading everything. The body of the file is the second level of detail; if Claude determines the skill applies to the current task, it reads the full SKILL.md into context.

Additional Files

As skills grow in complexity, they may contain too much context for a single SKILL.md, or context relevant only in specific scenarios. Skills can bundle additional files within the skill directory and reference them by name. These serve as the third level (and beyond) of detail.

In the PDF example, the SKILL.md references two additional files: reference.md and forms.md. By moving form-filling instructions to a separate file, the skill author keeps the core skill lean, trusting that Claude will read forms.md only when actually filling out a form.

Progressive Disclosure

The article describes progressive disclosure as the core design principle making Skills flexible and scalable. The analogy used: "Like a well-organized manual that starts with a table of contents, then specific chapters, and finally a detailed appendix." Skills let Claude load information only as needed, meaning "the amount of context that can be bundled into a skill is effectively unbounded."

Skills and the Context Window

The sequence when a skill is triggered:

1. The context window begins with the core system prompt, metadata for installed skills, and the user's initial message.
2. Claude triggers the PDF skill by invoking a Bash tool to read the contents of pdf/SKILL.md.
3. Claude reads the forms.md file bundled with the skill.
4. Claude proceeds with the user's task now that it has loaded relevant instructions.

Skills and Code Execution

Skills can include code for Claude to execute at its discretion. The article notes that LLMs excel at many tasks but "certain operations are better suited for traditional code execution." For instance, sorting a list via token generation is far more costly than running a sorting algorithm. Many applications also need the deterministic reliability that only code provides.

The PDF skill includes a pre-written Python script that reads a PDF and extracts form fields. Claude can run this script without loading either the script or the PDF into context, and because code is deterministic, the workflow is consistent and repeatable.

Developing and Evaluating Skills

Guidelines for authoring and testing skills:

• Start with evaluation: Identify specific capability gaps by running agents on representative tasks and observing where they struggle, then build skills incrementally to address shortcomings.
• Structure for scale: Split content into separate files when SKILL.md becomes unwieldy. Keep paths separate for mutually exclusive or rarely co-used contexts to reduce token usage. Code can serve as both executable tools and documentation — it should be clear whether Claude should run scripts or read them as reference.
• Think from Claude's perspective: Monitor how Claude uses your skill and iterate based on observations, watching for unexpected trajectories or overreliance on certain contexts. Pay special attention to the name and description, since Claude uses these when deciding whether to trigger a skill.
• Iterate with Claude: Ask Claude to capture successful approaches and common mistakes into reusable context and code. If it goes off track, ask it to self-reflect on what went wrong. This helps discover what context Claude actually needs rather than trying to anticipate it upfront.

Security Considerations

Skills provide Claude with new capabilities through instructions and code, which makes them powerful but also means "malicious skills may introduce vulnerabilities" or "direct Claude to exfiltrate data and take unintended actions."

The recommendation is to install skills only from trusted sources. When using a skill from a less-trusted source, thoroughly audit it first — read the bundled files, paying attention to code dependencies, bundled resources like images or scripts, and any instructions that connect to potentially untrusted external network sources.

The Future of Skills

Agent Skills are supported across Claude.ai, Claude Code, the Claude Agent SDK, and the Claude Developer Platform. Planned developments include features supporting the full lifecycle of creating, editing, discovering, sharing, and using Skills. The team is also exploring how Skills can complement Model Context Protocol (MCP) servers by teaching agents more complex workflows involving external tools.

Looking further ahead, the goal is to enable agents to create, edit, and evaluate Skills on their own, "letting them codify their own patterns of behavior into reusable capabilities."

The article concludes that Skills are a simple concept with a simple format, making it easier for organizations, developers, and end users to build customized agents. Resources are available at the Skills docs and cookbook.