What Are Agent Skills? The Complete Guide

What are agent skills?

Agent skills are reusable instruction packs that teach an AI coding agent a workflow it doesn't know out of the box. Concretely, a skill is a folder containing a SKILL.mdfile: plain markdown with a small YAML frontmatter block (a name and a description) followed by step-by-step instructions. Drop that folder into your agent's skills directory and the agent discovers it automatically. When a task matches the skill's description, the agent reads the full instructions and follows them.

That's the whole mechanism. No plugin API, no server, no SDK. Because a skill is just markdown, the same skill works across Claude Code, Codex, GitHub Copilot, and Antigravity; only the directory it lives in changes. That portability is why an ecosystem formed around them so quickly: this registry alone indexes 8,600+ open-source skills, covering everything from code review checklists and security audits to PDF generation and commit message conventions.

The easiest way to think about a skill: it's the onboarding document you would write for a new teammate, except the teammate is your coding agent, and onboarding takes one command.

How skills differ from MCP servers and prompts

Skills sit between two things you probably already use: ad-hoc prompts and MCP servers. Each solves a different problem.

• Prompts are ephemeral; skills persist. A great prompt lives in one chat session and disappears. A skill writes that same expertise down in a file that is version-controlled, shareable, and loaded automatically in every future session. If you find yourself re-explaining the same workflow to your agent every week, that workflow should be a skill.
• MCP servers add capabilities; skills add knowledge. An MCP (Model Context Protocol) server is a running process that exposes tools and data to an agent: query a database, call an API, control a browser. A skill runs nothing. It is pure instructions that change how the agent behaves with the tools it already has. There is no process to install, no credentials to configure, and no runtime cost.
• They compose. A skill can teach an agent how to use an MCP server well — which tools to call, in what order, and what good output looks like. Capability and judgment are different layers, and mature setups use both.

A useful rule of thumb: if the agent needs access to something new, you want an MCP server. If the agent needs to behave differently with what it already has, you want a skill.

Anatomy of a skill

Every skill centers on a SKILL.md file. The frontmatter carries two required fields:

---
name: code-reviewer
description: Reviews diffs for correctness, security, and style.
  Use when the user asks for a code review or before merging.
---

# Code Reviewer

When asked to review code, work through the diff file by file:

1. Check error handling on every new code path...
2. Flag any query built by string concatenation...

The descriptionis the most important line in the file. Agents keep every installed skill's name and description in context and use them to decide when to load the full instructions, a pattern often called progressive disclosure. A vague description means the skill fires at the wrong times or never fires at all. The markdown body below the frontmatter holds the actual workflow: checklists, commands, conventions, and examples.

Beyond SKILL.md, a skill folder can also ship:

• References — extra markdown files with detailed documentation the agent reads only when needed, keeping the main file lean.
• Scripts — executable helpers (shell, Python, Node) the agent can run instead of re-deriving logic every time.
• Templates and assets — boilerplate files the skill copies or fills in.

Simple skills are a single file. The best complex ones read like a well-organized runbook: a short SKILL.md that routes the agent to deeper references as the task demands.

How installation works across the four clients

Installing a skill means copying its folder into the directory your client scans. Each client supports two scopes: a project install (the skill applies to one repository, and can be committed so your whole team gets it) and a global install (the skill applies to everything you work on). The four clients this registry supports:

Since every skill in this registry lives in a public GitHub repository, install commands use degit, which copies a single folder out of a repo without cloning its history:

npx degit <owner>/<repo>/<path-to-skill> .claude/skills/<skill-slug>

You never have to assemble that command yourself. Every skill page generates the exact one-liner for each client and scope; you pick your client, copy, and run it. Installation is a file copy, so "uninstalling" is just deleting the folder.

How to evaluate a good skill

Skill quality varies the way README quality varies. Before installing, check five things:

• A sharp description.The frontmatter should say exactly when the skill applies ("use when reviewing a pull request"), not just what topic it covers. This is what makes the skill trigger reliably.
• Focused scope.One skill, one workflow. A skill that claims to handle testing, deployment, and documentation at once will do all three poorly and crowd your agent's context.
• Concrete instructions.Open the source and read the SKILL.md. Good skills contain commands, checklists, and worked examples. Weak ones contain motivational filler an agent can't act on.
• A live source repo. Each listing links to its GitHub source. A maintained repo with recent commits beats an abandoned one.
• Popularity as a tiebreaker. Install and view counts are a useful signal of what the community keeps reaching for. The leaderboard ranks the most installed and most viewed skills across the registry.

One habit worth keeping: read a skill before you install it, the same way you would skim a shell script before piping it to bash. A skill is a set of instructions your agent will follow with your permissions. The source is always one click away, so there is no reason to install blind.

How to browse this registry

The registry indexes 8,600+ skills, so the fastest path depends on what you already know:

• Search the full catalog on the skills index if you have a task in mind — results filter as you type.
• Browse by categorywhen you're exploring. Skills are organized into nine categories; Coding is the deepest, and Security and Writing are good first stops for non-feature work like audits and documentation.
• Start from your client if you want setup details: each client page, like the one for Claude Code, covers that client's directory conventions and FAQs alongside its catalog.

However you get there, every skill page shows the description, the full SKILL.md, the source link, and a copy-paste install command for your client. Find one that matches a workflow you repeat, install it, and your agent knows something new in under a minute.