What Are AI Agent Skills? The SKILL.md Pattern Explained
An AI agent skill is a structured markdown file — usually named SKILL.md — that packages domain expertise an agent loads on demand: the process, the frameworks, the templates, and the quality bar for one specific job. Instead of re-explaining how you want something done every single session, the skill carries that knowledge permanently, and it works in any agent that can read a markdown file.
That last part is what makes skills a genuinely different category from prompting. A prompt is speech: you say it, the agent hears it, the conversation ends, and the knowledge evaporates. A skill is a file: versioned, editable, portable, and refined every time it runs in production. Prompts are how you talk to an agent. Skills are how your business remembers.
What does a skill actually contain?
A well-built skill is not a paragraph of vibes. In the FAST framework, a skill follows a strict anatomy:
- YAML frontmatter — the skill's name and a description of when it should trigger. This is how the agent knows, out of hundreds of skills, that this one matches the task at hand.
- A defined structure — FAST skills use 19 required sections: quick start, core frameworks, tiered tactics, templates, and more. Structure is what separates a skill from a note-to-self.
- Templates and examples — the actual artifacts the agent should produce, so output quality doesn't depend on the agent improvising format.
- A quality checklist — the pass/fail criteria the agent runs before calling the job done. This is the variance-control mechanism: skills shape probabilistic reasoning, and the checklist constrains the spread.
The frontmatter matters more than beginners expect. Agents don't read your entire skill library on every task — that would drown the context window. They read the name and description of each skill, pick the match, and load the full file only when needed. Anthropic calls this pattern progressive disclosure, and it's why a library of hundreds of skills stays fast: the agent skims the card catalog, not the whole library.
How is a skill different from a prompt, a GPT, or fine-tuning?
| Approach | Persistence | Portability | Who can edit it |
|---|---|---|---|
| Prompt | One conversation | None | Whoever retypes it |
| Custom GPT / platform bot | Lives on the platform | Locked to the vendor | You, within their limits |
| Fine-tuning | Baked into one model | That model only | ML engineers |
| SKILL.md | Permanent file in your repo | Any agent that reads markdown | Anyone who can edit text |
The portability row is the strategic one. A custom bot built inside a walled garden is hostage to that garden's roadmap. A skill is a text file in a git repo you own. When a better model ships, your entire knowledge library moves with you the same afternoon — nothing to migrate, nothing to rebuild. This is the "own the factory" principle applied to knowledge.
How are skills organized at scale?
One skill is a trick. Three hundred is an operating system — but only if they're organized. FAST's 300+ skills are structured by the OSLO taxonomy: Offers (creation and pricing), Sales (scripts and funnels), Leads (outreach and nurture), and Operations (systems and finance). Every business task maps to one of the four, so there's no ambiguity about where a skill lives or which one handles a given job. The full method is in how to structure a library of agent skills.
The library is also self-expanding: FAST includes a meta-skill — a skill whose job is creating new skills to the same standard. Do a job manually once, capture the process, and the meta-skill turns it into a SKILL.md with correct frontmatter, all required sections, and a quality checklist. Your playbook compounds instead of living in your head.
Why do skills beat "just prompt better"?
Three reasons, in descending order of importance:
- Consistency. A skill runs the same playbook on Monday as it did on Friday, whoever invoked it. Prompting from memory produces a different agent every day.
- Leverage across agents. Every skill you write works with every agent in your fleet — Claude Code, OptimusOS, a Telegram bot. Write once, deploy everywhere. This is the multiplicative math of the agent factory.
- Compounding. When a skill produces a mediocre result, you fix the file, and it never makes that mistake again. Prompts can't accumulate lessons. Files can.
A skill is the difference between hiring someone smart and hiring someone smart who has read your standard operating procedures.
What do skills NOT do?
Skills don't touch the world. They're knowledge, not connectivity — a skill can tell an agent exactly how to structure an invoice, but sending it requires a tool: an API, an MCP server, an email integration. That split is deliberate. Skills are probabilistic (they shape reasoning); tools are deterministic (they execute exactly). Keeping them separate is what makes the whole system safe to run — more on that in how to give AI agents tools safely.
FAQ
What is an AI agent skill?
An AI agent skill is a structured markdown file — typically named SKILL.md — that packages domain expertise an agent loads on demand: the process, the frameworks, the templates, and the quality checklist for one job. Instead of re-explaining how you want invoices done every time, the skill carries that knowledge permanently.
How is a skill different from a prompt?
A prompt is a one-time instruction that disappears when the conversation ends. A skill is a versioned file that persists, gets refined in production, and works across agents. Prompts are speech; skills are institutional knowledge.
Do skills only work with one AI model?
No. Because a skill is plain markdown, it is agent-agnostic — the same file works in Claude Code, OptimusOS, or any agent that can read a markdown file. That portability is the point: your knowledge library outlives any single model or platform.
How many skills does the FAST framework include?
FAST includes 300+ portable skills organized by the OSLO taxonomy — Offers, Sales, Leads, and Operations — plus a meta-skill that creates new skills, so the library is self-expanding.