You can tell a coding agent what to do every single time you need it. Or you can write the steps down once and let the agent follow them.
An agent skill does exactly that. You write a procedure in a markdown file, put the file in a folder inside your project, and the agent runs it the same way on Monday and on Friday. No code, nothing to install. From here on, this page calls it a skill for short.
The examples here use pi, a coding agent you run in your terminal. The same shape carries over to Claude Code, Hermes Agent, and most other agent harnesses, so nothing you learn here is specific to pi.
By the end you will have written a working skill, learned the one field that decides whether it ever runs, and run it against a real project.
Write the procedure once. Reuse it every time.
Your request helps the agent find the right skill. The skill tells it exactly what to do next.
“What did we agree to do after the meeting?”
- 1Read the meeting notes
- 2Pull out every action item
- 3Flag missing owners or dates
A complete action-item list, in the same shape every time.
Three ways to steer an agent
An instruction can live in three places. Each is plain text in your project, but the agent reads it at a different moment.
Project rules live in AGENTS.md and apply on every turn. A slash command saves words you would otherwise type by hand. A skill gives the agent an ordered procedure it can choose when the description matches your request.
Use the panel below to compare where each one lives and what makes it run.
Pick what you are handing the agent
Select one to see where it lives and when it fires.
Standing rules for the whole project, including coding conventions, writing preferences, and things the agent should never touch. The agent re-reads them on every turn, so keep them short.
- On disk
- AGENTS.md
- When it fires
- Every turn, whether you asked for it or not
Illustrative sessions. Exact wording depends on your agent and model.
When to use a skill
Reach for a skill when the job has an order to it, when there are specific things to look for, and when you want the same answer whoever runs it. When all three apply at once, write the skill.
Turning meeting notes into action items is a skill. So is checking a draft against your writing guidelines, or assembling the same weekly summary from the same three places every Monday. Asking what a word means is not a skill, it is just a question. A rule like "never edit the files in notes/" is not a skill either, it belongs in project rules, because it applies to everything you do rather than to one job.
One quick test. Would you write these steps down for someone covering your work while you are away? If yes, it is a skill.
What a skill is made of
A skill is a folder with a single file in it. The file is always called SKILL.md.
The folder lives inside your project, under .pi/skills/, and whatever you name the folder is what the skill is called. A skill named action-items sits at .pi/skills/action-items/SKILL.md. The leading dot in .pi just means your computer normally hides that folder from view, which is why you may not have noticed one before.
SKILL.md is a plain text file. There is nothing to install and nothing to compile. You can write it in any text editor, or you can ask the agent to write it for you, which is what you will do later in this tutorial.
The file has two parts. At the top, fenced above and below by a line of three dashes, is a small settings block. Everything after it is ordinary writing.
---
name: action-items
description: Pulls the action items out of the meeting notes in notes/ and flags any that are missing an owner or a date. Use when asked what was agreed or what is still outstanding.
---
# Action items
## Steps
1. Read every file in notes/.
2. List every action item you find, with who owns it and when it is due.
3. Flag anything missing an owner or a date, then write the list to action-items.md.
Agent documentation calls that settings block frontmatter, and writes it in a format called YAML. You do not need to learn YAML. A label, a colon, a space, then the value. That is the whole of it here.
Now read the example back one piece at a time.
name is what the skill is called. It has to match the folder name, and it is what you type when you want to run the skill by hand.
description is a sentence or two saying what the skill does and when to use it. This field alone decides whether the agent ever reaches for the skill on its own, and people get it wrong more than any other. The whole next section is about it.
The steps are the procedure, in order. Write them the way you would write them for a new teammate on their first day. There is no syntax to learn and no keywords to memorize. If a person could follow your steps, so can the agent.
Three parts, and only three. Everything else in the file is yours to use however you like.
Description quality
The description does far more work than it looks. When the agent decides whether a skill fits what you just asked, it reads the description and nothing else. Say what the skill does and when to use it. A title will not do.
Same steps, different description
Toggle between them and read what the agent does with each.
--- name: action-items description: Action items ---
What did we say we would do after the last meeting?
The agent opens the notes and improvises an answer. Your skill never enters the picture, because "Action items" does not tell it anything about when to use it.
Illustrative. Skill selection also depends on the model and the rest of your prompt.
Two sentences is usually enough. The first says what the skill does. The second says when to reach for it. Write the second one using the words you would actually say out loud when you want this job done, because those are the words the agent has to match against.
There is a failure worse than a vague description, and it is much harder to spot. The exercise below shows a skill whose frontmatter is missing one of the two required fields. Read the file, decide what happens when you ask the agent for that job, and then check your answer. Guess even if you are unsure. The explanation afterwards teaches the real lesson.
This skill has one problem. Which one?
Pick what happens and why, then check. Watch the status line change as you answer.
Loading and running
Two commands cover the whole loop. /reload makes the agent re-scan .pi/ so a file you just wrote becomes available. /skill:<name> runs a skill directly by name.
That direct call matters more than it sounds. Agents do not always reach for a skill on their own, so calling one by name lets you separate a loading problem from a matching problem.
Write, reload, run, read
Three moments worth noticing in one session.
- 1The agent only sees files under .pi/ after a reload. Skip it and a brand new skill silently does nothing, which trips up more people than any other step.
- 2Always test a skill by calling it by name. If it works here but not from a plain request, your description is the problem.
- 3The steps decided this output shape. Change step 3 and every future run changes with it.
Simplified. Exact wording and folder names depend on your project and agent version.
Now a couple of situations you will actually hit.
You asked what was agreed and nothing happened
Pick what you would try first, and why. Two situations.
Write it for real
The examples above are simulations you can repeat as often as you like. The terminal below opens a real pi session on a real machine, with the team's meeting notes already in it.
Start with the prompt beside step 1. It gives pi the file path, frontmatter, and procedure, and you can edit the wording before you send it. After you run the skill, the checks below the terminal inspect the real files in your sandbox and tell you what still needs work.
Write the skill and run it
A real pi terminal, running right here, with two meetings' worth of notes already in it.
- 1Copy this starter prompt into pi. You can edit it first if you want.
- 2Reload so pi picks the new file up.
- 3Run the skill by name and let it finish.
The starter project includes AGENTS.md and deliberately loose meeting notes, giving your skill realistic gaps to catch. These practice checks do not affect course progress or create a certificate.
What to remember
A skill is a folder with a SKILL.md in it. The description decides whether the agent ever reaches for it, so write what it does and when to use it. Call it by name to test it, because a direct call tells you whether the file loaded and a plain request tells you whether the description matches.
Once you have written one, the same three parts carry over to Claude Code, Hermes Agent, and anything else that reads markdown skills.
Where to go next
Keep building with a structured course and a project that grows as you learn.
Introduction to Pi
Build project rules, slash commands, and reusable skills, then bring all three together in a capstone.
30 Days of Hermes Agent
Practice the same reusable-skill pattern with a different coding agent and see what carries over.