What are Agent Skills?

If you have used an AI coding agent for more than a week, you have probably repeated yourself. You explain your test conventions on Monday, and again on Thursday. You paste the same deployment checklist into three different sessions. You correct the same wrong assumption about your database layer over and over.

Agent Skills exist to end that loop. A skill is a small, shareable folder of instructions that an agent loads on demand, only when the task at hand calls for it. Write the guidance once, and the agent applies it every time it becomes relevant.

What a skill actually is

Strip away the terminology and a skill is a directory with one required file:

my-testing-skill/
└── SKILL.md

SKILL.md is Markdown with a small block of YAML frontmatter at the top:

---
name: testing-conventions
description: >
  Project testing conventions and patterns. Use when writing, fixing,
  or reviewing tests, or when asked about coverage requirements.
---

# Testing conventions

Tests live next to the code they cover, named `*.test.ts`.

Use the Arrange-Act-Assert structure...

That is the whole mechanism. Two frontmatter fields do the routing, and everything below is the guidance the agent reads once it decides the skill applies.

More elaborate skills add supporting files next to SKILL.md — reference documents, templates, or scripts the instructions tell the agent to run. The body can point at them, and the agent reads them only if it needs to.

The description field is the whole game

Here is the part people get wrong on their first attempt.

At rest, the agent does not hold the contents of your skills in context. It holds only each skill’s name and description — a few dozen tokens apiece. When you ask for something, it matches your request against those descriptions and pulls in the full body of whichever ones look relevant.

This is why a library of fifty skills does not cost fifty skills’ worth of context. It also means your description is not documentation for humans — it is the retrieval key. A vague one never fires:

# Too vague — the agent has nothing to match against
description: Helps with testing.

# Specific — names the triggers explicitly
description: >
  Testing conventions for this repository, including file layout, mocking
  policy, and the 80% coverage gate. Use when writing new tests, fixing
  failing tests, or reviewing test coverage.

Write the description as a list of the situations in which the skill should activate. That is the single highest-leverage thing you can do to make a skill work.

Where skills live

Two locations, and the distinction matters:

Location	Scope	Use it for
~/.claude/skills/	Every project you work on	Your personal habits, preferred libraries, review style
.claude/skills/	The repository it sits in	Team conventions, architecture rules, deployment steps

Project-scoped skills are the interesting ones for teams. Commit them, and every engineer’s agent — and every new hire’s, on day one — picks up the same conventions automatically. The knowledge stops living in one senior developer’s head.

What makes a skill worth installing

Having catalogued several hundred public skills, a few patterns separate the useful from the abandoned.

Good skills are narrow. A skill called python that tries to cover the whole language will fire constantly and rarely help. A skill called pytest-fixtures fires exactly when it should.

Good skills encode judgement, not syntax. The agent already knows the syntax. What it does not know is that your team banned a particular pattern after an incident, or that a specific library version has a subtle bug. That context is what earns its place.

Good skills declare a licence. Roughly a third of the public skills we index do not, which means you have no clear legal footing to adapt or redistribute them. It is worth checking before you build on one.

Good skills are maintained. A skill written against an API that changed a year ago is worse than no skill, because it confidently supplies wrong information.

Finding skills that already exist

Before writing your own, it is worth checking whether someone has solved it. The full catalog indexes public, open-source skills from GitHub, sorted into categories — testing, security, DevOps, documentation, and more.

If you want a shortlist rather than a full listing, the curated collections rank the strongest entries per topic: the best workflow skills, the best testing skills, or what is gaining traction now.

Every listing links straight back to the source repository, because you should read a skill before you install it. It is a set of instructions you are handing to something that writes code on your behalf.

When to write your own instead

Reach for a custom skill when the knowledge is genuinely yours:

• Conventions specific to your codebase that no public skill could know
• A workflow with company-specific steps — how releases are cut, who signs off
• Hard-won corrections, the things you find yourself re-explaining
• Domain knowledge the agent has no way to infer from the code

Start smaller than feels natural. One SKILL.md, one clear description, twenty lines of guidance. Use it for a week, notice where the agent still gets it wrong, and add only what that reveals. Skills that were speculatively comprehensive on day one tend to be the ones nobody maintains by month three.

The short version

A skill is instructions in a folder. The description decides when it loads. The body tells the agent what to do. Personal skills go in your home directory, team skills go in the repository.

It is a deliberately small idea, and that is why it works: no runtime, no API, no service to keep alive — just knowledge, written down once, in a place your agent knows to look.