What an AI Skill Is, and When to Write One

• 4 min read
Skills AI Tooling Best Practices

You end up explaining the same things over and over. How this project gets deployed. How your team writes commit messages. Which patterns the components follow. A skill is that explanation, written down once in a folder your assistant reads when it's relevant.

What it is

A skill is a folder with a SKILL.md file in it. The file has two parts: a few lines of metadata at the top, and the instructions underneath. That's the entire format. 

---
name: commit-message
description: Writes a commit message for staged changes. Use when
  the user asks for a commit message or is about to commit.
---

Read the staged diff, then write the message:

- One short line, imperative mood: "Add", "Fix", "Remove".
- Keep that line under 60 characters.
- Add a body only if the change needs explaining.
- Don't list the files changed. The diff already says that.

The description is the important half, and it's the half people rush. It's the only part your assistant sees until it decides the skill is relevant, so it has to say when to use this, not just what it is. Everything below the metadata is what gets followed once that decision is made.

The spec: Agent Skills at agentskills.io

Why bother

Because the alternative is pasting the same paragraph into a chat window every week, slightly differently each time, and getting slightly different results. A skill is written once, gets corrected when it's wrong, and stays corrected.

The neat part is how they load. Your assistant reads only the name and description of each skill at startup — enough to know one might be useful. The instructions themselves are read when a task actually matches. So twenty skills sitting on your machine cost you almost nothing until the moment one is needed.

And because it's a plain folder, it goes in git with the project. Everyone on the team gets the same version, and you can review a change to it in a pull request like any other file. The format is an open standard — it's called Agent Skills — so the same folder works across Claude Code, Codex, Cursor, VS Code, Gemini CLI and a long list of others. Worth knowing the name: it's what your own tool's documentation will file this under.

How to write one

Drop the folder into a skills directory your tool watches. Most default to .agents/skills/ in the project, though some use their own path — check yours. Keep it in the repo and commit it, and everyone on the team gets it; most tools also have a personal folder for skills you want everywhere, whatever project you're in. The folder name is the skill's name, and the two have to match. 

.agents/skills/
└── commit-message/
    ├── SKILL.md      # the instructions
    └── examples.md   # only read if the skill asks for it

Start from something you've already typed twice. Open a skill file, paste in what you'd normally explain, and tidy it into steps. Then use it — either by naming it directly, or by asking for the thing it covers and letting the description do its job. Most of the work is in the second draft, after you watch it get something wrong.

What people actually write

The useful ones are rarely clever. They're the things you'd otherwise explain to a new colleague in their first week:

  • Running the project. Install steps, the environment variables it needs, which port it comes up on, how to tell it's working. The thing your README half covers.
  • Code review. What your team looks for, in the order you look for it — so a review comes back consistent instead of whatever the assistant happened to notice.
  • Component conventions. Which patterns your UI follows, how you handle styling, what "done" means for a new component.
  • Release steps. The runbook — version bump, changelog, tag, deploy, what to check afterwards, and what to do when it goes wrong.
  • Migrations. The exact order you write, test and apply one in this codebase — the steps that aren't in any tool's documentation because they're yours.

They aren't only for code, either. A skill can carry a script or a template alongside its instructions, which is how people build ones that pull tables out of PDFs, run a standard data analysis, or produce a report in the shape their team expects. Same folder, same two files, more stuff in the directory.

Two things worth getting right

Write the description for a stranger. "Helps with deployment" tells your assistant nothing about when to reach for it. Say what the skill does and what a request for it looks like — the words someone would actually use. A skill that never fires is usually a description problem, not an instructions problem.

Keep the instructions short. Once a skill loads, it stays in the conversation, so every line you wrote is along for the rest of the ride. State what to do rather than explaining why. If you have genuine reference material — a long style guide, a table of examples — put it in a second file in the folder and point at it from SKILL.md, so it's only read when it's needed. The format's own guidance is to keep the main file under 500 lines.

Is it worth it

Write one when: you've explained the same procedure more than twice, the steps matter, and the knowledge is specific to you or your team rather than something any assistant already knows.

Don't when: it's a one-off, or it's a fact rather than a procedure. "We use PostgreSQL" belongs in your project's context file. "Here's how we run a migration" is a skill.

None of this is clever, and that's rather the point. It's a markdown file in a folder. What changes is that the explanation you'd otherwise repeat out loud becomes something you can read, correct, review, and hand to the next person who joins — or to whatever assistant you're using by then.