How to Prompt AI to Write a SKILL.md File

Ask a model to write a SKILL.md and you will usually get a tidy file that is worthless, because it fills the body with what it already knows about the topic. A skill exists to carry what the model cannot infer: your steps, your naming, your edge cases, the reason you do step four before step three. So the prompt that works does not ask for a skill. It asks the model to interview you, then write one. That single change is the difference between a file you delete and one you keep.

If the format is new to you, our introduction to agent skills covers what they are and how agents load them.

What the spec actually requires

Give the model the constraints up front, because it cannot guess them and a file that violates them will not validate. From the published specification:

The body below the frontmatter is plain Markdown with no format restrictions. The spec recommends step-by-step instructions, example inputs and outputs, and common edge cases, and advises keeping SKILL.md under 500 lines with detailed material moved into separate reference files.

Why the description field carries the most weight

Agents load skills progressively. At startup they read only the name and description of every available skill, roughly a hundred tokens each. The full body loads only once a task appears to match. So the description is not a summary for humans, it is the matching rule, and a vague one means the skill never activates.

The spec contrasts these directly. "Helps with PDFs" is given as the poor example. The good one reads: "Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction."

The difference is the trigger clause. Tell the model explicitly to write both halves, what it does and when to use it, including the words a user would actually type.

The prompt

Paste this, filling in the first two lines.

I want to create an Agent Skill (a SKILL.md file) for this task:
<one sentence describing the task>

Context: I do this <how often>, for <who>, using <tools>.

Do NOT write the skill yet.

First, interview me. Ask me up to 10 questions, one at a time, to
extract the procedural knowledge you cannot infer: the exact steps in
order, the decisions I make and what I base them on, the edge cases
that have burned me, the naming and conventions I use, and what a
good output looks like versus a bad one. If my answer is vague, push
back and ask for a specific example.

When you have enough, write the SKILL.md to this spec:
- YAML frontmatter with `name` (1-64 chars, lowercase a-z, 0-9 and
  hyphens only, no leading/trailing/consecutive hyphens) and
  `description` (1-1024 chars, stating BOTH what it does AND when to
  use it, including the words someone would actually type).
- Markdown body: numbered steps, a worked example with realistic
  input and output, and a section on edge cases.
- Keep it under 500 lines. If a section grows long, tell me to split
  it into references/ instead of writing it inline.
- Write only what I told you. If a step needs information I have not
  given, insert TODO and list those TODOs at the end.

Then list which parts came from me and which you inferred.

The last instruction is the quality gate. A model that must separate your input from its own inference will inflate the first list, but it exposes the invented parts clearly enough to delete them. The TODO rule serves the same purpose, which is the technique we cover more generally in getting AI to flag uncertainty.

The three failure modes

1. It writes an encyclopaedia entry

You asked for a skill about invoicing and got a general explanation of invoicing. The model already knows that, so the skill adds nothing and burns context when it loads. The interview step prevents it. If it happens anyway, reply with: "Remove everything you would already know without me. Keep only what I told you." What remains is the actual skill, and if nothing remains, you did not need one.

2. The description does not trigger

A description like "handles our reporting workflow" never matches a real request, because nobody types that. Make the model list five phrasings a user might actually use, then fold the distinctive words into the description.

3. No worked example

Instructions without an example leave the model guessing at format. One realistic input with the exact output you expect is worth more than another paragraph of prose, and it is the part generated skills most often skip.

Checking it before you commit it

Validate the frontmatter mechanically rather than by eye. The project publishes a reference library, and skills-ref validate ./my-skill checks that the frontmatter is valid and follows the naming conventions. It will not tell you whether the instructions are any good.

For that, test it the way it will be used: start a fresh session, give the agent a real task that should match, and see whether the skill activates and whether the result is right. A skill that works in the conversation you wrote it in proves very little.

Once you have more than a handful, treat them as the shared asset they are. The habits from our guide to building a reusable prompt library apply directly, and the overlap with writing a good system prompt for a custom assistant is substantial, since both are instructions a model reads before acting. The broader techniques sit in our prompt engineering guide.

Frequently asked questions

Why does the model write generic content in my skill?

Because it defaults to what it already knows when you have not given it your procedure. Make it interview you before writing, then ask it to strip anything it would have known without you.

How long should a SKILL.md be?

Under 500 lines per the spec, with the body ideally under about 5,000 tokens. Detailed reference material belongs in separate files that the agent loads only when needed.

What makes a good description field?

It states what the skill does and when to use it, and includes specific keywords matching how someone would phrase the request. It is the only part loaded at startup, so it is what decides whether the skill ever activates.

Can I validate a SKILL.md automatically?

Yes, for the frontmatter. The skills-ref reference library validates naming conventions and frontmatter structure. The quality of the instructions still needs a real test run.

Does the name have to match the folder?

Yes. The spec requires the name field to match the parent directory name, alongside the lowercase, hyphen and length rules.