Agent Skills and Procedural Playbooks: Rehearsed Set-Pieces for AI
A developer asks their coding agent to cut a production release. The agent guesses the steps: it bumps the version number, creates a git tag, commits straight to main, and forgets to run the test suite or update the changelog.
Nothing broke because the model was dumb. It broke because the model had to improvise a seven-step company procedure from zero.
In football, teams do not improvise corner kicks. When the ball rolls out to the corner flag, eleven players do not form a circle to brainstorm who runs where. They run a rehearsed set-piece: the kicker raises one arm, two forwards cross paths near the near post, and the central defender attacks the open space behind them. Every movement has been practiced fifty times on the training pitch.
In software development with coding agents, that rehearsed set-piece is called a Skill.
The Reality
Most teams start by stuffing every procedure into their system prompt or a giant markdown file. That approach has two flaws: it burns context tokens on every single turn, and it buries the model under pages of rules that have nothing to do with the current edit.
If you put your twenty-step database migration checklist into the root instructions, the agent reads those twenty steps even when you only ask it to fix a button color in CSS.
A skill solves this by remaining dormant until needed.
A skill is a directory on disk containing a procedural manual, usually named SKILL.md, and optional helper scripts. At startup, the agent harness reads only a two-sentence description of the skill and its trigger conditions. The actual instructions stay off the field. Only when your prompt matches the trigger does the harness load the full playbook into active memory.
The Why
This architecture creates a specific engineering challenge: the trigger description.
If a description reads “helps with databases”, the agent either ignores the skill entirely or pulls it into context whenever someone edits a query. A reliable trigger description works like a referee whistle: precise, explicit, and bounded. It lists the exact tools, file extensions, and intents that demand the routine:
“Use when modifying Prisma schema files or executing database migrations. Do not use for read-only SQL queries or seed scripts.”
The second discipline is knowing what belongs in the playbook versus what belongs in an executable script.
Large language models excel at judgment calls: evaluating edge cases, deciding whether an error requires a retry, and translating intent into flags. They struggle with mechanical, deterministic tasks like parsing syntax trees or calculating package checksums.
A well-architected skill leaves mechanical labor to executable CLI scripts. The SKILL.md file contains the decision logic: when to run the script, what arguments to pass, and how to interpret errors. If an operation can be written as a shell script or a Python utility, write it as a script. Keep the prose for the decisions.
Skills vs MCP: What is the boundary?
Engineers often ask whether they need a skill or a Model Context Protocol (MCP) server.
The distinction is clear:
- MCP provides the physical tools: It connects your agent to external systems like a database, an issue tracker, or a cloud deployment API.
- A Skill provides the playbook: It defines how to use those tools in sequence to achieve an outcome safely.
MCP gives the agent the ability to post a message to Slack; the skill tells it to notify the release channel only after the smoke tests pass.
Where does this break down?
Vague descriptions and procedural bloat.
When descriptions lack clear negative conditions, agents suffer from false triggers, cluttering context with irrelevant playbooks. Conversely, when teams cram deterministic code logic into prose instead of simple CLI scripts, the agent wastes tokens hallucinating arguments instead of executing deterministic tools.
The Takeaway
A skill turns a loose multi-step procedure into a repeatable drill that runs only when summoned and consumes zero context tokens the rest of the time.
AI specialists call it: Agent Skills / Procedural Playbooks / On-Demand Context Loading / Tool Ergonomics
Agent skills decouple domain-specific workflows from persistent system instructions. By registering lightweight metadata schemas that lazily load full Markdown execution playbooks (SKILL.md) upon semantic intent matching, agents minimize token footprint and eliminate instruction dilution. Deterministic operations are delegated to companion CLI binaries, reserving LLM inference strictly for branching heuristics and exception recovery.
💬 What repetitive workflow in your codebase breaks most often when someone tries to follow it from memory?
Part 3 of 10 | #CodingAgentsForHumans