Agent Skills, out of the clipboard

The symptom is recognisable. In a team that has worked with an assistant for a few months, there is one instruction that works well: the one producing a design note in the right format, or checking a deliverable against a domain standard. It lives 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 of which nobody knows which is right.

This is exactly where operations scripts stood twenty years ago, and the remedy is the same: put them in a repository, give them a format, and make changes go through review. What was missing until now was the format and the means of distribution: two things an open specification and a command-line utility now provide.

The format is deliberately poor: a folder, a Markdown file with a few metadata fields at the top, and whatever files the instruction refers to. That poverty is its main quality: 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.py

The part that decides everything is the description at the top: it determines whether the instruction is summoned at the right moment. A vague description produces one that never fires, or worse, fires everywhere. It is the only place where the writing needs care, and the one that gets rushed.

The utility installs an instruction from a repository rather than from a machine. That is all it takes: from the moment the install address is the company’s account, the instruction stops being personal. It is reviewed before merging, it has a history, and removing it is done once for everybody.

# 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-review

The organisational consequence is more interesting than the technical one. An instruction that goes through review becomes an object somebody answers for, and that changes what gets written in it: loose phrasings that passed unnoticed in a private conversation get challenged as soon as a reviewer reads them. It is the same mechanism as code review, and it has the same effect on average quality.

I have no method for evaluating an instruction. We can say a change improved a result over three attempts; we cannot say it did not degrade another, and human review does not see it either. While that gap holds, a shared instruction remains an artefact you review without being able to verify: better than the clipboard, and worse than code.

And a reservation about momentum. Ease of installation encourages accumulation, and a library of forty instructions of which six are used is worse than six: it makes the choice expensive at exactly the moment it should be obvious. Removal has to be as routine as adding, and it never is spontaneously.

• agentskills · spécification
• skills · utilitaire d’installation