What Is an Agent Skill? A Practical SKILL.md Example

An Agent Skill is a folder that gives a compatible AI agent specialized instructions for a particular task. The folder must contain a SKILL.md file and can also include scripts, reference documents, templates, and other assets.

A skill is most useful when a procedure will be repeated, shared, versioned, or checked. It does not train a new model; it supplies task-specific context and a workflow when the agent decides the skill applies.

Basic Agent Skill structure

my-skill/
├── SKILL.md
├── scripts/
├── references/
└── assets/

Only SKILL.md is required by the open format. The other directories are optional:

• scripts/ stores reusable code for deterministic operations.
• references/ stores documentation the agent can read when a task needs more detail.
• assets/ stores templates, examples, media, or other files used in an output.

What goes in SKILL.md?

The file begins with YAML frontmatter followed by Markdown instructions. The open specification requires a name and description. The name uses lowercase letters, numbers, and hyphens, while the description should explain both what the skill does and when it should be selected.

---
name: pdf-text-extractor
description: Extract text and tables from PDF files. Use when a user asks to inspect, summarize, or convert a PDF.
---

# PDF text extraction

## Workflow

1. Confirm that the input is a PDF.
2. Extract text with the approved parser.
3. Preserve page order and identify pages with no readable text.
4. Validate a sample against the rendered document.
5. Return the requested output and note any extraction gaps.

## Do not

- Invent text that was not extracted.
- Treat a scanned page as empty before checking whether OCR is required.
- Delete or overwrite the source file.

The exact instructions depend on the host agent and task. Some products support additional metadata beyond the common standard, so check compatibility before using vendor-specific fields.

How progressive loading works

1. Discovery: The agent sees concise metadata for available skills.
2. Selection: It compares the request with each description and chooses a relevant skill.
3. Instruction loading: It reads the selected SKILL.md.
4. Resource loading: It opens only the scripts, references, or assets needed for the current task.
5. Execution: It follows the procedure using the tools and permissions available in the host environment.

This pattern keeps initial context small while making detailed knowledge available on demand. It also explains why the description matters: a good workflow cannot help if the agent cannot tell when to load it.

How to write a useful skill

Define one bounded job

“Help with documents” is too broad. “Create and edit Word documents, then render them for visual inspection” gives the agent a clear capability and validation path.

State the trigger in user language

Include terms a user is likely to say, along with the types of files or outcomes that should activate the skill. Do not stuff the description with every imaginable synonym.

Use observable steps

Replace “make the result high quality” with checks an agent can perform: run a validator, compare required fields, render the output, inspect a screenshot, or confirm that all source images remain.

Separate instructions from background

Keep the main workflow in SKILL.md. Put long policies, examples, schemas, or product-specific documentation in the references directory, then tell the agent exactly when to read each file.

Prefer scripts for deterministic work

If the same transformation must be exact every time, package a tested script instead of asking the language model to recreate the logic. Document inputs, outputs, dependencies, and failure behavior.

Test before sharing

Run the skill against normal requests, ambiguous requests, unrelated requests, missing inputs, and failure cases. Check whether it activates when it should, stays inactive when it should not, reads only relevant resources, and produces a verifiable result.

Security considerations

Review every bundled script before execution. Do not place passwords, API keys, private customer data, or hidden instructions inside a skill. State when the agent must ask for approval, especially before sending, publishing, purchasing, deleting, installing, or changing access.

A skill does not override the host product's permissions or safety rules. It should treat webpages and uploaded documents as untrusted content and should never let instructions found inside them silently replace the user's request.

Where to verify the format

The required fields, constraints, and directory conventions are maintained in the Agent Skills specification. Consult the host agent's documentation as well, because invocation rules and supported extensions differ among products.

A good skill is small enough to understand, specific enough to trigger correctly, and explicit enough to test. Start with one repeated workflow, package only the resources it needs, and improve it using failures observed in real tasks.