Stop Re-Pasting Your Best AI Prompts: Turn Them into a SKILL.md With a Done Condition

Every team using an AI coding agent eventually builds a private collection of “the good prompts.”

The payment-review prompt. The release checklist. The incident-triage runbook. The one that makes the agent check tests before it confidently edits the first plausible file.

They start as a useful chat message, then become a 70-line paste, then get copied into AGENTS.md, then get shortened until the important constraints disappear.

That is the point where a prompt should become a skill.

Not because a SKILL.md file is magical. It is useful because it forces a workflow to answer five questions that a pasted prompt usually leaves implicit:

1. When should this run?
2. What inputs are required?
3. What sequence must the agent follow?
4. What may it not do without approval?
5. What observable evidence says the work is complete?

The fifth question is the one that changes outcomes. A skill without a done condition is just a longer prompt in a different folder.

The recurring-prompt smell

I use a simple test: if someone has pasted substantially the same instructions into an agent three times, the workflow deserves to be inspected for packaging.

Good candidates are high-context, repeatable jobs:

• reviewing PRs that touch billing, auth, or permissions;
• preparing a release;
• investigating CI failures;
• auditing an API surface;
• turning a written brief into a tested implementation;
• producing a changelog from a real diff.

Bad candidates are one-line operations and workflows that are genuinely different every time. “Rename this variable” does not need a skill. Nor does a vague instruction that still depends on a human inventing every step while it runs.

A concrete example: payment PR review

Imagine a small SaaS team using Stripe. Every pull request that touches subscriptions, invoices, webhooks, or checkout needs the same review:

• authorization and tenant boundaries;
• idempotency for money-moving requests;
• webhook replay behavior;
• state transitions for failed payments;
• relevant tests.

The first version of that workflow is often a prompt like this:

Review this billing PR carefully. Check security, webhooks, idempotency, tests, and anything else that could break payments.

It sounds reasonable, but it gives the agent freedom exactly where the team needs consistency. What is “carefully”? Which files count as billing-related? Does the agent have to run tests? Can it change code while reviewing? What does a finished review look like?

Here is a much better starting point for a skills/payment-pr-reviewer/SKILL.md:

---
name: payment-pr-reviewer
description: ">-"
  Review pull requests that touch Stripe, billing, subscriptions, invoices,
  checkout, or payment webhooks. Check authorization, idempotency, replay
  safety, money movement, and relevant test coverage. Use when reviewing a
  payment-related PR before merge.
---

The description does two jobs: it tells the agent what the skill does and when to choose it. A name is for humans; the description is the dispatch layer.

Then the body makes the work deterministic enough to review:

## Required inputs

- PR diff and changed files
- billing test command: `pnpm test -- billing`
- existing authorization middleware
- webhook handler code when changed

## Review sequence

1. List changed billing-related files before making conclusions.
2. Trace every money-moving request to its authorization check.
3. Check idempotency keys and duplicate-event behavior.
4. For each changed webhook path, verify replay is safe.
5. Inspect existing tests and run the billing test command.
6. Report findings by severity, citing file and line references.

## Safety boundary

Do not change implementation code during review. Ask before running migrations,
calling external payment APIs, or changing production configuration.

## Done when

- all changed payment paths have been inspected;
- the billing test command has been run or a blocker is reported;
- findings explain impact, evidence, and a recommended next step;
- absence of findings is explicit, not implied.

That is not a giant system prompt. It is a compact operating procedure with a measurable exit condition.

The five parts worth preserving

1. Triggers

Do not write “review code.” Write the vocabulary that identifies the job: Stripe, checkout, invoice, subscription, webhook, and money movement.

The same applies to a release skill. “Deploy software” is vague. “Prepare a production release when the user asks to ship a merged branch, cut a release, or promote staging” gives the agent a usable boundary.

2. Required inputs

An agent should not silently guess which command proves success, which environment is safe, or which document is authoritative.

List the inputs it must locate or request. This prevents a familiar failure mode: a beautiful answer based on an incomplete diff, an outdated runbook, or a test command the agent invented.

3. Ordered work

Order matters whenever evidence changes the next action. For debugging, require a reproducible failure before a fix. For a PR review, require reading the diff before suggesting changes. For a release, require a passing build before deployment steps appear.

If a step can be skipped without changing the result, it probably does not belong in the skill.

4. Safety boundaries

Skills are especially valuable when the safe behavior is easy to forget under time pressure.

Examples:

• do not send external messages without approval;
• do not publish, deploy, delete, or alter production data without approval;
• redact credentials from captured output;
• stop instead of retrying a destructive action blindly.

This is not bureaucracy. It is the difference between an agent that helps with a release and one that accidentally owns the release process.

5. A done condition

“Review completed” is not evidence. “All changed payment paths inspected; billing tests run; findings cited by file and line; no finding explicitly stated” is evidence.

Done conditions make a skill testable. They also make handoffs better: another engineer can see what the agent did instead of trusting a cheerful summary.

Skills, project instructions, and hooks are not interchangeable

I use this division:

Put it in…	When it belongs there
AGENTS.md / project instructions	Context that applies to nearly every task in this repository
a skill	A repeatable, multi-step job that should be selected on demand
a hook or CI rule	A rule that must execute regardless of what the model decides

For example, “this service uses pnpm and has a monorepo layout” is project context. “Review a payment PR” is a skill. “Block a merge when tests fail” belongs in CI, not in agent prose.

Trying to make one of these mechanisms do the work of the others is how teams end up with a 600-line context file nobody can confidently maintain.

A quick packaging workflow

When converting a real prompt or runbook, I follow this sequence:

1. Collect evidence. Gather the prompt, relevant AGENTS.md sections, two or three real examples, and the verification command.
2. Mark repetition. Remove background explanation that the agent can discover, but preserve exceptions that caused past failures.
3. Write the trigger description. Include both the job and the vocabulary that should activate it.
4. Add approval gates. Name public, destructive, paid, or production-changing actions.
5. Write a done condition before the detailed steps. If you cannot define proof, the workflow is not ready to automate.
6. Run it on a historical task. The first test should be a real PR, incident, or release that the team already understands.

The goal is not to capture every thought a senior engineer has. It is to capture the parts that must happen every time.

Two ways skills fail

They are too vague. A skill named code-review with “review code carefully” does not give an agent a meaningful workflow. Specialize it when the risk or evidence model changes.

They are too large. A skill that tries to encode every architecture decision becomes unreadable and brittle. Keep the core procedure focused; put reference material, templates, and scripts beside SKILL.md so they can be loaded only when needed.

The sweet spot is a small instruction surface with strong triggers, clear gates, and proof of completion.

Turn the next repeated prompt into an asset

The next time you paste a prompt you know worked last week, do not just save it in a notes app. Ask:

What must be true before this starts, what steps are non-negotiable, what needs approval, and what proves it is done?

Those answers are the beginning of a reusable skill.

I published the full workflow and an installable agent-workflow-packager skill at Terminal Skills. It is designed to turn an existing prompt, checklist, or runbook into a spec-valid skill folder with triggers, examples, approval gates, and a completion check.