TIPS & TRICKS · AGENTS · SKILLS

Agent Skills for Development: When to Make One

A skill is a packaged set of instructions an agent loads when a task calls for it. What goes in one, when it is worth making, and a worked example.

3 Nov 2026 · 5 min read

If you find yourself pasting the same paragraph of instructions into a coding agent every week, such as “when you add a migration, also update the schema file, run the generator, and check the rollback”, you have found a skill waiting to be written.

What a skill is

A skill is a small, packaged set of instructions, and optionally scripts and reference files, that an agent loads when the task in front of it calls for it. Most agent tools that support skills use the same shape: a folder with a main Markdown file that starts with a short name and a one-line description, followed by the instructions.

The description is what makes it work. The agent sees only the names and descriptions of available skills at first, which costs very little context. When a task matches a description, it loads the full instructions. So you can have dozens of skills without filling the context with all of them.

Compare that with the alternatives:

• Project instructions file (like CLAUDE.md or an AGENTS.md): loaded on every task. Great for rules that always apply, wasteful for a procedure you need once a week.
• Pasting instructions by hand: works, but you forget steps, and every teammate pastes a slightly different version.
• A script: perfect when the steps never vary. A skill can call scripts, and adds the judgment around them.

When a skill is worth making

Make a skill when all three are true:

1. The task repeats. Weekly or more, or by more than one person.
2. There is a right way that is not obvious from the code. Steps in a specific order, a checklist, a house convention, a tool to run.
3. It needs some judgment. If every step is mechanical, write a script instead.

Good candidates: adding a new page that must follow your SEO rules; writing a database migration; preparing a release; reviewing a pull request against your checklist; adding a new problem or episode in a content-heavy repo.

Poor candidates: one-off tasks, things the agent already does well without help, and rules that apply to every task (those belong in the project instructions file).

What goes in a good skill

Keep it short and concrete. A useful outline:

• Name and description. The description should say when to use it, in the words a task would use: “Use when adding or changing a database table or migration.”
• The steps, in order. Numbered, each one checkable.
• The rules. The house conventions and the mistakes people make.
• How to verify. The commands to run and what a pass looks like.
• Pointers, not copies. Link to the reference files in the repo rather than pasting them, so the skill does not go stale when the code changes.

Aim for something a new teammate could follow. If it is longer than a page or two, split it, or move detail into reference files the skill points to.

A worked example

Say your team adds API endpoints often, and they keep missing the same things. A skill might look like this:

---
name: add-api-endpoint
description: Use when adding a new HTTP API route under src/pages/api.
---

# Adding an API endpoint

1. Create `src/pages/api/<name>.ts` with `export const prerender = false`.
2. Validate the request body with the helpers in `src/lib/server/validate.ts`.
   Reject unknown fields. Return 400 with a short message on bad input.
3. Check the session first. Signed-out requests get 401.
4. Rate-limit writes with the existing `limit()` helper.
5. Add tests in `tests/api/<name>.test.ts`: happy path, bad input,
   signed out, and rate limited.
6. Run `npm test` and `npm run build`. Both must pass.

Rules: never log request bodies (they can hold personal data);
return JSON errors as { "error": "..." }; no new dependencies.

Now “add an endpoint that saves a user’s theme” produces an endpoint with validation, auth, rate limiting and four tests, every time, without anyone remembering to ask.

Grow skills from real mistakes

The best skills are not designed up front. They are written after the third time something goes wrong. When you correct an agent and think “I have said this before”, add the correction to the relevant skill. Over a few weeks, the skill turns into your team’s real checklist, written in the order things actually break.

Review skills now and then. Delete steps that no longer apply, and update paths when code moves. An out-of-date skill is worse than none, because the agent will follow it confidently.

Keep secrets out

Skills are usually committed to the repo and shared. Never put keys, passwords or private URLs in one. Point to environment variables by name instead: “the API base URL is in API_BASE_URL”.

Takeaway: a skill is a procedure the agent loads only when the task matches its description. Make one when a task repeats, has a non-obvious right way, and needs judgment. Keep it short, numbered and verifiable, and grow it from the corrections you keep repeating.