Agent Skill Anti-Patterns: Scope Creep, False Positives, and Prompt Bloat

The failure modes look like model problems and aren't

When a skill misbehaves -- fires when it shouldn't, produces output nobody asked for, contradicts another skill that also fired -- the instinct is to blame the model. Almost always the actual defect is in how the skill file itself was written, not in the model following it. This is the catalogue of the specific ways a skill file goes wrong, and each one has the same shape: something that seemed like a reasonable shortcut when the skill was first written turns into a reliability problem once the catalog has more than a handful of entries.

These build directly on the discovery mechanism and the versioning/composition model -- most of what follows is what happens when either of those disciplines is skipped.

Scope creep: the description that grew to match everything

A skill starts narrow -- "review a diff for correctness bugs" -- and picks up scope one reasonable-sounding addition at a time: security issues, then style, then test coverage, then documentation completeness. Each addition made sense in isolation. The result is a description broad enough that it plausibly matches almost any request touching code, which is the false-positive problem from discovery in its most common concrete form: not two skills accidentally overlapping, but one skill quietly becoming the entire catalog's gravity well.

The fix is splitting, not trimming. A code-review skill and a security-review skill covering genuinely different concerns, each with its own tight description, retrieve more accurately than one skill trying to cover both -- this site's own code-review and security-review skills are deliberately two files for exactly this reason, not one skill with a longer description.

A skill that tries to do too much in one pass

Related but distinct from scope creep: a skill whose description is appropriately narrow but whose instruction body tries to accomplish several genuinely separate jobs in one pass -- review the diff, then also write the commit message, then also draft the PR description. Each of those three is legitimately its own skill on this site (code-review, commit-message-writer, pr-description-writer), and combining them into one instruction body doesn't save the runtime any work -- the model still has to reason through three different tasks -- while making the single skill harder to test, harder to version independently (a fix to the review methodology now risks disturbing the commit-message logic sitting in the same file), and harder to match precisely, since its description has to describe three things at once to stay honest.

Contradictory instructions when two skills both fire

This is the accidental-composition case from versioning and composition, but it's worth calling out on its own because it produces a specific, confusing symptom: the model appears to behave inconsistently on requests that look identical, when what's actually happening is that two skills with conflicting instructions are matching at different rates depending on small wording differences in the request. One skill says keep responses terse; another, unrelated skill that also happens to match says always include a full worked example. Neither skill is wrong on its own. The bug is that nothing checked whether their instructions could coexist before both were added to the same catalog -- which is exactly what a catalog manifest, reviewed before a new skill ships, is meant to catch.

Prompt bloat: the skill that eats the budget it's supposed to save

A skill exists to make context-efficient use of a request -- load only the instructions relevant to this specific task, instead of carrying every possible instruction in a bloated system prompt. That property inverts once a skill's own body grows large enough that loading it costs more context than the monolithic prompt it replaced would have, for the fraction of requests that actually needed it. A skill file that's accumulated exhaustive edge-case documentation, a long history of examples, and defensive caveats for every objection anyone has ever raised is a skill that has become the thing it was built to avoid.

The practical check: if a skill's instruction body is pushing past a few hundred lines, ask whether it's actually several skills wearing one description (the "does too much" anti-pattern above), or whether it needs an aggressive edit pass to cut anything that isn't pulling weight on the common case. Detailed edge-case handling that only matters 2% of the time is a better fit for a shorter pointer plus a reference the model can pull in on demand than for inline text paid on every single invocation.

The fix that generalizes: verify before reporting

Several of the anti-patterns above are really one root problem wearing different clothes: a skill that produces a plausible-looking result and never checks whether that result is actually correct before presenting it. The clearest countermeasure is designing a verify step directly into the skill's instructions, not hoping the model self-corrects.

This site's own code-review skill is built around exactly this idea. Its instructions don't stop at "list problems you notice" -- they require a second pass, for every candidate finding, that states the concrete input or sequence of events that would actually trigger it: "If you can't articulate a specific failing scenario, it's not a finding -- drop it." That single instruction is what keeps the skill's output from degrading into the false-positive noise that erodes trust in a review tool fastest -- plausible-sounding findings that don't survive a second look. The same verify-before-reporting shape generalizes to almost any skill whose job is producing a judgment rather than executing a mechanical transform: state the check, require evidence before the claim ships, and treat "I couldn't verify this" as a legitimate output rather than a reason to keep guessing.

Catching these before they ship, not after

Every anti-pattern above is far cheaper to catch during a review of the skill file itself than to diagnose later from confusing model behavior in production, for the same reason a code review is cheaper than a production incident: the evidence is right there in the text instead of scattered across logs and user reports. A short checklist, applied whenever a skill is added or substantially edited, catches most of this list directly: does the description have an explicit negative-scope clause, not just a positive one? Does the instruction body do exactly one job, or does it secretly do two or three? Does anything in the manifest already cover adjacent ground this new skill might collide with? Is the body short enough that loading it doesn't outweigh what it saves? And does the skill's own instructions require evidence before it reports a finding, or does it just ask the model to "be careful" and hope?

That last question is worth being blunt about: "be careful" is not a mechanism. A verify step with a concrete bar -- state the triggering scenario, cite the specific line, drop anything that doesn't clear the bar -- is a mechanism, and it's the difference between a skill that degrades gracefully as a catalog grows and one that quietly erodes trust one false positive at a time.