Skip to content
CodeAndBuild LogoCodeAndBuild

AI Coding

How to Write a Project Skill an AI Coding Agent Will Follow

Package a repeated workflow into a skill file with a clear trigger, the steps, and the files the agent should read first.

CodeAndBuild Team8 min read
  • AI Agents
  • Skills
  • Cursor
  • Workflow
On this page
  1. The file is the whole interface
  2. Steps an agent can execute
  3. Split skills the way you split functions
  4. Try the skill on a real request
  5. Store it where the next session can see it

Rules tell an assistant what is always true. A skill tells it how to do one job that comes up often: add a blog post, cut a release, triage a failing check. If you explain that job in chat every Monday, write it down once. A skill is a markdown file with a name, a description that says when to use it, and steps that point at real files. The agent can load it when the request matches, instead of reconstructing your taste from a vague prompt.

A skill that tries to be the entire engineering handbook will not be followed. Narrow the trigger. "Use this when adding a guide to lib/posts.ts" is a trigger. "Use this when writing code" is a trap. The description should contain the words a person actually types, because that is how the skill gets selected.

The file is the whole interface

Put SKILL.md in a folder named for the job. The front matter needs a name and a description. The body is the procedure. Link to the files the agent must read before it edits. Tell it what done looks like. Tell it what to do when a fact is missing, which is usually to stop and ask, not to invent a publisher id, a price, or a user.

skills/new-guide/SKILL.mdmd
---
name: new-guide
description: Add a technical guide to the Next.js blog in lib/posts.ts. Use when the user asks for a new post, guide, or article.
---

1. Read lib/posts.ts and match the existing Post fields.
2. Add the post at the top of the array. Do not delete older posts.
3. Put a new cover in public/images. Do not reuse a cover that is already on another post.
4. Keep code samples free of real API keys.
5. Stop when the slug renders. Do not deploy unless the user asked.

Steps an agent can execute

Each step should be an action with an object. "Read this file." "Edit that function." "Run this command." "Consider the architecture" is not a step. If a step depends on a fact only the user knows, say so and stop. Skills that tell the agent to guess the missing fact are how the wrong account gets an email integration.

  • Open with the files to read. Agents that edit before reading will mimic a different framework.
  • Name the verify command. A skill that ends at "save the file" leaves the broken page for the user.
  • Name the forbidden shortcut. For this blog, that includes inventing secrets and deploying from the parent folder.
  • Keep the skill updated when the file layout changes. A skill that points at a deleted path is worse than no skill.

Split skills the way you split functions

A new-guide skill should not also explain how to buy a domain. If two requests share a preamble and diverge, they are two skills with a sentence of shared context, or one skill with a branch that is still short. You should be able to read the file in a couple of minutes. If you cannot, the agent will sample it and miss the one line that mattered.

Put it in a skillLeave it out
A workflow you repeatA one-off migration you will never run again
File paths and commandsA history of why the company exists
The definition of doneEvery possible edge case written as prose
When to stop and askA prompt that says to be creative

Try the skill on a real request

After you write it, ask for the job in a fresh session without extra hints. Watch which files get opened. If the agent skips the step that says to read the post type, the step is too far down or the description did not match the way you asked. Fix the skill, do not add a longer chat preamble. The test of a skill is a session that did not need you to repeat yourself.

Review the skill like code. It can send an agent to run commands and edit files. A vague "clean up the repo" skill is permission to delete things you did not mean. Prefer skills that add or update a known path. When a skill is wrong, you will feel it as a confident edit in the wrong file. That is the signal to tighten the trigger, not to stop writing things down.

Store it where the next session can see it

A skill that lives in a chat transcript helps one afternoon. A skill in the project helps the next person and the next agent session. Keep it beside the repo conventions, and mention it in the contributor notes in one line so humans know it exists. Do not duplicate the same steps in a rule and a skill and a README paragraph that can drift. The skill owns the procedure. The README can link to it. When the procedure changes, change the skill in the same commit as the code it describes. A new-guide skill that still says posts live in a markdown folder you deleted will create that folder again. That is the failure mode to test: ask for the job after the layout change, and see whether the agent follows the file or your memory.

More guides