Skills
/write-skillTurn repeated instructions into a skill you can test.
The tell in your fingers
A repeated explanation may be a reusable procedure
You begin another task and type the same preamble: inspect the existing conventions, do not change generated files, run the relevant checks and report what remains uncertain. Repetition is useful evidence. It suggests that part of the work may be stable enough to capture instead of rebuilding it from memory each time.
A skill is a reusable, versioned procedure that an AI harness can load when a defined trigger appears. It is more than a saved prompt. A useful skill states when it applies, when it does not, which steps to follow, what evidence completion requires and when the agent must stop or ask for a decision. The second explanation is a candidate for a skill, not proof that one should exist.
Repeated instructions are a signal, not the finish line
Writing a procedure down creates a candidate skill. Testing and ownership make it reusable.
Retyped guidance
- Lives in one conversation Easy to omit a constraint on the next run
- Changes invisibly No version or review trail
- Depends on memory The user must remember when and how to restate it
codify, then evaluate
Testable skill
- Sharp trigger and exclusions The harness can inspect when it applies
- Expected artifact and evidence Completion is reviewable
- Evaluation cases and owner Changes can be tested, versioned and maintained
A skill is reusable only while someone keeps it aligned with the work.
Give the procedure boundaries
A skill needs an entrance, an exit and an owner
Start with the trigger. Name something observable, such as “a task adds or changes a database migration,” rather than “use this when the work feels risky.” Then name exclusions. A request to explain a schema without changing it should not start a migration procedure. Sharp exclusions prevent a useful rule from becoming irrelevant ceremony.
Next specify inputs, ordered actions, allowed tools, evidence and escalation points. Put destructive actions behind human authority. Record a version, owner and reason for the last change. Finally, test the skill against cases where it should run, cases where it should stay silent and difficult cases where the correct response is to pause. A procedure becomes reusable when its boundaries are as clear as its instructions.
This is harness engineering
Reuse reduces instruction drift; it does not improve the model
Writing a skill does not make the model smarter or guarantee obedience. It moves repeated instructions into the working system around the model, where they can be inspected, tested and changed. That can reduce variation between sessions and make failures easier to trace: you can compare an output with the procedure and ask whether the trigger, instruction, tool or judgement failed.
Reuse has costs. A skill consumes context and execution time. It can carry an old policy into new work or fire in a project whose tools and permissions differ. Portability is therefore conditional. The underlying principle may travel, while command names, file paths, approval rules and evidence checks need a project-specific version. Stable, consequential repetition is a good candidate. A rare task or a procedure still changing every week may be cheaper and safer to handle directly.
A complete worked example
Version the procedure, then make it survive an evaluation
Suppose a team repeatedly asks an agent to review database migrations. The reminders vary, so the first version turns them into one procedure. Trigger: a task creates or changes a migration file. Exclude: read-only schema questions and disposable local prototypes. Procedure: inspect existing data, identify locks and downstream consumers, define rollback or roll-forward recovery, test a clean database and a representative fixture upgraded from the prior schema, then compare the observed schema and data with the intended result. Destructive or irreversible changes require a named human approver.
The skill also defines completion evidence: the migration and recovery commands, before-and-after checks, relevant test results and unresolved risks. Save that as version 1.0. Then evaluate it on known scenarios rather than trusting the prose. The set should include safe changes, a table with existing rows, a long-running backfill, an irreversible operation and tasks that should not trigger the skill.
In an illustrative evaluation, imagine version 1.0 flags six of eight known migration risks and incorrectly fires on both read-only questions. Version 1.1 narrows the trigger and adds a check that upgraded data satisfies new constraints before enforcement. On the same set, it flags all eight known risks and stays silent on both exclusions. Those numbers are not a universal benchmark; they are a regression check for this procedure. If a new failure appears, keep the case and revise the version. Brainstorming can expose the first shape, while a reliable trigger makes sure the finished skill is actually considered at the right time.
A maintainable skill has an operating contract
The procedure needs enough structure to activate correctly, act safely and prove what it produced.
- Trigger and exclusions Name both when the method applies and when it should stay out.
- Inputs and authority Define required context, allowed tools and prohibited actions.
- Actions and stopping rules Describe the sequence, escalation point and safe boundary.
- Artifact and evidence State what must exist and how another person can inspect it.
- Evaluation cases Include ordinary, edge, false-positive and should-not-trigger examples.
- Owner and version Someone reviews drift, updates dependencies and retires obsolete rules.
Portability is earned through explicit dependencies, not promised by a file format.
Maintenance is part of the procedure
A reusable skill is maintained, not made permanent
A skill can decay when an API changes, a command disappears, policy moves or the surrounding model and tools behave differently. Give it a maintenance trigger: review after a miss, a false activation, a relevant platform change or a scheduled interval that matches the risk. Retire it when the task disappears or direct handling becomes clearer than the reusable procedure.
The professional value is not that instructions become free or last forever. It is that repeated judgement becomes a visible artifact with an owner, evidence and history. The student value is equally practical: every failed evaluation can become a retained case instead of a lesson remembered vaguely. Capture what is stable, test what you captured and keep the right to change it when reality does.
A repeated procedure earns reuse only when its trigger, exclusions, evidence, evaluation and maintenance owner are explicit.