What are agent skills? SKILL.md, explained

An agent skill is a folder containing a SKILL.md file: Markdown instructions that teach an AI agent how to do something specific. Unlike a system prompt, which is always in the agent’s context, a skill loads on demand — the agent reads a one-line description of each available skill, and pulls in the full instructions only when the task at hand matches.

The format came out of Anthropic’s work on Claude Code and spread fast: Cursor reads skills from .cursor/skills/, most major coding agents now support the same layout, and directories like skills.sh list thousands of installable ones. The reason it caught on is the economics: an agent can know about a hundred skills for the cost of a hundred sentences, and only pay the context cost of the one it actually needs.

The anatomy

A minimal skill is one file:

---
name: theme-design
description: Design conventions for this theme. Use when creating or editing UI.
---

# Design conventions

## Colors
Only use tokens from src/styles/colors.css. Never use raw Tailwind
palette colors (no blue-600, no gray-100) and never invent hex values.

## Spacing
Sections use mt-24 between them; inside a section, mt-8 rhythm.
...

The frontmatter matters more than it looks. The description is the only part the agent sees before deciding whether to load the skill, so it has to say both what this is and when to use it. A vague description means the skill never fires; an overly broad one means it fires when it shouldn’t.

Beyond the single file, a skill folder can carry references: extra Markdown files, templates, scripts. The agent loads those progressively too, following links from SKILL.md only when needed. That’s the whole trick of the format — knowledge organized so that attention is spent just-in-time.

Skills vs rules vs prompts

The three context layers get conflated, but they answer different questions:

• Rules (like Cursor’s .cursor/rules/) are conventions, always or conditionally attached: “use the @/ alias”, “don’t add dependencies”. Small, constant, enforced everywhere they apply.
• Skills are capabilities, loaded when relevant: how to build a page in this design system, how to release this package, how to write a migration. Bigger, procedural, occasional.
• Prompts are the task itself: “add a careers page”. If your prompts keep containing conventions or procedures, that content is trying to become a rule or a skill.

A useful test: if you’d want it every single edit, it’s a rule. If you’d want it for this kind of task, it’s a skill. If you’d only say it once, it’s a prompt.

What makes a skill good

Having written one for every theme in the Lexington catalog, the qualities that separate skills that work from skills that decorate:

1. Extracted, not aspirational. The skill should describe what the code actually does. Agents can see the code; a skill that contradicts it just creates confusion.
2. Constraints over adjectives. “Never use a raw palette color” changes output. “Keep it elegant” does not. Every line should be checkable.
3. Scoped tight. One skill, one competence. A skill that covers design and deployment and testing fires wrong and reads long.
4. A precise description line. It’s the skill’s advertisement to the agent. Write it last, once you know exactly what the skill covers.

And before you install anyone else’s: read the whole file, including anything it references. A skill is instructions your agent will follow with your permissions — treat it like a dependency, because it is one.

Every Lexington theme ships a design skill extracted from that theme’s real code; I wrote about how those are built in the design skill that keeps AI pages on-brand. The full extraction method, with a fill-in template, is chapter 2 of Making Your Codebase AI-Ready.