How to Create Your Own AI Agent Skill from Scratch

You create a skill by writing one file. Make a folder, put a SKILL.md inside it with a short description of what the skill does and when to use it, then write the instructions in plain markdown. Test it with real requests, fix what goes wrong, and the skill is ready to install or share.

A skill is not a program. It is a playbook your AI assistant reads before starting a task: the steps to follow, the format to produce, and the rules to respect. If you repeat the same kind of task every week and keep re-explaining how you want it done, that explanation is a skill waiting to be written down.

Step 1: Pick one narrow, repeatable task

Start small. One skill should do one job.

• Good: turn meeting notes into a summary with decisions and action items.
• Good: rewrite a product description in your shop's tone of voice.
• Too big: run my whole marketing department.

Narrow skills trigger at the right moment and produce consistent results. Broad skills fire at the wrong times and follow none of their instructions well. You can always write a second skill later.

Step 2: Create the folder

Create a folder named in lowercase letters with hyphens, like meeting-notes-summary. The folder name matters: it must match the name you declare inside the file, and it becomes the skill's identity wherever you install it.

Inside the folder, create one file: SKILL.md. That single file is a complete, working skill. Everything else is optional.

Step 3: Write the frontmatter

SKILL.md starts with a small block of YAML between two --- lines. It looks like this:

--- name: meeting-notes-summary description: Turns rough meeting notes into a clean summary with decisions and action items. Use when the user pastes meeting notes or a transcript and asks for a summary or recap. ---

Two fields do the work:

• name — must match the folder name exactly.
• description — says what the skill does and when to use it.

The description is the most important line in the file. Your assistant does not read the whole skill in advance; it scans descriptions and loads a skill only when a request matches. A description that only says what the skill does ("Summarizes meeting notes") triggers weakly. One that adds the trigger ("Use when the user pastes meeting notes…") fires reliably. Anthropic's Agent Skills documentation describes this matching in detail.

Step 4: Write the instructions

Below the frontmatter, write plain markdown instructions for the task itself. Cover four things:

1. Steps — the exact sequence to follow, in order.
2. Input — what the user will provide, and what to do if part of it is missing.
3. Output format — the shape of the result, with a small example if the format matters.
4. Rules — the lines not to cross: tone, length, things never to invent, facts never to change.

Write it the way you would brief a careful new colleague. Short sentences, no filler. Every instruction you would otherwise repeat in chat belongs here.

Step 5: Add supporting files only if you need them

As a skill grows, you can add three optional folders:

• scripts/ — small programs the assistant runs for exact, repeatable work, like renaming files or converting formats.
• references/ — documents to consult, such as your style guide, price list, or product catalog.
• assets/ — templates and examples of finished output.

This structure works because of progressive disclosure. The assistant always loads only the short metadata — name and description, roughly 100 tokens. It loads the full SKILL.md only when the skill triggers, and it opens scripts and reference files only when the instructions call for them. So keep SKILL.md itself lean, ideally under about 5,000 tokens, and push the detail into reference files.

Step 6: Write down the gotchas

The first versions of any skill fail in predictable places. When something goes wrong, do not just fix the output — add the lesson to the file as an explicit warning. A short "Watch out" list at the end of SKILL.md works well:

• Never invent a decision that is not in the notes. If it is unclear, mark it as unclear.
• Keep names exactly as written in the notes, even if a spelling looks wrong.

These gotchas are where a homemade skill quietly beats a generic prompt. They are your experience, written down once and applied every time.

Step 7: Test with real requests, then iterate

Install the skill and use it on real work, not toy examples. Watch for three things: does it trigger when it should, does it stay quiet when it should, and does the output follow your format? Each failure points at a line to fix — usually the description or one missing rule. Update the file and test again. Most useful skills are right by the third or fourth round.

Step 8: Package and install it

To share the skill or move it between tools, compress the skill folder into a ZIP — the folder itself, not its contents scattered loose. In Claude, upload the ZIP under Customize → Skills, switch it on, and test it. For Claude Code and other tools that read local folders, drop the folder into ~/.claude/skills/ and restart the session.

If you want to see the shape of finished skills before writing your own, browse the examples in Anthropic's official skills repository, or the ready-made packs in the AI Services Market directory. Reading two or three good SKILL.md files teaches the format faster than any guide — including this one.