Agent Skills · Learn · The open SKILL.md standard
Concepts

Agent skills vs rules files

Both are markdown that steers your agent — but they're used differently. A skill is on-demand expertise that loads when a task matches it. A rules file is an always-on set of project conventions the agent reads every time.

Rules files: always-on project context

Most agents read a project-level conventions file on every request — .cursorrules / .cursor/rules/ (Cursor), AGENTS.md (Codex, Amp and others), .clinerules/ (Cline), .windsurf/rules/ (Windsurf), .goosehints (Goose). It's where you put standing facts: "this repo uses pnpm", "always write tests in Vitest", "our API base is …". It's loaded whether or not it's relevant to the current task.

Skills: on-demand expertise

A skill is a SKILL.md the agent loads only when the task matches its description — that's progressive disclosure. You can install dozens of skills (PDF handling, a specific API's conventions, a release checklist) without any of them weighing on unrelated work. The right one shows up exactly when it's needed.

When to use which

A rule that only matters for 5% of tasks is wasted context the other 95% of the time — that's a skill. A skill you want active on every single request is really a rule.

They overlap — and that's fine

On agents without a native skill loader, the two converge: you install a skill by dropping its body into the rules directory (see the install guide), so it behaves like an always-on rule. Native-loader agents keep the distinction sharp. Either way, the open SKILL.md format means the same content is portable — see which agents support skills and how each loads them.

Skills vs rules files — answered

What's the difference between an agent skill and a rules file?
A rules file (.cursorrules, AGENTS.md, .clinerules) is always-on project context the agent reads every request. A skill (SKILL.md) is on-demand expertise loaded only when a task matches its description. Rules = standing conventions; skills = occasional, specialized know-how.
Is AGENTS.md the same as a skill?
No. AGENTS.md is a project-level rules/instructions file read on every request. A skill is a SKILL.md loaded on demand. That said, on agents without a native skill loader you install a skill by adding its body to a rules file, so the two can overlap in practice.
Should I use a skill or a rule for my project conventions?
Use a rules file for things true all the time (stack, conventions). Use a skill for specialized expertise needed only on some tasks. If something only matters occasionally, a skill keeps it out of context until it's relevant.