Package a Repeatable Process as a Skill
A skill is useful when a single static instruction isn't enough: you need an order of steps, inputs, outputs, stop conditions, scripts, or references. It's a repeatable workflow, not a long universal prompt. In the companion project that skill became verified-change.
---
name: verified-change
description: Implement a small repository change through explicit scope, plan, patch, tests, and independent evidence review. Use for bug fixes and focused refactors.
---
# Verified change
1. Restate the goal, allowed write paths, constraints, and acceptance checks.
2. Read the relevant implementation, tests, and repository instructions before editing.
3. Write a short plan naming files, symbols, risks, and verification commands.
4. Make the smallest coherent patch. Do not change generated output or unrelated files.
5. Run the narrowest relevant test first, then `npm run check`.
6. Inspect the final diff and report changed files, commands, exit codes, and residual risks.
Stop and ask for direction if the requested change requires credentials, a destructive operation, or writes outside the declared scope.A skill's minimal anatomy is simple: name - a stable identifier; description - what it does and when it's relevant; explicit inputs and outputs; a step-by-step procedure with no hidden premises; checks and stop conditions; references to scripts and assets loaded only when needed.
Where each product looks for skills is worth keeping in view - the directories and the way to invoke differ.
Product · Documented project directories · Invocation
- Codex - .agents/skills/<name>/SKILL.md; Automatically by description or explicitly by skill name
- Claude Code - .claude/skills/<name>/SKILL.md; Automatically or /skill-name; disable-model-invocation: true leaves only explicit calls
- Cursor - .agents/skills/ and .cursor/skills/; Automatically or via the / menu; Cursor also documents compatible Claude and Codex directories
Two rules guard against typical mistakes. The first is about a single reason to exist: verified-change fits a focused bug fix and refactor, while deploy, DB migration, and incident response need separate skills because they have different rights and stop conditions.
A side effect must not fire on unclear relevance. Claude Code and Cursor document disable-model-invocation: true. For deploy, sending a message, or a commit workflow, an explicit user call is usually clearer than the model's automatic choice.The second is about portability: the SKILL.md format is common in idea, but the supported fields, directories, and invocation behavior differ, so keep a minimal compatible core and check extensions in the target product.
Prompt, instruction, and skill are only three of five surfaces. Choosing between them and a hook or CI must be done by the level of guarantee.