Agent Skills: Reusable Capability Packages

What a 'skill' actually is: a folder with instructions, scripts, and assets that an agent loads on demand.

What a skill is

A skill is a self-contained package that teaches an agent a repeatable capability. Instead of retyping instructions every session, you ship a folder the agent discovers and loads when relevant.

A minimal, well-formed skill contains:

my-skill/
├── SKILL.md        # frontmatter (name, description) + instructions
├── scripts/        # executable code the agent can run
├── references/     # docs loaded only when needed
└── assets/         # templates, images, boilerplate

The core design rule: progressive disclosure

Load information in three tiers, so the context window stays small:

1. Metadata (always loaded) — the name and description in frontmatter, just enough to decide relevance.
2. Body (loaded on match) — the main SKILL.md instructions.
3. Bundled resources (loaded on demand) — scripts and reference docs, referenced from the body.

A skill whose entire content is crammed into tier 1 defeats the purpose — it burns context on every request, relevant or not.

Writing a description that actually triggers

The description field is the single biggest lever on whether your skill fires. Include:

• What it does
• When to use it (specific trigger conditions, file types, user intents)
• What format it produces

Weak: Helps with documents.

Strong: Extracts text and tables from PDF files, fills forms, merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

Common failure modes