Agent Skills, out of the clipboard
The instructions given to assistants end up where nothing is reviewed: in conversations and personal files. Getting them out only requires treating them like the rest of the code.
The symptom is easy to recognise. In a team that has been using an assistant for a few months, one instruction gives good results: the one that produces a design note in the right format, or checks a deliverable against an industry standard. It sits in its author’s clipboard. It has been pasted into a private conversation, sent to two colleagues, modified by one of them, and there are now three versions with nobody knowing which is correct.
Operations scripts were in the same state twenty years ago, and the remedy is the same: put them in a repository, give them a format, and submit changes to review. Until now there was no format and no means of distribution, which an open specification and a command-line utility now provide.
The format is minimal: a folder, a Markdown file with a few metadata fields at the top, and the files the instruction refers to. That simplicity is its main advantage, since there is nothing to learn, and a writer who does not code can propose a change.
design-note-review/
├── SKILL.md # the instruction itself, and when it applies
├── references/
│ └── internal-standard.md
└── scripts/
└── check_headings.pyThe decisive element is the description at the top of the file, because it determines whether the instruction is used at the right moment. A vague description produces an instruction that never triggers, or triggers everywhere. It is the one place where the wording needs real care, and often the one neglected.
The utility installs an instruction from a repository instead of from a machine. That is enough: once the installation address is the company’s account, the instruction is no longer personal. It is reviewed before being merged, it has a history, and it is removed once for everyone.
# Install from the company account rather than from a public repository
npx skills install github:company/skills/design-note-review
# Whatever gets installed must be listable and removable
npx skills list
npx skills remove design-note-reviewThe effect on the organisation is more interesting than the technology. An instruction subject to review has an owner, and that changes what gets written in it: approximate wording that went unnoticed in a private conversation is challenged as soon as a reviewer reads it. The mechanism is that of code review, and the effect on average quality is the same.
I have no method for evaluating an instruction. You can observe that a change improves a result over three attempts, but not check that it does not degrade another one, and human review cannot do that either. As long as this gap remains, a shared instruction is a text you review without being able to test it, which is better than the clipboard and worse than code.
One last reservation. Easy installation encourages accumulation, and a library of forty instructions of which six are used is less useful than those six alone, because it makes the choice difficult just when it should be obvious. Removing instructions has to become as routine as adding them, which never happens on its own.