Why the wrong agent skill keeps firing

Three collisions that look identical from the outside

1. 1

   Overlap: two descriptions claim the same trigger words.

   A weekly-report skill and a client-update skill both say they summarise the week. Every phrasing that reaches one reaches the other, so the selector is choosing between two things you told it were the same. It is not guessing badly. It is answering the question you asked.

2. 2

   Catch-all: one description is broad enough to match anything.

   A description that opens with "use for any writing task" will out-match a specific skill on that skill's own subject. One catch-all in a set of twelve quietly becomes the default for all twelve, and the symptom shows up on the other eleven.

3. 3

   Vocabulary drift: the winner matches your words better.

   You type "draft the Henderson recap". The skill you wanted says "report", the one that fires says "recap". Neither is wrong about its own job. The one that fires is the one that shares your vocabulary, which is rarely the one you were thinking of.

Tell them apart before you rewrite anything. Run the same prompt three times. If the same wrong skill wins every time, it is overlap or a catch-all. If different skills win, your prompt is not reaching either description clearly, and the problem is the prompt.

If nothing fires at all, that is a different failure with different causes. See why a skill never fires.

Write the boundary into both files, not one

Fixing only the skill that lost leaves the winner just as greedy, and it will take the next thing you install. Both descriptions have to say where they stop.

# weekly-report/SKILL.md
description: Summarises the week's work.

# client-update/SKILL.md
description: Writes a summary of the week for a client.

# weekly-report/SKILL.md
description: Internal weekly summary for the team, pulled from
  commits and tickets. Use when the user asks for a standup note,
  a team update, or what shipped this week. Not for anything a
  client reads.

# client-update/SKILL.md
description: Outward-facing progress note for one client account.
  Use when the user names a client and asks for an update, a
  check-in, or a status email. Not for internal summaries.

The "not for" line is doing most of the work. It gives the selector a reason to reject a near miss, which is the one thing a list of positive triggers cannot do.

Catch-alls belong last, or not at all

A general-purpose skill is worth keeping only if its description says it is the fallback. Name the cases it does not cover and point at the skills that do. If you cannot write that sentence, the skill is competing with your set rather than completing it, and deleting it will fix more pages than editing it.

Confirm it with prompts, not by reading

A boundary reads well and still loses. The only proof is the prompts you would really type, run against the whole installed set rather than the two files you were thinking about, because the skill that wins may be a third one you forgot. There is a short guide on testing a skill.

Collisions are what a tested set prevents. Every skill in the Agency Owner pack ships with the eval cases it is measured against, and the cases cover the boundaries between skills as well as the skills themselves.