An agent skill is a packaged, reusable capability that an AI agent can discover and load when a task calls for it, typically consisting of written instructions, optional scripts and reference files bundled in one folder. In the field of AI agents, skills turn procedural know-how into a portable unit, so the same agent can follow a company’s report format, process spreadsheets or apply a review checklist without that knowledge sitting permanently in its prompt.
The concept became concrete when agent platforms introduced folder-based skills described by a short metadata header and a main instruction file, commonly named SKILL.md. Collections of such packages are usually called agent skills, and the format has since been adopted across several agent frameworks and coding agents as an open, file-based convention.
How an agent skill is structured and loaded
An agent skill works through progressive disclosure: the agent sees only a compact description of each available skill until a task matches it, and then reads the full instructions and any needed files. This keeps the context window small while allowing a large library of skills to be installed at once.
A typical skill folder contains a main file with a name and description in YAML front matter, a body of step-by-step guidance, and optional subfolders for scripts, templates and reference documents. The description acts as the trigger condition, so its wording determines whether the agent selects the skill at the right moment.
| Component | Purpose | When it is loaded |
|---|---|---|
| Metadata header | Name and description used for selection | Always, at session start |
| Instruction body | Workflow, rules and decision steps | When the skill is triggered |
| Reference files | Detailed guides, schemas, examples | Only when the instructions point to them |
| Scripts | Deterministic code for validation or conversion | Executed on demand, output read back |
| Assets and templates | Fonts, document templates, images | Used by scripts or copied into output |
Agent skills compared with tools, prompts and subagents
An agent skill teaches the agent how to do something, whereas a tool gives it a callable function and a subagent gives it a separate worker. Skills often orchestrate existing tools: a skill for preparing invoices may instruct the agent to call a spreadsheet script, check totals and then use a document tool, without adding any new tool schema.
Skills also differ from a long system prompt. A system prompt is always present and always paid for in tokens, while a skill costs almost nothing until it is needed. Compared with an MCP server, which exposes external systems through a protocol, a skill is usually plain files on disk that encode procedure rather than connectivity.
| Mechanism | What it provides | Context cost | Typical example |
|---|---|---|---|
| Agent skill | Procedural knowledge and bundled scripts | Low until triggered | Brand-compliant report workflow |
| Tool calling | A single executable function | Schema always visible | Search the web, run a query |
| MCP server | Access to external systems and data | Tool list always visible | Connect a ticketing system |
| System prompt | Global behavior and persona | Always present | Tone and safety rules |
| Subagent | An isolated worker with its own context | Separate context window | Parallel code review |
Designing an effective agent skill
An effective skill has a precise, trigger-oriented description, a short main file and well-separated reference material. Authors write the description in terms of the user requests that should activate it, because the agent decides relevance from that text alone. The main file stays concise, often a few hundred lines at most, and points to deeper files instead of inlining them.
Deterministic steps belong in scripts rather than prose. Asking a language model to compute checksums, validate a JSON schema or count words invites errors, while a bundled script returns an exact result that the agent reads back. Good skills also state explicit success criteria, so the agent can verify its own output before finishing.
| Design question | Recommended choice | Reason |
|---|---|---|
| Where to put long guidance | Separate reference files | Keeps the main file within budget |
| How to handle exact checks | Bundled validation script | Removes model guesswork |
| How to write the description | List concrete trigger phrases | Improves selection accuracy |
| How to scope the skill | One coherent workflow per skill | Avoids conflicting instructions |
| How to measure quality | Test prompts with expected outcomes | Detects regressions after edits |
Security, governance and common mistakes
Agent skills carry real security risk because they combine instructions with executable code that runs with the agent’s permissions. A malicious or careless skill can exfiltrate data, call unexpected endpoints or contain prompt injection hidden in reference files. Organizations therefore treat skills like software dependencies: they review the source, pin versions and install only from trusted catalogs.
Governance also covers agent permissions and sandboxing. Scripts from a skill should run in an agent sandbox with restricted network and file access, and actions with side effects, such as sending messages or publishing content, should still require human-in-the-loop approval where policy demands it.
- Vague descriptions cause skills to trigger on unrelated tasks or never trigger at all.
- Overlapping skills give the agent contradictory instructions for the same request.
- Bloated main files waste context and bury the critical rules.
- Unpinned external downloads inside scripts break reproducibility and widen the attack surface.
- Untested edits silently change agent behavior across every task that uses the skill.
In everyday language
An agent skill is like a recipe card in a kitchen drawer. The cook does not memorize every recipe; the cook glances at the card titles, pulls out the right one when a dish is ordered and follows it step by step.
For an AI agent, the card holds instructions and sometimes small helper programs. The agent reads only the titles until a job matches, then opens the full card. This lets one assistant handle many specialized jobs reliably without being overloaded with information it does not need.
Seen in the real world
A mid-sized accounting firm uses a coding agent to prepare monthly client reports. Staff previously pasted the same formatting rules into every conversation, and results varied. The firm packages the rules into a single report skill: a main file of about 150 lines describing the workflow, a reference file with the house style, an Excel template and a Python script that checks totals and date formats.
The skill description lists triggers such as monthly report, client summary and reconciliation pack. After rollout, the agent loads the skill automatically for those requests, runs the validation script before delivering each file and flags any mismatch. Reviewers report far fewer formatting corrections, and when the house style changes, the firm updates one reference file instead of retraining staff on new prompts.