Agent skill

Also known as: agent skills

On this page 6

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.

ComponentPurposeWhen it is loaded
Metadata headerName and description used for selectionAlways, at session start
Instruction bodyWorkflow, rules and decision stepsWhen the skill is triggered
Reference filesDetailed guides, schemas, examplesOnly when the instructions point to them
ScriptsDeterministic code for validation or conversionExecuted on demand, output read back
Assets and templatesFonts, document templates, imagesUsed by scripts or copied into output
Typical components of a skill package

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.

MechanismWhat it providesContext costTypical example
Agent skillProcedural knowledge and bundled scriptsLow until triggeredBrand-compliant report workflow
Tool callingA single executable functionSchema always visibleSearch the web, run a query
MCP serverAccess to external systems and dataTool list always visibleConnect a ticketing system
System promptGlobal behavior and personaAlways presentTone and safety rules
SubagentAn isolated worker with its own contextSeparate context windowParallel code review
How skills relate to neighboring mechanisms

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 questionRecommended choiceReason
Where to put long guidanceSeparate reference filesKeeps the main file within budget
How to handle exact checksBundled validation scriptRemoves model guesswork
How to write the descriptionList concrete trigger phrasesImproves selection accuracy
How to scope the skillOne coherent workflow per skillAvoids conflicting instructions
How to measure qualityTest prompts with expected outcomesDetects regressions after edits
Design decisions and recommended choices

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.