How to Create an Agent Skill (SKILL.md) — Step by Step

What you are actually building

Agent Skills are a lightweight, open format: a folder containing a SKILL.md file with metadata and instructions, optionally bundled with scripts, reference documents and templates. The agentskills.io spec keeps the required surface tiny on purpose.

The file has two parts. Frontmatter carries the skill’s name and description. The body carries the instructions: the steps an expert would follow, written out for the agent to load when a task matches.

Step 1 — pick a workflow worth teaching

The best first skill is something you already do repeatedly and can explain. Test your candidate against three questions:

• Does it repeat — weekly or more often — or does it cost real money when it is done badly?
• Can you describe the steps so precisely that a competent new colleague could follow them?
• Can you say what “done” looks like — the exact output you expect?
• Good first candidates: an SEO audit, a stock screen, a code-review checklist, a client report, a launch checklist.

Step 2 — write the SKILL.md

Create a folder named after your skill and put a SKILL.md directly inside it. The file has a small block of frontmatter — the skill’s name plus a one-line description — and then the instructions in plain Markdown.

Write the instructions the way you would brief a smart colleague on their first day: numbered steps, the order that matters, the checks before finishing, and one or two worked examples of good output. Keep scripts and long references in subfolders next to the SKILL.md and point to them from the instructions.

Keep the skill focused on a single job. If you find yourself writing “also, optionally…”, that is usually a second skill.

Step 3 — make the description a trigger

This is the part beginners underestimate. Agents use progressive disclosure: at startup they load only each skill’s name and description, and they activate a skill only when a task matches that description. A vague description means your skill never fires.

Write the description as “what it does + when to use it”, with the words a user would actually say. For example, a skill that audits pages should say it audits a page for SEO issues and should be used when the user asks to check or improve a page’s search performance — not “a comprehensive solution for digital marketing excellence”.

Step 4 — test it like a user

Load the skill into a skills-compatible agent — Claude Code, Cursor, Codex CLI, VS Code and others all read the same format — then run real tasks against it, phrased the way you would naturally ask:

• Does it activate on the right requests — and stay quiet on unrelated ones?
• Does the output match your “done” definition on the first run?
• Where does it improvise? Add the missing instruction or example there.
• Run the two or three hardest cases you know, not just the easy one.

Step 5 — publish it, and keep 80%

A working skill has two ways to pay off. Use it yourself, or sell it. On Capafy AI, publishing takes three steps: upload the Skill package (SKILL.md plus any references and scripts), write the Agent Card describing what it does and who it is for, and pass the publisher check to go live.

Publishers keep 80% of every sale — Capafy handles payments and the runtime that runs your agent online, so buyers can use it in the browser with nothing to install. A one-time US$0.99 certification fee applies when you first publish.

Best practices that separate great skills from good ones

Patterns that show up in every skill people actually keep using:

• One job per skill, with a description that reads like the request it answers.
• Concrete verbs and ordered steps — “extract, then compare, then rank”, not “analyse thoroughly”.
• Handle the edges: say what to do when data is missing or a check fails.
• Keep secrets out of the skill — reference credentials, never paste them.
• Version it, and update the instructions when you find a failure mode.