Write an open source SKILL.md that validates and loads

Pick one task that repeats and can end

A first skill earns its place on a task your team already does the same way every week. Write down the last three times it came up, with the sentence each request arrived in. "Can you refund the annual plan on invoice 4471" carries the words a description needs. Three requests in a month say the file is worth writing. A task that came up once belongs in that session's prompt.

Then say what finished looks like: a queue assigned, a tag pushed, a reply sent. A task whose end you cannot state in one sentence, such as "improve the onboarding docs", turns into a skill full of advice. Advice never signals completion. A task with two decisions in it, such as "triage a ticket and draft the reply", is two skills, or one skill with the second half left out.

Name the folder before you write a line

A skill is a folder with a SKILL.md in it, so the path is skills/<name>/SKILL.md. The format's specification fixes the name: at most 64 characters, lowercase letters, digits and hyphens, no leading or trailing hyphen, no double hyphen, and the same string as the folder. The folder's last segment is the name, so skills/pdf/ holds name: pdf and skills/refund-policy/ holds name: refund-policy (skills entries).

Name the task in the folder: refund-policy will still mean the right thing in a year, and support-tools-v2 will not. A rename later touches the folder, the frontmatter, the registry line and the grant, and each one is a place to forget.

Write the description for the agent that decides, then the body for the agent that acts

Two readers open this file. The first has not chosen anything: at startup it sees one line per skill and decides which to load (the guide). The second has already loaded the file and needs the steps. A team writes its first skill for the second reader, then adds a description at the end from memory. That order is why so many first files summarise the topic and never write down the trigger.

Build the description from the requests you collected. Name what the skill does in one clause, then name the situations and the words a request arrives in: "Use when a customer asks for a refund, a plan change back to monthly, or an invoice correction." Stay inside 1,024 characters, and keep the sentence specific enough that the skill next to it in the list could not claim the same trigger.

Number the steps, and give the run a stop and an end

A body is a procedure. Numbered steps, one action each, in the order they happen. Each step names the file, the field or the command it works on, so the agent does not have to infer where to look.

Two lines at the bottom do most of the work. A stop condition ends the run at the step where it appears, for example a missing order record or two clauses that both match. Without it the agent improvises the rest. An exit criterion is a state someone else can check. The queue field holds a value, the reason quotes the line that decided it, or the tag sits on the merge commit. The complete file in the SKILL.md panel carries both, and the gap between a skill that finishes and one that keeps going is usually those two lines.

Keep the file inside the budget, and move the tables into references/

Metadata loads at startup for every skill, about 100 tokens of it. The body loads once the skill is chosen, and the recommendation for it is under 5,000 tokens. The main SKILL.md should stay under 500 lines. Those limits are generous enough that a first draft passes them and still crowds out the task.

The body holds the decision. A 300-line table of field names belongs in references/fields.md, with one line in the body saying when to open it. Anything under references/, scripts/ or assets/ loads only when a step reaches for it. The specification asks for references one level deep, not a chain of folders.

Validate, then grant the skill to one agent

Two checks catch most of what a reviewer would otherwise find. The format's reference library validates the file and its naming, skills-ref validate ./skills/refund-policy. The project's check is stricter about placement. A skills folder with no SKILL.md, or a SKILL.md whose frontmatter name: is not the skill name, is an error, and kortix validate exits 1 on it (kortix.yaml reference).

Then register the skill and grant it, in the order the kortix.yaml panel shows. The registry line maps a name to its folder. The grant sits in one agent's block. Grant the agent whose work the task is, and let it run there for a week before the grant reaches the rest of the team. An omitted skills key grants nothing, so a registered skill stays inert until an agent names it. A grant of all hands the new file to every agent in the same commit. Then one bad step is everybody's problem.

Run the task once by hand, then let the agent run it

Do the task yourself once and keep a note of every decision the file did not cover. Those notes are the missing steps, and they turn up faster this way than in a reread of the draft.

Then run it in a session. One isolated sandbox per session. Each session has its own isolated machine and branch. Read the output against the exit criterion, and ignore how good the writing sounds.

When the skill came from another repo, or you edited one that did, the diff it produces on a real task is the review. A borrowed skill that returns the right answer on a task you know beats its README. One that returns a confident wrong answer has shown you where its steps end. The file lives in the project's git repository, so a correction is one line a reviewer reads. Session work reaches main through a change request. Merge is default-deny for agents. Kortix keeps its own skills like this, in a repository you can read. Open source. Read it, fork it, audit it.