Designing Reusable AI Skills

A prompt works. You save it. Next month someone else uses it, gets a different shape of answer, and adjusts the wording. Now there are two versions and no way to say which is right.

What was saved was a phrase. What was needed was everything that was implicit when it worked the first time.

What a skill means here

In PMP, a skill is a reusable, versioned package of instructions and declared operating constraints for a repeated task. It may define inputs, outputs, tool scope, success criteria, failure conditions and escalation.

Other platforms use the word differently, sometimes for a tool, sometimes for a plugin, sometimes for a saved prompt with a name. This is working vocabulary for describing one architecture, not a claim about what the word means generally.

The load-bearing part is declared. A prompt that happens to be reused is still a prompt. What makes it a skill in this sense is that the things which were assumed are now written down.

What to declare

These are design dimensions rather than required fields. A small skill may need three of them; a consequential one probably needs all six.

Purpose. One sentence naming the job this owns that nothing else should. If it takes a paragraph, you may be describing a workflow.

Inputs. What must be supplied, what is optional, and what should be ignored. "Ignored" earns its place: skills degrade when callers pass extra context that quietly changes behaviour.

Output shape. What comes back. If anything downstream depends on it, that shape is a contract, and the mechanics of checking it are structured output.

Tool scope. What it may touch. A skill drafting a release summary does not need billing access. Narrower is easier to validate and easier to reason about later.

Success criteria. What a correct result looks like, specifically enough that someone else could judge it.

Stop conditions. What it does instead of guessing: missing input, conflicting evidence, a request beyond its scope. A skill that never stops is either trivial or overconfident.

A worked example, and its limits

This repository packages its own editorial skill as a SKILL.md alongside five recipe files and a validator that checks structure rather than judgment. The skill file states the contract for publishing here; the recipes carry per-form language rules; the validator runs over both.

The interesting part is the line the skill draws itself. Its own wording is that automation verifies the contract while the author remains accountable for the claim. The validator can confirm that an incident is declared as observed, that a claim maps to prose, and that a repository source carries an immutable commit reference. It cannot confirm that the observation happened, or that a cited source supports the interpretation drawn from it.

That is a useful thing to copy and a precise thing not to overstate. It shows one way to package and check a skill. It does not establish a universal skill format, and the validator passing does not mean the writing is any good. It means the declared structure holds.

One skill or two

The most common design question is whether to split.

If two parts of a skill would be evaluated differently, they probably should not be one skill. That test does more work than it looks like, because it catches the cases where a single package has quietly acquired two jobs with different definitions of success.

Split it when the parts serve different objectives, carry different risk, produce outputs consumed by different things, or need different tool permissions.

Keep it whole when the steps are tightly coupled to one objective, share the same inputs, share the same definition of done, and stop for the same reasons.

Changing it without breaking it

Reuse is what makes a skill valuable and also what makes changing it consequential. A prompt used once has a local blast radius. A skill used in four places does not.

A small set of cases, kept stable, is enough to notice most drift:

Case	Question it answers
Normal	Does it still do the job on ordinary input?
Borderline	Does it stay sensible when the input is thin or ambiguous?
Failure	Does it fail clearly when it cannot proceed?
Escalation	Does it stop when it should, rather than continuing?

Four cases you actually run beat forty you intend to write. The point is not coverage; it is that a behaviour change becomes visible instead of arriving as a complaint weeks later.

Signals worth watching after a change: output no longer matches its declared shape, escalation happens less often with no drop in risk, callers start correcting results by hand, or the skill needs more context than it used to.

This is scoped to one question: does this revised package still do what it claims? How to evaluate AI output more generally, and what to record over time, belongs to evaluation and observability.

Versioning

Version when behaviour changes, not when wording does.

A materially changed skill package should remain distinguishable from the version it replaced. Whether a caller has to do anything differently tells you about interface compatibility, not whether the package changed enough to version. A clearer instruction producing the same results is a tidy-up. Changed instructions, a widened tool scope or a weakened stop condition are worth being able to tell apart later, even when nothing downstream has to move.

Whatever scheme you use matters less than being consistent about that line, and recording what changed in behaviour rather than what changed in text. A version number attached to a diff nobody can interpret is bookkeeping.

What this changes

Stop asking whether a prompt can be reused. Ask whether the thing you would hand to someone else says what it needs, what it returns, what it may touch, and when it should stop. If it does not say those, reuse will produce a second version rather than a shared one.