The Art of Writing Skill

Everyone building agents has hit the same wall. The model is fine on the happy path and quietly wrong on yours. It reaches for raw SQL when a governed metric is sitting right there. It reads "last quarter" as a calendar quarter when your company doesn't run on the calendar. It hands you a number it never checked. Each failure looks like a prompt problem, so you patch the system prompt, and the system prompt grows, and the failures move somewhere else.

Agent Skills are the fix, and they are now an open standard adopted across some thirty agent products. The format is simple enough to learn in twenty minutes from the spec. Which is exactly the problem: everyone learns the format, almost nobody learns the craft, and the result is a field full of skills that are beautifully written and never fire.

This book is about the craft.

It covers what a skill actually is and why every design decision falls out of the three tier loading model. When a skill is the right tool at all, and when you really wanted an MCP fix, a prompt, or a subagent. Why the description is a silent gate that most skills fail at, and why a skill that never triggers is indistinguishable from a skill that doesn't exist. How to write a body that corrects the model's defaults instead of documenting your domain, and why "less is more" turns out to be a measured result rather than a matter of taste. Why scripts are the only part of a skill that doesn't vary, and what that buys you. And how to actually know whether any of it worked, which almost nobody does, because it requires running the baseline you would rather not run.

Seven chapters, each one sitting long, each ending with checks that target a specific misconception. One running example, an analytics agent over a company data warehouse, carried the whole way through.

Written for engineers who already have an agent and want it to stop being almost good enough.

Volume Two, Beyond a Single Model, is in progress.