AI Guides › Skills & Agents

Writing Skills For Non-Technical Teammates

By Nigel Guy · 3 min read

An engineer writes a skill the way they'd write anything else technical: precise, terse, assuming the reader can fill in gaps from context. That's fine when the reader is another engineer. Handed to a non-technical teammate, the same skill is a black box that either works exactly once the way they expected, or fails in a way they have no idea how to diagnose — and the engineer never notices, because they never see it fail that way themselves.

The mechanism: the Plain-Language Pass

Before handing a skill to a non-technical teammate, run it through this pass — separate from writing the skill itself:

1. Remove every term that assumes technical background. Not by dumbing anything down, but by translating: "trigger condition" becomes "when this kicks in," "output schema" becomes "what you'll get back." If a teammate has to ask what a word means before they can use the skill at all, that word needs replacing.
2. Write the failure mode in plain terms, explicitly. Not "handles errors gracefully" — "if it can't find the file, it'll tell you that and stop, rather than guessing." A non-technical user has no instinct for what a silent failure looks like, so it has to be spelled out, or they'll assume a wrong answer is a right one.
3. Give them one thing to check, not a debugging process. An engineer troubleshoots by inspecting internals. A non-technical teammate needs a single, concrete thing to look at — "if the number in row three looks wrong, stop and flag it" — not a general instruction to "verify the output."
4. Test it with the actual person, not a colleague who already gets it. An engineer reviewing the skill will fill gaps automatically without noticing they did. The person it's actually for won't, and that's the only test that tells you anything.
5. Give them a plain way to say "this didn't work." Not a bug tracker — a specific person or channel, described in the skill itself, so a failure gets reported instead of quietly worked around.

What to skip

Skip assuming a clear one-line description is enough on its own — clarity about what a skill does is not the same as clarity about what it looks like when it doesn't. Skip translating the language but leaving the underlying assumptions technical; a plain-language description of a process only a specialist could actually verify is still, in practice, a skill only a specialist can use.

Guardrails

• This pass doesn't make a fundamentally complex task simple — it makes an already-appropriate task usable by someone without the background to debug it themselves. If the task itself needs technical judgement to run safely, translating the words doesn't remove that requirement.
• Revisit the plain-language version whenever the underlying skill changes. A translation that drifts out of sync with the actual behaviour is worse than no translation, because it reads as current when it isn't.
• Don't let "it's for non-technical users" become a reason to skip documenting the failure mode for anyone — that step improves the skill for every reader, technical or not.

All 751 AI guides · JulieMango plans from £17/mo