Agent Skills Are Not Prompts: A Complete Engineering Guide to Writing, Evaluating, and Operating Them
As agentic coding tools become standard, the difference between a productive agent and an unreliable one is the quality of its Skills. Poorly written Skills don't fail loudly; they silently increase token costs, grab the wrong tasks, and output outdated code, eroding trust in the entire system.
Cramming team knowledge into a single, massive Skill file creates context bloat and trigger chaos. A proper Skill uses a three-layer architecture—metadata for routing, instructions for process contracts, and scripts for deterministic actions—to load only what a task needs. The highest-yield Skills target high-frequency, easily botched tasks, acting as fault-tolerance patches that close the gap between a model's frozen training data and current best practices.
Five core design patterns cover most business flows: Tool Wrappers isolate SDK context, Generators enforce output structure via templates, Reviewers decouple checks from execution with modular scoring, Inversion forces agents to collect requirements instead of guessing, and Pipelines enforce sequential workflows with hard checkpoints. Writing a Skill is only the start; an 8-step closed-loop process from scenario selection to evaluation is the minimum for industrial-grade reliability.
Evaluation must break the black box. A four-layer framework—trigger, execution, outcome, and system—is needed to pinpoint failures, and A/B testing against a no-Skill baseline is mandatory. Without ongoing governance, a Skill ecosystem decays: directories become noisy, valuable Skills get buried, and old Skills that should be retired or downgraded to static scripts continue to pollute context and routing.
The most common Skill failure mode is not a crash, but a silent, steady drift toward outputting old SDK patterns and grabbing the wrong tasks—a degradation invisible without layered evaluation.
Google's Gemini API developer skill improved task success from 28.2% to 96.6% not by being encyclopedic, but by providing a capability overview, current SDK info, and links to docs; the Skill's role is to route the agent to the right approach, not replace documentation.
Anthropic and OpenAI both converge on the same principle: maximize a single agent's capability before introducing multi-agent complexity, and treat high-risk actions with human-in-the-loop checkpoints.
The boundary between a Skill and a Tool is defined by stability of execution; when a Skill's core value becomes reliably running a deterministic process, it should be retired from the prompt context and reimplemented as a script or MCP tool to reduce cost and evaluation burden.
Skill ecosystem decay follows a predictable pattern: directories grow without categorization, valuable Skills are buried in noise, and old Skills are never retired, making the system increasingly untrustworthy. The fix is product-management discipline, not more authoring guides.