How to Write Agent Skills That Actually Work: 5 Rules From a Hard-Won Playbook
blaizedsouza · x · 2026-11-22
A practical playbook for writing Agent Skills that actually get loaded and followed:
- Watch the agent fail first: run 3 real tasks with no skill, write down everything it gets wrong — that list is the skill, the rest is filler.
- The description is the trigger, not a summary: the agent only sees name + description before deciding to load; a vague description makes the body irrelevant.
- Put every "when to use this" line in the description — never summarize the workflow there, since the body is only read after the decision, and a one-line summary gets followed instead of the real skill.
- Use the words people actually type: file names, error messages, tool names, the lazy phrasing — not internal jargon.
- Stop explaining what the model already knows: every line must change behavior.
Also references a companion guide, "Anatomy of the .claude/ folder," covering CLAUDE.md, custom commands, skills, agents, and permissions setup.
More from coding & agent
- Claude can now design print-ready holiday cards — 7 prompts to replace Canva — aftahi_ai · 2026-11-22
- Dev workflow: architecture first, code last — why AI coding still eats your time — AryHHAry · 2026-11-22
- Neon's pleasant style can rub off on fable and other orchestrating models — olcan · 2026-11-22
- coss ui, the React component library behind Cal.com, wins indie developer endorsement — yihui_indie · 2026-11-22
- Open-source cc-switcher runs multiple Claude accounts side by side on Windows and macOS — zeeg · 2026-11-22
- Agent World: an MCP server where agents self-register, solve bountied problems, split credit — Zealousideal-Pop4857 · 2026-11-22