How to Write AI Agent Skills: Document Like Prose, Maintain Like Code
adnan_hashmi · x · 2026-10-21
A detailed guide by Eugene Meidinger and Ruben Van de Voorde on writing skills for AI agents (Claude Code, GitHub Copilot, etc.).
Key points
- A skill is just a folder with a SKILL.md plus optional reference files and scripts — packaged context in an open standard, but it lets agents do things they couldn't before.
- The frontmatter (name + description) is always loaded and decides whether the agent reaches for the skill; instructions and references load only on invocation.
- Write skills for your business processes, definitions, and preferences — things agents can't derive — not for technical details they can figure out themselves.
- Best written iteratively: run the agent, document where it struggled, revise. Overly prescriptive skills often cause confusion; consider cutting rather than adding.
- The companion graphic frames the method: write it like documentation (prose, reader-first, explain the why), maintain it like code (in Git, PR-reviewed, tested with evals).
More from coding & agent
- Laude Institute launches Slingshots FOUR: 14 projects across 8 top institutions — a1zhang · 2026-10-21
- Research agent Épi sets 120 records, narrows n-queens constant interval 84x — dair_ai · 2026-10-21
- Compaction hooks in practice: keep last n messages verbatim, summarize the rest for full agent continuity — MoonL88537 · 2026-10-21
- The blank prompt box hides real operational burden: context, workflow and supervision fall on users — _AustinCalvert_ · 2026-10-21
- DeepMind paper: self-evolving agents forget as they learn — fastest learner GEPA also breaks old tasks most — rohanpaul_ai · 2026-10-21
- arXiv: Are Self-Evolving Agents Continual Learners? Plasticity comes at the cost of stability — rohanpaul_ai · 2026-10-21