Overview
Agent Skills are an open format for extending what an agent can do. A skill is usually a directory: the required file is SKILL.md, and the directory can also include reference material, templates, images, data files, or executable scripts.
skill-name/
├── SKILL.md # Required: metadata + instructions
├── scripts/ # Optional: executable code
├── references/ # Optional: detailed docs, checklists, conventions
├── assets/ # Optional: templates, images, examples
└── ...SKILL.md contains YAML frontmatter followed by Markdown instructions. The frontmatter must include at least name and description; the body tells the agent how to perform the task.
The format comes from Anthropic’s Claude Skills. Anthropic introduced Skills on October 16, 2025, so Claude could load a folder of instructions, scripts, and resources when they were relevant to a task. On December 18, 2025, Anthropic published Agent Skills as an open standard maintained at agentskills.io. See the Agent Skills specification for the format details.
Why It Is Called A Skill
A Skill is not just a prompt template, and it is not just a tool. It is closer to a reusable task capability: the agent can discover it, load it, and follow it to complete a class of work.
A good Skill contains three things:
- when to use it:
nameanddescriptionhelp the agent decide whether the current task is relevant; - how to do the work:
SKILL.mdcaptures the steps, constraints, criteria, and failure handling; - what it depends on: scripts, templates, specs, and examples live in the same folder and are loaded or executed only when needed.
That is why the abstraction is called a Skill: it packages a discoverable, loadable, reusable way to do work. A prompt is usually a one-off instruction. A tool is an external action interface. A Skill bundles knowledge, process, and resources so a general agent can behave more like an experienced operator for a class of tasks.
When To Write A Skill
Skills are for knowledge that is not project facts and not one-off prompting: workflows, checklists, writing style, compliance steps, API conventions, template-filling rules, and script execution procedures.
Three signals suggest something should become a skill:
- You keep pasting the same playbook. Every code review, weekly update, PDF workflow, or campaign draft starts with the same copied checklist.
- The system prompt is getting bloated. What started as identity, boundaries, and project facts is filling up with procedural content: “when X happens, follow process Y.”
- The same rule must work across agents or projects. Copying the rule creates drifting versions; a skill gives the team one source of truth.
Once packaged as a skill, that knowledge can be versioned, reused across projects, and loaded only when the task calls for it.
Skill Versus Prompt
A skill still gives the model textual instructions, but it is not just “more Markdown in the system prompt.” The difference is how it loads.
The system prompt is always on: every call carries it, whether the task needs it or not. A skill is on demand: the agent first sees a lightweight list of available skills; when a task matches, it loads the full instructions; when it needs deeper material, it reads the referenced files.
That creates two useful properties:
- Lower baseline cost: the always-on context only needs each skill’s name and description.
- Deeper capability: detailed specs, templates, and scripts can live in the skill folder instead of crowding the main prompt.
Progressive Disclosure
The core mechanism is progressive disclosure: give the agent enough information to decide, then load richer content only when it is needed.
| Level | Loaded content | When it loads | Purpose |
|---|---|---|---|
| L1 | name and description | Startup loads metadata for all skills | Let the agent know which capabilities exist |
| L2 | SKILL.md body | When the task matches a skill | Provide workflow, steps, constraints, and criteria |
| L3 | Files in references/, assets/, scripts/, etc. | When L2 instructions ask for them | Provide detailed docs, templates, examples, or executable capability |
That is the leverage: the agent can keep many capabilities available without carrying every capability’s full instructions in every context.
description Is The Trigger
The description field is the main signal the agent uses to decide whether to load a skill. It is not only a human-readable summary; it is a search index and trigger condition.
A good description says both:
- what the skill does;
- which tasks, files, scenarios, or keywords should activate it.
For example:
description: Extract text and tables from PDF files, fill PDF forms, and merge multiple PDFs. Use when working with PDFs, forms, scanned documents, or document extraction.A weak description is too generic:
description: Helps with documents.The first description can match “PDF,” “forms,” and “document extraction.” The second barely helps the agent decide when to load it.
Where Content Belongs
The main design move is to split content across levels:
| Content | Location | Reason |
|---|---|---|
| Skill name, purpose, and triggers | Frontmatter | The agent uses this to decide whether to load the skill |
| Main steps and constraints | SKILL.md body | Must be visible immediately after activation |
| Long specs, domain knowledge, examples | references/ | Read only when the relevant step needs them |
| Output templates, sample files, images | assets/ | Needed only during generation or conversion |
| Reusable execution logic | scripts/ | Prevent the agent from hand-writing complex, error-prone operations |
A practical rule: the main file directs; supporting files carry depth. If SKILL.md keeps growing, move detailed material into references/ and tell the agent exactly when to read which file.
Common Shapes
The Agent Skills standard defines the directory format. In practice, skills often take a few recurring shapes:
| Shape | Best for |
|---|---|
| Tool Wrapper | Teaching the agent when to use a tool, how to fill arguments, and how to recover from failures |
| Generator | Producing a repeated artifact type: reports, emails, pages, contract drafts |
| Reviewer | Reviewing code, documents, designs, or compliance risks against a checklist |
| Inversion | Turning existing user material back into structured knowledge, such as extracting team conventions from docs |
| Pipeline | Chaining a multi-step workflow: gather material, draft, verify, export |
These are organization choices, not part of the specification. The real criteria are still whether description
triggers correctly, SKILL.md stays concise, details load on demand, and outputs can be verified.
A special shape is the Meta Skill. Instead of performing a business task directly, it teaches the agent how to create new skills. A meta skill usually references the specification, examples, and naming conventions so the agent can draft a new SKILL.md when it notices repeated work.
Multi-Skill Composition
When an agent can see L1 metadata for multiple skills, it can decide whether to load one skill or several.
For example, if the user says, “Write a blog introduction and make it SEO-friendly,” clear descriptions let the agent load both blog-writer and seo-checklist: one for the writing workflow, one for the SEO review.
The negative case matters too. If no skill matches, a well-designed system should let the agent say that it does not currently have that capability, rather than pretending a workflow exists.
Storage And Reuse
Skills become more valuable as they are reused. Common locations:
- Project-level: inside the repo, such as
<project>/.agents/skills/, for team-shared skills that are reviewed and released with code. - User-level: in a user directory, such as
~/.agents/skills/, for personal skills reused across projects.
Because a skill is just a folder of files, it works well with git: review, tag, rollback, and promote stable skills into a team library. External skills should be treated like dependencies: review the content, license, and script permissions before loading them into a runtime environment.
What To Read Next
- Writing Guide: how to extract a Skill from repeated work, choose the right structure, then test and iterate it.
- Integration guide: how a harness discovers, loads, authorizes, and observes skills. The Chinese version is available at 集成指南; the English version has not been added yet.