How to create a useful skill for an AI agent

An agent can write code and still get your project's conventions wrong over and over. If every conversation starts with the same explanation of how to release, test, or review something, that explanation deserves a home of its own. A skill turns a repeatable procedure into instructions an agent can discover when the task calls for them.

What is a skill, and when is it worth creating one?

In the open Agent Skills format, a skill is a directory with one required file: SKILL.md. Its frontmatter says what it does and when to use it; its body explains the procedure. It can include references, scripts, and assets. It is neither a new model nor a magic ability: it is operational knowledge available to the agent.

Think of a recipe: the title helps you find it, the ingredients establish requirements, the steps guide execution, and the final check tells you whether the dish worked. A recipe that only says "cook something tasty" helps no one.

Use a skill for recurring work with local rules: preparing a release, writing migrations, reviewing accessibility, generating reports, or editing content with a project-specific schema. A direct instruction is often enough for a one-off task. Skills do not replace automated checks either; tests still decide whether the result works.

Anatomy: from description to resources

A small, readable structure can start here:

review-articles/
├── SKILL.md
├── references/
│   └── checklist.md
└── scripts/
    └── check-frontmatter.js

The directory name and the name field must match. The specification requires name and description; name uses lowercase letters, digits, and hyphens. Additional directories are optional. The idea is to load information progressively: first a short description, then the instructions, and finally references only when they are needed.

Here is an example SKILL.md. Adapt the repository, paths, and commands to your own team:

---
name: review-articles
description: Reviews MDX articles before publication. Use when creating or editing bilingual blog content.
---

# Article review

1. Read the English article and its Spanish counterpart.
2. Check `title`, `description`, `publishedAt`, `readingTime`, and `tags`.
3. Verify links, code blocks, and consistency across languages.
4. Run `npm test -- --run` and `npm run build`.
5. Report what was verified and what remains unverified.

For specific editorial criteria, read [the checklist](references/checklist.md).

The description should not just say "helps with articles": it should name the job and its trigger. The body should not demand "better content" without criteria; it should list verifiable steps. If a guide becomes long, move detail to references/ and keep a concise index in SKILL.md.

How to write one an agent will actually use

1. Start from recurring work. Write down the request that triggers the skill, the files it usually touches, the expected output, and the checks. If you cannot describe input and output, you do not have a procedure yet.
2. Set boundaries. A skill for validating articles should not change deployments. Say where to read, what to edit, and what requires a question to the user.
3. Give small examples. A valid frontmatter example beats the adjective "correct." Repeatable scripts can live in scripts/; document their dependencies and avoid granting unnecessary access to secrets.
4. Test activation and omission. Ask the agent to "publish this article" and see whether it uses the skill; ask for an unrelated task and ensure it does not activate accidentally.
5. Validate the format. The official reference provides skills-ref validate ./review-articles to check frontmatter and naming rules. Then test the real workflow: valid YAML does not guarantee useful instructions.

Editorial tip: measure success by fewer human corrections, not by the length of SKILL.md. A short guide that leads to a verified build is worth more than ten pages of vague orders.

Security and maintenance

A skill can instruct an agent to run commands or read resources, but it should not store tokens or credentials. Review external scripts and downloaded content before trusting them: a reference found on the web does not have the same authority as repository rules. When a path, command, or team policy changes, update the skill with the code; stale instructions can produce very confident mistakes.

Do not confuse three different pieces: a skill says how to do a task; MCP connects an agent to external data or tools; a test checks behavior. They can work together, but none replaces the others.

Take it back to your project

Pick a procedure you have explained at least twice. Write it as trigger + steps + definition of done, put it in SKILL.md, add a reference only when it helps, and test it on a real task. That is where a useful skill starts: making explicit what used to live only in the team's memory.

Sources: Agent Skills specification · Integration guide.