Define the outcome, inputs, and non-goals

A useful skill has a finish line. “Help with releases” doesn’t have one. It could mean versioning, packaging, publishing, deploying, announcing, rolling back, or all of those at once.

Our skill is narrower. Its outcome fits in one sentence:

Produce an evidence-backed release-readiness report for the current repository.

That’s a job someone can name, ask for, and check.

Inputs and output

The inputs are the repository, the version you intend to release, and any release policy the project documents. The output is a report with the checks it ran, the blockers it found, the warnings, and a go-or-no-go recommendation.

Notice the output is a file, not an action. The agent writes a report. It doesn’t do anything to the repository.

Non-goals matter as much as goals

This is the part most people skip. Write down what the skill does not do:

• it doesn’t bump the version
• it doesn’t commit or push
• it doesn’t publish a package
• it doesn’t deploy
• it doesn’t send announcements

Each of those has different permissions and a different cost when it goes wrong. A bad report wastes ten minutes. A bad publish is on npm forever. A later skill could do those things, but only after its own review.

Is the scope right?

Two symptoms tell you the scope is off.

If the skill needs five unrelated modes and a page of “if the user asks X, do Y” routing, it’s too broad. Split it.

If the skill contains one command that no other workflow would use, it may be too narrow. A project script might be enough.

Aim for the middle: a coherent unit of work with a clear end.

Write the contract

Put this in a file next to your extraction note and fill it in:

Outcome: an evidence-backed release-readiness report for the current repository
Inputs: the repository, the target version, the project's release policy
Output: a Markdown report with checks, blockers, warnings, and a decision
Non-goals: version bumps, commits, pushes, publishing, deploying, announcements
Completion evidence: every check in the report names the command it ran and its result

Now hand it to another developer and ask two questions. Could you tell when this skill is done? Is any dangerous action still ambiguous? If they hesitate on either, the contract isn’t finished.

I do this before writing a single line of SKILL.md. Ten minutes on the contract saves hours of scope creep later.