How to Write SKILL.md: A Step-by-Step Guide (No Code)

A SKILL.md is a short text file that teaches an AI assistant (like Claude) how to do a specific job the same way every time — it’s not code, it’s a set of instructions written in plain prose. For example, you teach the assistant once to “check these things before publishing any new page,” and from then on it remembers, every time. On this page you’ll learn three things: what parts make up a SKILL.md file, how to write one without any coding, and a real example you can copy and use. At the end, you’ll also see the 3 most common mistakes.

The Anatomy of a SKILL.md File

A SKILL.md file has two parts, both plain text — no code in either.

1. The ID card (name and description). At the very top of the file sits a short, two-line intro: the skill’s name and what it does. This part needs to stay short, because the assistant, faced with dozens of skills, decides which one to use based on just these two lines. I covered how Claude Skills work in more detail here; this page focuses purely on the writing side.

2. When it should trigger. This is the part people skip most often. It’s not enough for the description to say “what this skill does” — you also need to say “when to use this skill.” The assistant reads that sentence and decides whether the current conversation matches. Write it vaguely (e.g. “content helper”) and the assistant either never triggers it or fires it in the wrong situations.

3. Step-by-step instructions. The body that follows the ID card explains how the job gets done. Write it the way you’d explain a task to an assistant — as if you were talking to a smart helper who’s brand new and knows nothing about the subject. Spell out what to do, in what order, which file to check, and what the result should look like.

Step by Step: How to Write One Without Code

Here’s how to build a SKILL.md file with plain sentences, no code:

1. Define the job in one sentence. Write a single, honest sentence answering “what does this skill do?” Long descriptions tire you out, not the assistant.
2. Write the trigger. Add a separate sentence: “use this when…” The more concrete it is, the better it works — not “related to reports,” but “when preparing the weekly competitor pricing report.”
3. Number the steps. Write out the job in the order you’d actually do it in your head: check this first, then look here, then write it in this format. Don’t skip steps — the assistant doesn’t know what’s in your head, only what’s written.
4. Add a concrete example. “If this kind of input comes in, the result should look like this” — a single example like that works better than ten lines of abstract explanation.
5. Test it and narrow it down. On the first try, a skill either triggers too often or not at all. Try it on two or three real situations and sharpen the trigger sentence accordingly.

In my experience, the step people waste the most time skipping is step 5. People write it and never look back — but a skill’s real test doesn’t show up on the first use, it shows up on the third or fourth.

Example: A Complete SKILL.md File

Below is a full SKILL.md for a simple job — a checklist to run before publishing a new blog page. Copy it and adapt it to your own work.

`--- name: pre-publish-page-check description: Checks title, description, image, and internal links before a new blog page or article is published. Triggers when the user says “check before publishing,” “is the page ready,” or “look at this before it goes live.”

Pre-Publish Page Check

This skill checks five items, in order, before a page is published.

Steps

1. Confirm the title is 50-60 characters and includes the target keyword.
2. Confirm the meta description is 140-160 characters and states a concrete benefit.
3. Check that the page has at least one image, and that the image has a non-empty “alt” attribute.
4. Confirm the page includes at least one internal link (to another relevant page).
5. If any of the four items above is missing, list clearly which one is missing and how to fix it. If everything checks out, say “ready to publish.”

Note

This check is purely structural — it does not evaluate the accuracy or quality of the content.`

Notice the description packs both “what it does” and “when to use it” into a single sentence, the steps are numbered and concrete, and the “note” section honestly states the skill’s limits.

The 3 Most Common Mistakes

I’ve read and written dozens of SKILL.md files, and the same three mistakes keep repeating.

1. Writing too generically. Broad labels like “content helper” or “SEO expert” tell the assistant nothing. The more specific you write, the more accurately the skill triggers at the right moment.
2. Writing too much. Pages of background, rationale, and philosophy don’t help — if anything, they make the assistant more likely to miss the important step. Say what to do, not why it’s done.
3. Leaving the trigger vague. This is the most common mistake of all. People write “this skill does X” and stop there, skipping the “when to use it” sentence entirely. The result: the skill either never fires, or interrupts an unrelated conversation.

In Real Life: How It’s Used on This Site

I don’t just use this in theory — I use it in my own work. Behind the scenes on this site, a skill runs automatically before any new page is published, checking the title, description, image, and schema markup — triggered with a single line of command, so I don’t have to remember which standard to check against every time; the skill remembers. I set up the same logic for my clients: weekly competitor price scans, campaign report prep, new product page checks — anything repetitive.

I covered the bigger picture of this in the Agentic AI Guide — skills are a concrete application of the “delegate work to the assistant” idea I talk about there.

You Can Have Me Do This

If you want a SKILL.md written for your own work, or want to wire a few existing skills together, I set that up. I work remotely, billed hourly — a simple checklist skill usually takes about 2 hours, and a system that chains multiple skills together can run up to 2 weeks. See the scope on the Your Own AI Assistant page, or just write to me directly.

Frequently Asked Questions

Where do I need to save the SKILL.md file?

It depends on the tool you’re using; generally you save it as SKILL.md inside a folder named after the skill itself, and you can put extra files (a template, an example list) in the same folder. You don’t need to know how to code — a text editor and the right location are all it takes.

Do I need to know how to code to write SKILL.md?

No. The file itself is written in plain text and markdown — headings, bullet points, numbered lists, nothing more exotic than that. The hard part is describing the job clearly and in order — that’s a writing skill, not a coding skill.

When does a skill trigger — do I trigger it, or does the assistant decide?

Both are possible. Most of the time, the assistant compares the content of the conversation against the “description” field in the file and decides on its own — which is why writing that description clearly matters so much. You can also call a skill directly by name if you want.

What’s the difference between a SKILL.md and a normal instruction (prompt) I give the assistant?

A normal instruction gets rewritten every time and stays within that conversation. A SKILL.md is written once, saved, and automatically remembered in every relevant situation — think of it as giving the assistant a permanent habit.