Agent Skills Are Not Just Prompts: What Breaking Them Taught Me About Writing Stable AI Behavior

Teams adopting agentic coding tools often blame the model when a Skill misfires, but the real failure is usually in the description, untested boundaries, or overloaded files. Fixing those three things costs far less than rewriting prompts and produces behavior that survives rephrased requests.

A Skill starts as a simple markdown file telling an agent when to act, how to act, and when to stop. The first trap is stuffing rules into the body while writing a vague description — agents use progressive loading and decide whether to trigger almost entirely from the name and description alone. Boundary test cases catch more failures than longer prompts ever will. As Skills grow, splitting into references, assets, and scripts keeps the main file navigable, but splitting too aggressively forces the agent to jump across too many files and increases errors. Scripts handle deterministic checks like date formats and field completeness; the model handles fuzzy judgment like whether a risk description is clear. External capabilities like knowledge bases and MCP tools belong at the connection layer, not inside the Skill file — a Skill declares dependencies but cannot supply credentials or network access. When multiple Skills coexist, they compete for triggering, so descriptions must be narrow enough to avoid collisions and coexistence tests must verify that a new Skill does not hijack tasks or escalate privileges.