Three Design Pitfalls in Agent Skill Systems (and How to Avoid Them)
Agent frameworks are proliferating, and nearly every team building on top of them eventually adds a Skill or plugin system. Getting the metadata contract, invocation path, and lifecycle management right from the start avoids silent token waste, broken tool permissions, and context pollution that are painful to debug later.
A Skill is a loadable instruction pack centered on a SKILL.md file, but the simplicity of the concept hides several design traps. The header metadata goes well beyond name and description: fields like `allowed-tools`, `disallowed-tools`, `model`, `context`, and `agent` control tool permissions, model routing, and execution isolation. Misunderstanding `disallowed-tools` as a permanent block instead of a single-turn restriction is a common bug that silently breaks subsequent agent actions.
Two invocation patterns dominate: a dedicated `SKILL_TOOL` that returns an activation marker, base directory, and body, or a simpler `ReadFile` approach that reads the markdown directly. The dedicated tool unlocks fine-grained permission scoping and state tracking; the file-read approach works for early prototypes but leaves metadata unused. Regardless of the method, registration must stay lightweight—only name and description enter the system prompt, never the full body.
The third pitfall is skipping deduplication and state tracking. Without an activation marker and an active-skills set, the same Skill body gets injected repeatedly, burning tokens and bloating context. That same set also governs when to apply and revoke tool permissions, making it the linchpin of a clean implementation.
The distinction between `allowed-tools` as pre-approval versus `disallowed-tools` as hard block is subtle but consequential—many implementers treat both as simple filters and miss that one removes the need for human approval while the other requires explicit restoration logic.
Claude Code and Codex already diverge on invocation: Claude Code uses a dedicated tool, while Codex shells out to `cat`. This suggests the ecosystem hasn't converged on a single pattern, and anyone building a Skill system today is making a bet on which approach becomes standard.
The `metadata` field is explicitly not read by the model, which makes it a clean extension point for ops concerns—cost centers, ownership, auditing—without risking prompt pollution. Few plugin systems in the Western ecosystem separate machine-readable metadata from model-readable instructions this cleanly.