What Is SKILL.md? How AI Agents Use Written Instructions to Do Reliable Work

AI agents are often described as autonomous, but they do not arrive knowing your company’s procedures. A SKILL.md file is one way to give them that missing knowledge: a plain-text instruction sheet that an agent reads when a task matches it. The simplest analogy is an onboarding guide for a new employee, stored in a folder rather than pasted into every conversation.

The short answer

A “skill” is a folder containing a required file named SKILL.md. That file holds two things: a small header that identifies the skill and says when it should be used, and a body of instructions that explains how to perform the task. The folder can also contain optional scripts, reference documents, templates, and other resources. This structure is now an open format used across multiple AI tools, not a Claude-only convention; Anthropic published it as an open standard, and other agent platforms such as Cloudflare Agents document the same anatomy (Agent Skills specification, Cloudflare Agents docs).

What is inside a SKILL.md file

The file begins with a short metadata block, often called YAML frontmatter. In plain terms, it is a label at the top of the document. Two fields are required:

• name — a short identifier for the skill, such as invoice-review.
• description — a sentence or two saying what the skill does and when to use it.

The description matters more than it looks. It is the signal an agent uses to decide whether the skill is relevant to the current request. A description that says only “helps with invoices” is weaker than one that says “checks invoices for missing approvals, validates totals, and escalates exceptions.” The specification limits the name to 64 characters and the description to 1,024 characters, so the metadata must be concise (specification).

Below the header is the body: the actual procedure. It can include steps, decision rules, examples, output formats, quality checks, and escalation paths. A minimal shape looks like this:

---
name: invoice-review
description: Checks invoices for missing approvals and escalates exceptions.
---

Purpose: review an invoice before payment.
Steps: verify vendor, totals, approval, and duplicate charges.
Exceptions: escalate missing approval or mismatched totals.
Output: a short review note with pass/fail status.

The header is not the instruction; it is the index entry. The body is the instruction the agent follows once the skill is triggered.

How an agent actually uses it

Agents load skills in stages, a design principle called progressive disclosure. At startup, the agent loads only each skill’s name and description into its working context — roughly 100 tokens per skill according to Anthropic’s documentation. That is enough to know the skill exists without reading every instruction. When a request matches a skill’s description, the agent loads the full SKILL.md body. If the body points to additional files, such as a detailed reference guide or a form-filling document, the agent reads those only when needed (Anthropic Agent Skills overview, Anthropic research article).

This is why a skill is different from a prompt. A prompt is a one-off instruction for a conversation; a skill is a reusable, filesystem-based resource that can be loaded on demand. Anthropic describes the benefit as reducing repetition: write the guidance once, and the agent can use it automatically when the task fits (overview).

Why businesses should care

For a business, the value is not the file extension. It is the ability to turn tacit procedures into explicit, reusable guidance.

• Consistency: a skill can encode the same steps, thresholds, and tone every time a task is handled.
• Auditability: the instructions live in a version-controlled file, so changes can be reviewed and traced.
• Specialization: a general-purpose agent can be given domain knowledge — compliance review, customer escalation, brand voice, invoice checks — without rebuilding the agent for each use case.
• Portability: because the format is open, a skill can be reused across compatible agent platforms rather than tied to one vendor.

Anthropic’s engineering article frames a skill as “an onboarding guide for a new hire” and as a way to package procedural knowledge into composable resources (research article). That is a useful mental model for managers: the skill is the written playbook, while the agent is the worker applying it.

What SKILL.md is not

It is not model training or fine-tuning. It does not permanently change the model’s weights; it supplies context at runtime. It is not a program that enforces a rule, and it is not a guarantee that the agent will behave correctly. It is also not a replacement for human judgment in high-stakes work.

A skill can be outdated, incomplete, or contradictory. If the file says “approve invoices under $5,000” but the policy has changed to $2,500, the agent may follow the old instruction. The file is only as reliable as its owner and review process.

How to write one for a business task

A practical skill should be narrow enough to be useful and clear enough to be tested. A workable pattern is:

• Name by task, not department. “customer-escalation” is clearer than “support-team-guidance.”
• Make the description trigger-rich. State what the skill does and the situations that should activate it.
• Write the body as a procedure. Include purpose, required inputs, steps, decision rules, exceptions, output format, and when to escalate.
• Keep the core lean. Move long reference material, forms, or examples into linked files so the main body stays readable.
• Include checks. Add quality checks and examples of correct and incorrect output.
• Assign an owner and a version. Review it when policies, products, or workflows change.

For example, a customer-support triage skill might specify: identify the issue type, collect the minimum required details, decide whether the case is routine or urgent, use a defined tone, and escalate when the customer is threatening cancellation or the issue involves billing disputes. That is more useful than a vague instruction such as “be helpful.”

Governance and risks

Skills are instructions, not trusted facts. An agent may follow a skill that contains errors, outdated policy, or even malicious content. Treat skill files as you would treat any operational document: review them, restrict who can edit them, and keep sensitive data out. Do not put passwords, customer records, or confidential credentials in a skill file.

There is also a permission question. Some skill formats allow a list of pre-approved tools, but that is an experimental feature; it should not be treated as a security control by itself (specification). Pair skills with access controls, logging, and human review for regulated or high-stakes work. Anthropic’s best-practices guidance also stresses conciseness: once a skill is loaded, every token competes with the rest of the conversation, so verbose instructions can crowd out more important context (best practices).

The practical takeaway

SKILL.md is best understood as a documented procedure for an agent. It gives the agent a discoverable instruction sheet, loads the details only when relevant, and lets a business reuse expertise across tasks and tools. The file itself is simple; the real work is the clarity, ownership, testing, and review behind it. Start with one recurring workflow, write the steps plainly, test the agent against real examples, and update the skill when the business rules change.

Sources

• Anthropic — Agent Skills overview
• Anthropic — Equipping agents for the real world with Agent Skills
• Agent Skills — specification
• Anthropic — Skill authoring best practices
• Cloudflare Agents — Agent Skills