What Are Agent Skills? A Practical Guide

Agent skills are reusable, versioned instructions your AI agents follow — a way to capture "how we do X" once so every agent applies it the same way. This guide covers what agent skills are, how they differ from one-off prompts and from agent memory, and how to manage them across tools like Claude, Cursor, and ChatGPT.

What are agent skills?

An agent skill is a named, self-contained set of instructions, written in Markdown, that an AI agent can load and follow when it's relevant. Think of it as the difference between explaining a task from scratch every time and handing someone a checklist they already know how to use.

Anthropic introduced Agent Skills in 2025 as a structured way to package this kind of know-how. A skill isn't a model, a plugin, or code you have to run — it's plain text that describes a procedure: how to review a pull request, how to write in your company's voice, how to cut a release. Because it's just Markdown, anyone on the team can read it, edit it, and reason about what the agent will do.

Agent skills vs. one-off prompts vs. agent memory

Three things get confused here, so it's worth drawing the lines.

• A one-off prompt is ephemeral. You type it, you get a result, and the instruction is gone. If it was good, you either paste it again next time or lose it.
• A skill is a prompt you decided to keep. It has a name, a clear purpose, and a version. It's meant to be reused deliberately and improved over time — a function instead of a copy-pasted snippet.
• Agent memory is different again: it's the context an agent accumulates about you — facts, preferences, past decisions — usually passively. Memory answers "what does the agent know about my situation?" Skills answer "what procedure should the agent follow?" You want both, for different reasons. We go deeper in agent skills vs. agent memory.

The practical upshot: don't bury a repeatable procedure in memory and hope it resurfaces, and don't retype it as a prompt every day. Make it a skill.

The SKILL.md pattern

Agent Skills use a simple, portable convention. A skill is a folder containing a SKILL.md file: YAML frontmatter with a name and a description, followed by the instructions in Markdown. The folder can hold supporting files too — scripts, examples, or reference docs the skill points to.

---
name: code-review
description: Review a diff for correctness, security, and style. Use when asked to review code or a pull request.
---

# Code review

When reviewing a change:

- Start with correctness — does it do what the PR claims?
- Flag security issues: injection, missing auth checks, secrets in code.
- Confirm new logic has tests.
- Keep style comments short and last.

Reply with a one-line summary, then findings grouped by severity.

The description is doing real work here: it's how the agent decides when the skill applies.

How agents discover and load skills

Skills are built around progressive disclosure. An agent doesn't read every skill in full all the time — that would blow up its context window. Instead it sees the lightweight metadata (the name and description) for each available skill, and only loads the full body when a task matches. Ask an agent to "review this PR" and it recognizes the code-review skill from its description, pulls in the instructions, and follows them.

That's why the description matters as much as the body. A vague description means the skill never fires; a sharp one ("use when asked to review code or a pull request") means it fires exactly when it should.

Concrete examples

A few skills most teams end up wanting:

• Code review — the example above. It encodes what your team actually checks for, so reviews stay consistent no matter who (or which agent) runs them.
• Brand voice — how your product writes: tone, words you avoid, how you refer to features. Load it before drafting docs, release notes, or marketing copy and everything sounds like one company.
• Release notes — the exact format you ship: which sections, how you describe fixes versus features, where the changelog lives. It turns a fuzzy chore into a repeatable one.

Each is small, single-purpose, and reusable — a library, not a monolith.

Sharing and versioning skills across tools

A skill is only as useful as it is reachable. If your code-review skill lives on one laptop, the rest of the team writes their own slightly different version — the exact drift skills are supposed to prevent.

Two things fix that. First, version control: track every change so you can review edits, roll back, and know which version an agent used. A skill you can't diff is a skill you can't trust at scale — more on that in version control for prompts and skills. Second, shared access across tools: because skills are just Markdown, the same one can serve a teammate on Claude, another on Cursor, and a third on ChatGPT — provided there's a neutral place all of them can read. In practice that means exposing the library over MCP (Model Context Protocol), the open standard most agents adopted through 2025, so any client can fetch the current skill on demand.

That's the gap Roget fills: a shared library where you store skills once, version every change, share them privately with your team, and connect any agent over MCP so they all read the same source of truth.

Start small — turn your three most-repeated instructions into skills this week, then browse the Roget directory to see how others structure theirs.