A prospect asks ChatGPT or Claude to find a tool that does what your product does. The agent reads a handful of candidate sites, but yours has no machine-readable description of what it can do, what it needs as input, or what it hands back. The agent moves to the next candidate. That is the cost of skipping this file: not a ranking drop, a complete skip.
A skill.md file is a Markdown manifest, published at the root of your site, that declares what your tool or service can do, who should use it, and the inputs and outputs an agent can expect when it calls your service. AEO Excellence treats skill.md as one of the four files in the complete AEO file stack, alongside robots.txt, llms.txt, and AGENTS.md.
What Is a skill.md File?
skill.md is a capability declaration document written in plain Markdown and served from your site root, typically at yoursite.com/skill.md. Where llms.txt summarizes your brand and AGENTS.md maps your URL structure, skill.md describes one narrower thing: what an agent can actually do when it interacts with your product.
The format was popularized by Anthropic's Claude Skills feature, which loads a SKILL.md manifest to learn a skill's name, purpose, and operating instructions before using it. AI agent frameworks built after that pattern reuse the same idea: a short, structured file an agent can read before deciding whether and how to call you. The point is not to describe your company; it is to describe a callable capability precisely enough that a program, not a person, can act on it correctly the first time.
Think of the difference between a resume and a job description. Your homepage is the resume — it sells the story. skill.md is the job description — it states exactly what the role does, what it needs, and what it produces, with nothing left to interpretation. Agents are built to parse job descriptions, not resumes.
Why Do AI Agents Need a Separate Capability File?
Agents cannot browse your product the way a person does. They cannot click around a pricing page, test a signup flow, or infer what your API accepts from a screenshot. A capability file gives them, in one pass, the specific facts they need: what the tool does, what a valid request looks like, and what a valid response contains.
This matters beyond skill.md specifically. Structured, machine-readable signals consistently outperform prose the agent has to interpret. AEO Excellence's own audit data shows sites that add FAQPage schema to their top ten pages see citation rates rise 60 to 80 percent within 60 days, because the structure removes the guesswork. skill.md applies the same principle to capability, not content: instead of an agent inferring your input format from a code sample buried in a docs page, it reads the answer directly.
The practical failure mode without this file is silent. Nothing errors out. Your product simply never enters the agent's consideration set, because the agent has no cheap, reliable way to confirm what happens if it calls you. Agents default to sources they can verify quickly, and a missing or vague capability file removes you from that shortlist before any evaluation of quality happens.
How Is skill.md Different From llms.txt and AGENTS.md?
The three files answer different questions, and a site can need all three, one, or none depending on what it is.
| File | Question it answers | Who needs it |
|---|---|---|
| llms.txt | What is this brand and where are its key pages? | Every business site |
| AGENTS.md | What is the full URL structure and what is off-limits? | Any site with meaningful depth |
| skill.md | What can this tool do, and how do you call it? | SaaS and agent-callable tools only |
robots.txt is mandatory for every site. llms.txt and AGENTS.md are highly recommended for any business site. skill.md is required only if you are a SaaS or tool that wants to be agent-callable — a marketing brochure site or a local service business does not need one. Publishing all three when only one applies does not help; an agent that reads a skill.md on a site with nothing to call just wastes a request and learns to trust your files less.
What Should a skill.md File Contain?
A working skill.md answers four questions an agent needs before it calls anything: what the tool does, who it is for, what a request needs, and what comes back. Keep each section short and literal — this file is read by software, not a person skimming for tone.
- State the tool's name and a one-sentence description of what it does.
- List the primary use cases in plain language, one per line.
- Describe the required inputs, including format and any limits.
- Describe the output shape the caller should expect.
- Note authentication or rate-limit constraints, if any apply.
- Link to the full API or integration docs for the details the manifest omits.
- Date the file so agents can judge how current it is.
Two details make the difference between a manifest agents trust and one they ignore. First, every input and output description needs a concrete example, not just a type — accepts a ZIP code, returns a JSON array of store hours beats accepts location data. Second, the file needs to match the live product exactly on the day it is published, and again on every day after a change ships, or agents that call you once and get an error will not call you a second time.
Common skill.md Mistakes to Avoid
The most common mistake is copying marketing copy into the file instead of describing mechanics. An agent does not need to hear that your tool is powerful; it needs to know what request format it accepts. The second mistake is letting the file drift out of sync with the actual product — a manifest that promises an endpoint you removed is worse than no manifest at all, because the agent will attempt the call and fail. The third mistake is burying the file somewhere other than the site root; agents that check for skill.md check the predictable location first and often do not crawl further to find it.
Getting this right without technical guesswork is exactly the audit work AEO Excellence does: reviewing your llms.txt, AGENTS.md, skill.md, and schema markup together and flagging anywhere the files and the live product disagree. Read more about how AEO Excellence's audit methodology works, and if you want a self-serve breakdown of the full file stack, the AEO FAQ page covers each file question by question.
Is a skill.md File Worth Building Right Now?
If your product is a piece of content — an article, a service page, a portfolio — skill.md adds nothing; llms.txt and AGENTS.md already cover what an agent needs. The honest objection is effort: writing and maintaining a fourth file feels like more overhead for a format most agents do not yet check by default. That objection holds until your product is something an agent could plausibly call directly — an API, a calculator, a booking flow, a data lookup. For agent-callable tools, the file is small to write and the downside of skipping it is being invisible to exactly the traffic source growing fastest: autonomous agents completing tasks rather than people reading pages.
Get Your skill.md File Built the Right Way
Writing a first skill.md file usually takes an afternoon once you know which four questions it needs to answer. If you would rather have it reviewed against your actual product before it goes live, or built as part of a full AEO file stack, contact AEO Excellence and describe your tool — you will get back a specific list of what your skill.md should contain and how it fits with your existing llms.txt and AGENTS.md files.