How to Write a SKILL.md That Teams Can Trust

A SKILL.md defines one repeated job: when it applies, what it needs, how it is done, what it produces, and how you know the result is acceptable. It is the unit you install, version, test, and own.

It is explicitly not a knowledge base, a style guide, or a collection of related tips. Those are reference files. Conflating them is the most common authoring mistake and it is why so many skill files are four thousand words long and rarely followed.

In most runtimes, the name and description are all the agent sees when deciding whether to load the skill at all. They function as a router, so they should describe the triggering situation in the words a user would actually use, not the internal name of the process.

“Customer renewal brief — use when preparing for a renewal conversation or an account review” routes correctly. “Account Intelligence Framework v2” does not, because nothing a user types will resemble it.

State both boundaries explicitly. The negative boundary matters more than authors expect: a skill that fires on adjacent work produces confidently wrong output in a context it was never designed for, and users lose trust in the whole library rather than the one skill.

Two or three lines is enough. “Use for scheduled renewal and QBR preparation. Do not use for new-business research, for pricing decisions, or when the account has an open legal dispute — escalate those to the account lead instead.”

List the required inputs and the optional ones separately, and say what the skill does when a required input is missing. The correct behaviour is almost always to ask for it or state that it is unavailable — never to proceed on an assumption.

Be specific about form as well as content. “The last call transcript” and “a summary of the last call” are different inputs that produce different quality outputs, and the difference should not be left to chance. Writing that list as a contract the operator can satisfy — including what to do with half-filled CRM fields — is covered in input contracts.

Define the allowed source set. Without this, the effective rule is “anything in the context window plus whatever the model remembers,” which is how outdated internal knowledge and unverifiable claims get into a deliverable.

The allowed set should be a short list with an ordering when sources conflict — for example, the CRM record wins over a transcript on commercial terms, and the transcript wins on stated intent. Conflict rules are cheap to write and prevent a whole class of quiet errors.

Write numbered steps in the order they happen. Each step should be an action with an observable result: read this, extract that, compare against the other, produce this section.

Explanatory prose is the enemy here. If a step needs justification, put the reasoning in a reference file and keep the step imperative. Models follow instructions far more reliably than they infer intent from context, and so do people.

Specify the output precisely: the sections, their order, what each contains, and roughly how long each should be. This is the single highest-leverage part of the file, because an unspecified output shape is the main reason two runs of the same skill look nothing alike.

Include an example of a filled-in output somewhere in the package. One concrete example communicates more about the expected register and depth than several paragraphs of description.

Add a short list of checks the output must pass before it is handed over. Keep them binary so that failure is unambiguous and so that they can be run as tests later.

Four to six checks is the right size. More than that and they stop being run; fewer and they miss the failure modes that matter for your job.

State what happens when the inputs are insufficient. The default behaviour of a language model is to produce a plausible answer, and the whole point of an unknowns policy is to override that default with something explicit.

A workable policy has two parts: name what is missing in a dedicated section of the output, and do not let a missing input silently weaken a conclusion elsewhere. A brief that says “renewal risk cannot be assessed — no usage data provided” is far more valuable than one that quietly assesses it anyway.

Decide what counts as evidence and how it must be attached: a quote, a timestamp, a record ID, a link. Then require it for the claim types where being wrong is expensive.

Requiring evidence on every sentence makes the output unreadable. Requiring it on risks, commitments, numbers, and anything that will be quoted back to a client is the usual balance.

Write the escalation conditions as rules with a named destination. “If the account has an open dispute, stop and hand to the account lead” is actionable; “use judgment on sensitive accounts” is not.

Approval points belong in the file for the same reason. If a human must sign off before anything is sent, that is part of the process definition, not an informal habit — the reasoning is in why approval points belong in the skill file.

The folder holds everything the job depends on: reference files for detail and background, templates for the output, and any scripts the workflow runs. The root file points to them by name and says when to read each one.

This is what keeps the root compact while allowing the skill to be thorough. Detail that is needed sometimes should be one hop away, not inline.

Aim for a root file a person can read in five minutes. Past that length, models begin to weight the beginning and end more heavily, and human reviewers stop reading entirely — so a rule buried in the middle of a long file is effectively not there.

The discipline that works: every time you want to add background, add it to a reference file instead and leave a single pointer. The root file should be almost entirely instructions and specifications.

Include three worked examples rather than one. A typical case shows the expected shape. A messy case — missing inputs, contradictory sources — shows the unknowns policy in action. An edge case shows the escalation path being taken rather than an answer being produced.

The messy example is the one that changes behaviour most, because it demonstrates that declining to conclude is an acceptable, expected outcome. Without it, the skill drifts toward always producing a confident answer.

Put a version and a date in the file, and keep a short changelog of what changed and why. This is what makes a shared skill safe to edit: a reviewer can see what moved and a user can tell whether they are running the current version.

Without it, the rational behaviour for a careful teammate is to avoid the shared artifact and keep their own copy — which is exactly the drift problem described in why teammates avoid an unversioned shared artifact. What a version bump should involve when the real process changes — retesting, release notes, and a rollback path — is in what a version bump should carry.

Different runtimes handle files, connectors, and memory differently, and a skill that is useful in several tools needs a small amount of per-tool guidance. Keep it in a clearly separated notes section or a separate adapter file.

Never let platform detail leak into the procedure itself. The moment a step says “upload the file to the project,” the skill has stopped being portable — the layering is described in keeping platform detail out of the procedure.

Always test in a clean session with no prior context. A skill tested in the conversation where it was written inherits everything you explained along the way, which is why authors consistently overestimate how well their instructions stand alone.

Then run the real test suite: ten past cases with known-good outcomes, scored against the checks. Behaviour that only appears under messy inputs will not appear any other way — the method is in testing a skill in a fresh session.

Most weak skill files fail in the same handful of ways, and all of them are visible in a five-minute review once you know what to look for.

The underlying pattern is writing for a reader who already understands the job. The skill will be run by someone who does not, in a session with no context, on a messier input than you tested.

Treat a new skill like a code change: someone other than the author reviews it against a fixed rubric before it enters the shared library. Six questions are enough, and they take about five minutes.

The reviewer should also run the skill once themselves in a fresh session. Reading a skill file and running one produce different opinions about it, and the second is the one that matters.

A raw SKILL.md is the instruction file. What we ship is the file plus the things that make it trustworthy in a team: a test suite built from your real history, worked examples including the messy case, per-tool install notes, a version and changelog, and a named owner. Those are precisely the four properties a native container cannot hold, which is the argument in what a native container cannot hold.

For common jobs, the library already contains packaged skills you can install and adjust. For jobs carrying your own rules and source systems, the build process is on the custom workflows page, and the docs cover installation, versioning, and compatibility.