Skip to main content

How to write an AI skill (SKILL.md) that actually gets used

· 5 min read
The MindMax team
The MindMax team
Building MindMax

An AI skill is a plain-text file — usually SKILL.md — with a name and a one-line description of when it applies at the top, and the method below: the steps, the checks, the shape of the output. To write one that gets used, describe the situation it applies to rather than its contents, keep the method concrete enough to be followed literally, and fix it the first time it lets you down.

The third time you type the same instruction into a chat box — "decisions first, each with an owner and a date" — that sentence has become a skill. It just has not been saved yet.

Skills versus prompts versus custom instructions​

  • A saved prompt is text you paste. It works if you remember it exists.
  • Custom instructions apply to every message. Good for standing preferences ("British spelling", "be brief"), bad for one kind of job, because they apply to every other kind too.
  • A skill applies to one kind of job, is called by name or picked when the job fits, and lives as a file you can read, edit and send to someone.

The format has spread across AI agent tools because it is simple: a Markdown file, a short header, and prose.

The anatomy​

---
name: meeting-notes
description: Use when turning rough meeting notes or a transcript into a record of decisions and actions.
---

1. Lead with decisions. Each one gets an owner and a date. If no date was agreed, write "no date agreed"
   rather than inventing one.
2. Then open questions, each with who is expected to answer.
3. Then a short narrative only if something cannot be expressed as a decision or question.
4. Never attribute a statement to a person unless the notes name them.

Two parts, and they do different jobs.

The description decides whether the skill is picked. When an AI chooses a skill automatically, it usually sees only names and descriptions until one is needed. So write the description as the situation it applies to — "use when turning rough notes into decisions" — not a summary of what is inside it.

The body decides what happens once it is picked. Write it as instructions to a careful colleague who will follow them literally. Concrete beats clever: "if no date was agreed, write no date agreed" does more than "be accurate about dates".

Five rules that make skills work​

  1. One job per skill. "Meeting notes" is a skill. "Writing helper" is a wish.
  2. Say what to do when information is missing. That is where models improvise, and improvisation is where they invent things.
  3. Describe the output's shape. A list, a table with these columns, four quadrants. Shape is easier to follow than tone.
  4. Keep the shelf small. Overlapping descriptions make the right skill harder to pick. Retire the ones you never use.
  5. Fix the line, not the whole file. When a result is wrong, the instruction usually did not say what you meant. Change that one line and run it again.

Read before you install​

A skill contains no code, but text can still tell an AI to do things you would not choose. Read a skill from someone else in full before installing it, the way you would read a script before running it.

In MindMax​

Skills are files in your folder: drop a SKILL.md into the skills folder and it counts; move it out and it stops. Type / to call one by name, or describe the task and let the matching one be picked. Typing /new-skill and describing the method in plain words gets you a drafted skill to read and approve — nothing is saved until you say so.

The same skill can be switched on for chat, for the canvas and for the editor. In chat it can take several turns and read your documents. On a canvas card, its output comes back in the shape the method calls for, such as a table or four quadrants. In the editor it runs on the paragraph you selected and comes back as a tracked change.

SKILL.md files written for other agent tools work as chat skills, with one boundary: only the text carries over. Scripts or other files in a skill's folder are not run, and steps that depend on tools MindMax does not have will not happen.

What a skill cannot do​

A skill is instructions, not new abilities. It changes how a job is approached using what the AI can already do — read your documents, search, write files. If you were hoping to add a capability, this is the wrong mechanism.

More on AI skills, with the step-by-step in using skills. The definition on its own is in the glossary: agent skills. The built-in ones are mostly classic methods — see thinking models.