How to Extend Claude with Custom Agent Skills Using SKILL.md

Claude is a powerful language model, but real‑world tasks often require specific programming knowledge and organizational context. To address this, Anthropic introduced Agent Skills , a method for building specialized agents by placing well‑structured instructions, scripts, and resources in a folder that the agent can discover and load dynamically.

A Skill is essentially a directory that contains a SKILL.md file. The file must start with a YAML front‑matter block that defines two required metadata fields: name and description. At startup the agent pre‑loads these fields into its system prompt, providing a lightweight first‑level disclosure that tells Claude when the Skill might be relevant without loading the full content.

The body of SKILL.md holds the second‑level details. If the agent deems the Skill relevant to the current task, it reads the full SKILL.md and any additional files referenced therein. This progressive disclosure mirrors a well‑organized manual: a table of contents, followed by chapters, and finally appendices.

Concrete example – PDF Skill : The PDF Skill enables Claude to fill out forms inside PDFs, a capability the base model lacks. The Skill’s directory contains SKILL.md plus two bundled files, reference.md and forms.md. By moving the form‑filling instructions into forms.md, the author keeps the core Skill concise while allowing Claude to load the detailed instructions only when it needs to process a form.

When a user asks Claude to complete a PDF form, the following sequence occurs:

The context window initially contains the core system prompt, the metadata of every installed Skill, and the user’s message.

Claude invokes the Bash tool to read pdf/SKILL.md, triggering the PDF Skill.

Claude decides the task requires the detailed form instructions and reads the bundled forms.md file.

With the relevant commands loaded, Claude proceeds to execute the user’s request.

Skills can also embed executable code. In the PDF Skill, a pre‑written Python script extracts all form fields from a PDF. Claude runs this script directly, avoiding the need to load the script or the PDF into the context window. Because the script’s behavior is deterministic, the workflow is repeatable and reliable.

Development and evaluation guidelines :

Start with evaluation: run the agent on representative tasks, identify gaps, and iteratively build Skills to fill those gaps.

Structure for scale: when SKILL.md grows unwieldy, split content into separate files and reference them, keeping rarely co‑used context separate to save tokens.

Think from Claude’s perspective: monitor how Claude uses the Skill, observe unexpected paths or over‑reliance on certain context, and refine the name and description fields accordingly.

Iterate with Claude: capture successful patterns and common errors as reusable context or code inside the Skill, and let Claude self‑reflect when a task deviates.

Security considerations : Because Skills introduce new instructions and code, malicious Skills could create vulnerabilities or cause data leakage. Install Skills only from trusted sources, audit bundled files before use, and scrutinize any network calls or external dependencies referenced in the Skill.

Future outlook : Today Skills are supported on Claude.ai, Claude Code, the Claude Agent SDK, and the Claude developer platform. In the coming weeks Anthropic plans to add full lifecycle features for creating, editing, discovering, sharing, and evaluating Skills, and to explore how Skills can teach agents more complex workflows that involve external tools, complementing the Model Context Protocol (MCP) server.

The simplicity of the Skill format—just a folder and a SKILL.md file—makes it easy for developers, organizations, and end users to build custom agents and extend Claude’s capabilities.