AI Guides › Skills & Agents
By Nigel Guy · 2 min read
Most advice on writing skills treats "good skill" as one fixed standard, as if the same skill should serve someone working alone and a team of twelve equally well. Write it to the solo standard and a team quietly diverges around it, each person tweaking their own copy. Write it to the team standard and a solo operator ends up maintaining ceremony nobody else will ever read.
The rule: decide who else will run this skill before you decide how to write it — a skill built for one person's head and a skill built for a team's shared understanding are different documents, not the same document at different lengths.
| Design question | Solo operator | Team |
|---|---|---|
| How much context to spell out | Minimal — you already know why the skill exists | Full — the "why," not just the "what," because someone reading it wasn't there when it was written |
| How strict the trigger condition | Loose is fine — you'll notice if it fires wrong | Tight and explicit — a loose trigger becomes five people's five different interpretations |
| Where it lives | Wherever you'll find it again | Somewhere discoverable without asking you directly |
| Who can change it | You, whenever | A named owner, with a way for others to propose changes |
| How failures get handled | You notice and fix it | Needs a documented failure mode, or each person handles it differently and silently |
| How much it assumes about prior steps | Can assume steps you always do first | Must state its own preconditions, since not everyone follows your sequence |
Pick your column before you write a line. If you're not sure which column you're in — a "solo" skill that's quietly being used by two colleagues already — you're in the team column, whether you planned to be or not.
Skip writing team-grade documentation for a skill only you will ever run — that's effort spent narrating decisions to an audience of one. And skip assuming a skill that works well solo will translate to a team just because it's "good": a skill's quality and its portability to other people are different properties, and a skill can be excellent at one and useless at the other.