[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M72TY2QFQ5VME262NA7PZD94":3,"skill-same:01M72TY2QFQ5VME262NA7PZD94":51},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":23,"commitSha":24,"skillDirectory":25,"forksCount":26,"repositoryHtmlUrl":27,"repositoryHomepageUrl":28,"ownerHtmlUrl":29,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":30,"install":31,"resources":44},"01M72TY2QFQ5VME262NA7PZD94","dispatch-authoring",null,"Matcher-aware authoring and troubleshooting knowledge for the full dispatch authoring surface — trigger frontmatter, applicable_agents, applicable_skills, routable, and description: phrase-matching. Loaded by any agent (router, code-writer, doc-writer, project-planner, etc.) when the user wants to write, improve, troubleshoot, or understand dispatch configuration. Trigger this skill whenever the user types \u002Fdispatch-authoring, asks \"how do I write triggers\", \"how do I make frontmatter for my agent\", \"what's a good keyword weight\", \"set up triggers\", or says \"my agent isn't being dispatched\", \"this skill never matches\", \"my frontmatter isn't working\", \"dispatch isn't picking up\", or similar authoring or troubleshooting requests around dispatch configuration. Covers the matcher's seven-decision ladder, scoring math, weight ladder {0.25, 0.5, 1.0}, symmetric Porter2 stemming and the no_stem opt-out, fnmatch path-glob footguns, conflict-pair detection, and the audit-catalog CLI pointer.","glitchwerks\u002Fclaude-wayfinder","glitchwerks","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F280158622?v=4","01M72TXS0Q6NRNKZYFQ4KFG1VJ","01M72TXS18Q7XJ6RNHV7K0D9XF",4,"MIT","https:\u002F\u002Fgithub.com\u002Fglitchwerks\u002Fclaude-wayfinder\u002Fblob\u002Fmain\u002Fskills\u002Fdispatch-authoring\u002FSKILL.md",[],[],"2026-11-10 22:39:42",false,"---\nname: dispatch-authoring\ndescription: >\n  Matcher-aware authoring and troubleshooting knowledge for the full\n  dispatch authoring surface — trigger frontmatter, applicable_agents,\n  applicable_skills, routable, and description: phrase-matching.\n  Loaded by any agent (router, code-writer, doc-writer,\n  project-planner, etc.) when the user wants to write, improve,\n  troubleshoot, or understand dispatch configuration. Trigger this\n  skill whenever the user types \u002Fdispatch-authoring, asks \"how do I\n  write triggers\", \"how do I make frontmatter for my agent\", \"what's\n  a good keyword weight\", \"set up triggers\", or says \"my agent isn't\n  being dispatched\", \"this skill never matches\", \"my frontmatter\n  isn't working\", \"dispatch isn't picking up\", or similar authoring\n  or troubleshooting requests around dispatch configuration. Covers\n  the matcher's seven-decision ladder, scoring math, weight ladder\n  {0.25, 0.5, 1.0}, symmetric Porter2 stemming and the no_stem\n  opt-out, fnmatch path-glob footguns, conflict-pair detection, and\n  the audit-catalog CLI pointer.\n---\n\n# Frontmatter Authoring Guide\n\nThis skill covers everything you need to write, improve, and troubleshoot\ntrigger frontmatter for claude-wayfinder agents and skills. It explains\nwhat fields the matcher reads, how scoring works, the seven routing\ndecisions the matcher can produce, and the most common mistakes that cause\nan entry to match poorly or never match at all.\n\n---\n\n## 1. What the Matcher Consumes\n\n### Source precedence\n\nThe catalog generator accepts trigger configuration from two places: inline\nfrontmatter inside the agent or skill file itself, and a **sidecar file**\nplaced next to the main file. The sidecar always wins when both are present.\n\nThe current sidecar format is **v6**. Under v6:\n\n- A **skill** stores its trigger configuration in a file named `triggers.yml`\n  placed in the same directory as `SKILL.md`:\n\n  ```\n  skills\u002Fpython\u002FSKILL.md\n  skills\u002Fpython\u002Ftriggers.yml   ← authoritative trigger config\n  ```\n\n  Per issue #150, a colocated `\u003Cname>.triggers.yml` next to `SKILL.md`\n  (owned and project agent sidecars) overrides inline frontmatter. The\n  `SKILL.md` file itself should not contain `triggers:`,\n  `applicable_agents:`, or `applicable_skills:` keys; the generator emits\n  a warning and ignores them if they appear there.\n\n- A **plugin-shipped agent** stores its trigger override at\n  `triggers\u002F\u003Cplugin>\u002Fagents\u002F\u003Cname>.yml` (per issue #142). This file\n  activates a dormant plugin agent that would otherwise score zero.\n\nFor the canonical field reference see `docs\u002Fschema.md`. For the design\ndiscussion behind the sidecar approach see `docs\u002Fdesign\u002Ftrigger-schema.md`.\n\n### Schema fields\n\n| Field | Where it lives | Purpose |\n|---|---|---|\n| `command_prefixes` | `triggers:` block | Slash commands that immediately short-circuit to score `1.0`. |\n| `agent_mentions` | `triggers:` block | Agent names whose explicit mention in the prompt immediately short-circuits to score `1.0`. |\n| `path_globs` | `triggers:` block | `fnmatch`-style globs matched against the `file_paths` dimension of the input. Each matched glob adds `0.4` to the score. |\n| `keywords` | `triggers:` block | List of `{term, weight}` mappings. Each term found in the input keywords adds `0.5 × weight` to the score. Terms are Porter2-stemmed unless `no_stem: true` is set (see § 1 \"Stemming\"). |\n| `no_stem` | per-keyword flag | Optional `no_stem: true` on a `{term, weight}` mapping exempts that term from stemming — it matches the raw (unstemmed) input token verbatim. Use for acronyms, product names, and CLI flags (`aws`, `gh`, `ps1`). |\n| `keyword_groups` | `triggers:` block | **AND-group conjunctive triggers** (added v0.6.0, #135). List of `{slots: [{name, terms: [...]}, ...], weight}` groups. A group fires only when **all** of its slots match — each slot must have ≥ 1 of its terms present in the input keywords. On match, the group adds `1.0 × weight` (via `_GROUP_MULTIPLIER`, distinct from the `0.5` `_KEYWORD_MULTIPLIER` so a satisfied weight-1.0 group can solo-decide `delegate`). Use when a routing decision should require co-occurrence of two or more terms (e.g. verb + noun) rather than either alone. |\n| `tool_mentions` | `triggers:` block | Tool names matched against the input `tool_mentions` dimension. Each match adds `0.5`. |\n| `excludes` | `triggers:` block | Terms that hard-zero the entry's score when found in the input keywords. |\n| `applicable_agents` | skill sidecar top-level | Hard allowlist of agent names that may receive this skill. `[\"*\"]` means any agent. `[]` means no agent — the skill is dormant. |\n| `applicable_skills` | agent sidecar top-level | Hard allowlist of skill names to attach when routing to this agent. `[\"*\"]` means any. `[]` means no skills. |\n| `routable` | agent frontmatter top-level | When `false`, the agent is excluded from the scored-agent pool. Set to `false` on the router itself so it is never selected as a delegation target. Absent on skill entries. |\n\n### How each field type feeds the matcher\n\n`command_prefixes` and `agent_mentions` are checked before any additive\nscoring begins — a match on either field returns `1.0` immediately without\nexamining any other field. `excludes` is also a pre-scoring check: a match\nzeroes the entry and stops further evaluation.\n\n`path_globs`, `keywords`, and `tool_mentions` contribute additively to a\nrunning score that is capped at `1.0` before being returned. An entry\nwith no triggers in any of these three fields will score `0.0` on any\nprompt that does not happen to name the entry directly by command prefix\nor agent mention.\n\n### Stemming (symmetric Porter2, issue #304)\n\nThe matcher applies **symmetric Porter2 (Snowball English) stemming** to\nkeyword matching. Catalog terms are stemmed at catalog-build time; input\ntokens are stemmed at dispatch time; matching is stem-vs-stem. The practical\nconsequence for authors: **list the base form only — you do not need to\nenumerate inflections.** `implement` matches `implementing` and\n`implemented`; `refactor` matches `refactored`; `lint` matches `linting`.\n\nThis applies to flat `keywords` terms and to `keyword_groups` slot terms\nalike. Two distinct catalog terms that collapse to the same stem are\ndeduped at parse time so a single input token cannot double-count.\n\n**`no_stem` opt-out.** Add `no_stem: true` to a `{term, weight}` mapping to\nexempt that term from stemming. A `no_stem` term is matched verbatim against\nthe raw (unstemmed) input token. Use it for tokens that must not collapse —\nacronyms, product names, and CLI flags:\n\n```yaml\ntriggers:\n  keywords:\n    - { term: \"deploy\", weight: 1.0 }                 # stemmed: matches \"deploying\", \"deployed\"\n    - { term: \"aws\", weight: 1.0, no_stem: true }     # exact: matches \"aws\" only\n    - { term: \"gh\", weight: 0.5, no_stem: true }      # exact: matches \"gh\" only\n```\n\nStemming changes nothing about the scoring formula or thresholds — it only\nchanges which input tokens count as a match. See `docs\u002Fdispatch-authoring-guide.md`\nfor the canonical reference, and § 9 for the `--check-stems` collision\npre-flight.\n\n---\n\n## 2. The Seven-Decision Ladder\n\nThe matcher evaluates the catalog against the input features and emits\nexactly one of seven decisions. The ladder is evaluated in order; the\nfirst branch whose conditions are satisfied wins.\n\n1. **`needs_more_detail`** — the input's extracted features populate fewer\n   than two distinct dimensions (paths, keywords, tools, command prefixes,\n   agent mentions); the matcher did not attempt to score the catalog at all.\n\n2. **`delegate`** — one routable agent scored ≥ 0.85 and its gap above\n   the second-place agent is ≥ 0.2; high-confidence single winner,\n   delegation is appropriate.\n\n3. **`self_handle`** — no dominant agent, but at least one skill scored\n   ≥ 0.5; the router handles the task itself with the matched skills\n   attached.\n\n4. **`mixed_content`** — the gap between the top two agents is \u003C 0.2 and\n   ≥ 2 agents are each clamped at 1.0 on path-disjoint lanes (every\n   qualifying agent has at least one path-glob match, and no input path\n   is claimed by more than one agent). The decision carries a `lanes[]`\n   array (one entry per specialist, each with `agent`, `score`,\n   `matched_paths`, and `skills`) and an `unassigned_paths[]` list for\n   input paths not claimed by any lane. Fires after `self_handle` and\n   before `advisory`.\n\n5. **`advisory`** — the best agent scored ≥ 0.5 but the `delegate`\n   threshold was not met (gap \u003C 0.2 or score \u003C 0.85) and `mixed_content`\n   conditions were not satisfied; delegation is suggested but not certain.\n\n6. **`ask_user`** — reserved in v0.1 and v0.2; the current matcher never\n   produces this decision. Include a handler for forward compatibility.\n\n7. **`self_handle_unaided`** — no agent and no skill scored above\n   threshold; the router proceeds without delegation or skill attachment.\n\n### Input-side density floor vs. entry-side weak scoring\n\nThese are two separate concerns. Conflating them leads to incorrect\ndiagnosis when an entry fails to match.\n\n**Input-side density floor (the `needs_more_detail` branch above).**\nThe matcher emits `needs_more_detail` when the *user prompt's* extracted\n`Features` populate fewer than two dimensions — paths, keywords, tools,\ncommand prefixes, or agent mentions. This is a property of how thin the\n*input* is, not of how thin any catalog entry's triggers are. A two-word\nprompt with no file paths and no recognised keywords triggers this branch\nregardless of how rich the catalog is. The fix is to provide a richer\nprompt, not to change the entry's triggers.\n\n**Entry-side weak scoring (a calibration footgun — see Section 5).**\nAn entry whose triggers populate only one dimension — for example\nkeywords-only with no `path_globs`, `tool_mentions`, or\n`command_prefixes` — will score weakly on most inputs, because it can\nonly accumulate score when the input happens to mention one of its\nspecific terms. This is not an unreachability theorem; the entry *can*\nscore if the input fills its one dimension. But it is a calibration\nsmell: the score ceiling on matching inputs is limited (`+0.5 × weight`\nper keyword hit, clamped at `1.0`), and any prompt that doesn't mention\none of the entry's specific terms scores it at zero. Section 5 elaborates\nthe practical guidance.\n\n---\n\n## 3. Scoring Math\n\nThe matcher computes a per-entry score using the following rules, applied\nin order. Short-circuits fire before any additive contribution is\ncalculated.\n\n**Short-circuit rules (evaluated first, in this order):**\n\n- `command_prefixes` match → score = `1.0` immediately.\n- `agent_mentions` match → score = `1.0` immediately.\n- `excludes` match in `features.keywords` → score = `0.0` immediately.\n\n**Additive scoring (when no short-circuit fired):**\n\n- Per `path_globs` match: `+0.4`\n- Per `keywords` match: `+0.5 × weight` (verified at\n  `src\u002Fclaude_wayfinder\u002Fmatch.py:84` — `_KEYWORD_MULTIPLIER = 0.5`;\n  raised from 0.3 to fix single-keyword skills never attaching)\n- Per `keyword_groups` match: `+1.0 × weight` per group that fires\n  (a group fires only when **all** of its slots are satisfied;\n  `_GROUP_MULTIPLIER = 1.0` is deliberately distinct from\n  `_KEYWORD_MULTIPLIER = 0.5` so a satisfied weight-1.0 group can\n  solo-decide `delegate`; #135 \u002F v0.6.0)\n- Per `tool_mentions` match: `+0.5`\n\nThe final additive score is **clamped to `1.0`** before being returned.\n\n### AND-group worked example\n\nAn entry has a `keyword_groups` block requiring both a \"verb\" and a \"noun\"\nto co-occur:\n\n```yaml\nkeyword_groups:\n  - slots:\n      - {name: verbs, terms: [create, open, file]}\n      - {name: nouns, terms: [issue, ticket, bug]}\n    weight: 1.0\n```\n\n| Prompt                              | verbs slot | nouns slot | Group fires? | Score from this group |\n| ----------------------------------- | :---------: | :---------: | :-----------: | --------------------: |\n| \"open the issue tracker\"            |     ✓       |     ✓       |     yes       |  `+1.0 × 1.0 = +1.0`  |\n| \"create the issue body\"             |     ✓       |     ✓       |     yes       |  `+1.0`               |\n| \"open the file\"                     |     ✓       |     ✗       |     no        |  `+0.0`               |\n| \"tell me about issues\"              |     ✗       |     ✓       |     no        |  `+0.0`               |\n\nA satisfied weight-`1.0` group contributes `1.0` to the entry — enough to\nclamp at the ceiling on its own and solo-decide `delegate` if the gap to\nthe runner-up is ≥ `0.2`. That is the design intent of\n`_GROUP_MULTIPLIER = 1.0`: a group is a stronger signal than any single\nflat keyword (which maxes at `+0.5`) because the group already encodes\nco-occurrence — the matcher has more evidence that the prompt intends\nthis entry, so the score reflects that.\n\nThe flat-`keywords` equivalent of the same term lists would score on\neither side firing alone — scoring `+0.5 × weight` on \"open the file\" and\n\"tell me about issues\" too, since each individual term contributes\nindependently. The AND-group structurally requires co-occurrence, which\nis the right shape when the trigger only makes sense for the combined\nintent.\n\n### Worked example\n\nAn entry has one `path_globs` entry (`**\u002F*.py`) and one `keywords` entry\n(`python`, weight `1.0`). For a prompt that mentions a `.py` file and\nthe word \"python\":\n\n```\npath_glob match:   +0.4\nkeyword match:     +0.5 × 1.0 = +0.5\ntotal:              0.9   (below 1.0, no clamping needed)\n```\n\nA score of `0.9` with a gap ≥ 0.2 above the second-place entry would\nyield a `delegate` decision.\n\n### Clamping footgun\n\nBecause the final score is hard-clamped at `1.0`, stacking additional\nhigh-weight keywords past the ceiling adds nothing. Consider an entry\nwith one path-glob hit (`+0.4`) and two weight-`1.0` keyword hits\n(`+0.5` + `+0.5`): the additive total is `1.4`, which clamps to `1.0` —\nexactly the same as one path-glob plus one weight-`1.0` keyword. The\nsecond high-weight keyword is dead weight on any input that already\ncrosses the ceiling.\n\nThe practical guidance: once an entry can plausibly reach `≥ 1.0` on its\nhighest-signal inputs, prefer broadening *coverage* — add more distinct\nterms at `0.25` or `0.5` weight — over stacking duplicate `1.0` weights.\nBroadening raises the score on a wider range of inputs; stacking only\ninflates the sum on the inputs where the ceiling would already be hit,\nand the clamp throws that extra score away.\n\n---\n\n## 4. Trigger Field Rules\n\nThese are the validation rules the catalog generator enforces. Violating\nthem produces a warning at build time and may cause the entry to score\nunexpectedly.\n\n- **Weight ladder is exactly `{0.25, 0.5, 1.0}`.** Any other numeric value\n  is clamped to the nearest ladder step with a validator warning (see\n  `_clamp_weight` in `build_catalog.py`). There is no weight of `0.75`,\n  `0.3`, or `2.0`.\n\n- **`keywords` is a list of `{term, weight}` mappings.** Bare strings are\n  rejected by the generator. Every keyword entry must be an object with\n  exactly two keys: `term` (a string) and `weight` (one of `0.25`,\n  `0.5`, `1.0`).\n\n- **Keyword terms are Porter2-stemmed unless `no_stem: true`.** List base\n  forms; stemming matches inflections automatically (see § 1 \"Stemming\").\n  Set `no_stem: true` on terms that must match verbatim — acronyms, product\n  names, CLI flags. A `no_stem` term is compared against the raw input token,\n  not its stem. Authoring inflected variants of a stemmed term (`deploy`,\n  `deploying`, `deployed`) is redundant — they all collapse to one stem and\n  are deduped.\n\n- **`path_globs` uses Python `fnmatch` semantics, not gitignore semantics.**\n  The matcher calls `fnmatch.fnmatch(path, glob)`. This has important\n  consequences — see the footguns section for the most common mistake.\n\n- **`tool_mentions` is case-sensitive.** The matcher compares tool names as\n  literal strings. `Bash` and `bash` are different values; the correct\n  casing matches what the Claude Code harness uses. Wrong case silently\n  fails to match.\n\n- **`excludes` matches against `features.keywords` only.** The `excludes`\n  list is not checked against `file_paths`, `tool_mentions`, or\n  `agent_mentions`. An exclude term that appears only in a file path will\n  not zero the score.\n\n- **`command_prefixes` should start with `\u002F`.** A prefix like `dispatch`\n  without a leading slash will not match a user-typed `\u002Fdispatch` command,\n  because the dispatcher passes the slash as part of the string.\n\n- **`keyword_groups` requires ≥ 2 slots per group.** A single-slot group is\n  semantically equivalent to a flat `keywords` entry — the catalog\n  generator warns and drops single-slot groups. Use plain `keywords`\n  instead when you only want one set of alternatives. Each slot needs a\n  non-empty `terms` list; empty `terms` makes the slot unsatisfiable and\n  drops the group.\n\n- **`keyword_groups` weights follow the same `{0.25, 0.5, 1.0}` ladder as\n  flat keywords.** Off-ladder weights on a group are clamped with a\n  validator warning, same as on flat keyword entries.\n\n---\n\n## 5. Footguns\n\nThese are the most common authoring mistakes, in roughly descending order\nof frequency.\n\n**`fnmatch *.py` does not match nested files.** Python's `fnmatch` matches\nonly within a single path component when the glob contains no path\nseparator. `*.py` matches `foo.py` but not `src\u002Ffoo.py`. Use `**\u002F*.py` if\nyou mean \"any `.py` file anywhere under the tree.\" This is the most common\npath-glob mistake and the one most likely to cause silent non-matching on\nreal inputs.\n\n**Tool names are case-sensitive.** The harness passes tool names with the\ncasing it uses internally: `Bash`, `Read`, `Edit`, `WebFetch`, `Glob`.\nLowercase variants like `bash` or `webfetch` will silently fail to match.\nWhen in doubt, check the tool name in the harness output rather than\nguessing the casing.\n\n**`applicable_skills: []` mutes the agent's skill attachment entirely.**\nSetting this to an empty list means the agent will never have any skill\nattached, regardless of how well those skills score against the input.\nOnly set `[]` when you genuinely want no skills auto-attached to this\nagent. The most common unintended form of this is inheriting a default\nempty list in a new agent sidecar template and forgetting to change it.\n\n**One-dimensional triggers are a calibration footgun (entry-side).**\nA routable agent or skill with only `keywords` and no `path_globs`,\n`tool_mentions`, or `command_prefixes` will score zero on any prompt that\ndoes not mention at least one of its specific keyword terms. Even on\nmatching prompts, the score is bounded by `+0.5 × weight` per hit,\nclamped at `1.0`. This is not the same as the input-side `needs_more_detail`\nfloor described in Section 2, which fires when the *user's prompt* is too\nthin. This is about the *entry* being weakly reachable across the distribution\nof prompts the matcher actually sees. The fix is to pair keywords with at\nleast one `path_globs`, `tool_mentions`, or `command_prefixes` entry, giving\nthe matcher a second scoring dimension to work with.\n\n**Flat `keywords` over-fire when terms only make sense together.** If your\nentry should match `\"open issue\"` but not `\"open file\"` or `\"recent issues\"`\nalone, flat keywords score each term independently and accumulate on\neither side firing alone. Use `keyword_groups` to require co-occurrence:\neach `slot` carries one set of alternatives, and the group fires only\nwhen **all** slots are satisfied. See the §3 worked example.\n\n**Conflict pairs produce `advisory` decisions.** Two entries whose\n`keywords` lists share three or more overlapping case-insensitive terms,\nwith no discriminating `path_globs`, `tool_mentions`, or\n`command_prefixes` to break the tie, will both score similarly on inputs\nthat mention those shared terms. The gap falls below 0.2, so neither\nreaches the `delegate` floor, and the matcher emits `advisory` — the top\nagent is suggested but not confirmed. (Prior to v0.9.0 this scenario\nproduced an `ambiguous` decision; that outcome was removed. The runtime\nnow emits `advisory` for all gap-tied and below-threshold cases.) Heavy\nkeyword overlap is a design smell. The remedy is to introduce a\ndiscriminator: a `path_globs` entry that is unique to one of the two\nentries, a `tool_mentions` entry that only one of them legitimately fires\non, or a `command_prefixes` entry that explicitly routes one of them. If\nthe overlap is fundamental — the two entries genuinely do the same thing\nin the same context — consider whether they should be merged into one.\n\n**Stemming can make two distinct terms collide silently.** Because matching\nis stem-vs-stem, two terms you intended to be different can collapse to the\nsame Porter2 stem and fire as one — `universe` and `university` both stem to\n`univers`, `operating` and `operate` both stem to `oper`. When that collision\nspans two competing catalog entries, it manufactures a conflict pair you did\nnot author by hand. The fix is either to accept the collision (often it is\nharmless) or to add `no_stem: true` to one of the terms so it matches\nverbatim. Run `python -m claude_wayfinder catalog build --check-stems` (see\n§ 9) to surface cross-entry stem collisions as `STEM_COLLISION` warnings\nbefore they reach the live catalog. Acronyms and product names are the most\ncommon over-stem casualties — prefer `no_stem: true` on those by default.\n\n---\n\n## 6. Authoring Workflow\n\nUse this workflow when writing trigger frontmatter for a new agent or skill\nfrom scratch.\n\n**Step 1 — Read the body in full.**\nOpen the agent or skill file and read it completely before writing a single\ntrigger. Triggers that are drafted from a one-line summary routinely miss\nthe recurring terminology the body actually uses.\n\n**Step 2 — Identify prominent terms and assign weights.**\nAs you read, note terms by how central they are to the entry's purpose:\n\n- The skill or agent **name**, or the core verb it acts on (e.g. `refactor`\n  for the refactoring agent, `dispatch` for the routing skill) → weight\n  `1.0`. At most one or two terms should sit here; if many terms seem equally\n  central, that is a sign the scope is too broad.\n- Recurring concept terms — vocabulary the body uses repeatedly and that\n  distinguishes this entry from neighboring ones → weight `0.5`.\n- Supporting or contextual terms — words that appear in the body and hint at\n  the use-case, but are not discriminating on their own → weight `0.25`.\n\nA well-calibrated entry typically has one or two `1.0` terms, three to five\n`0.5` terms, and a handful of `0.25` terms. If the `1.0` bucket is full of\ngeneric words (`code`, `file`, `run`) the entry will conflict with half the\ncatalog.\n\nList **base forms only** — terms are Porter2-stemmed, so `implement` already\ncovers `implementing` and `implemented` (see § 1 \"Stemming\"). Mark acronyms,\nproduct names, and CLI flags with `no_stem: true` so they are not over-stemmed\ninto a collision with another entry's term.\n\n**Step 3 — Add `path_globs` for any file patterns the body implies.**\nIf the body directs attention to specific file types or directory trees, add\na `path_globs` entry for each. Always use `**\u002F*.ext` for extension-based\npatterns (not `*.ext` — see the fnmatch footgun in Section 5). A\n`path_globs` entry adds `+0.4` per match and provides a second scoring\ndimension that significantly improves disambiguation against other entries\nwith similar keyword sets.\n\n**Step 4 — Add `tool_mentions` for any tools the body explicitly names.**\nIf the body tells the user to reach for a specific tool — `Bash`, `Edit`,\n`WebFetch`, etc. — list those tools in `tool_mentions`. Use the exact\ncasing the harness uses (capitalize the first letter; see the case-sensitive\nfootgun in Section 5).\n\n**Step 5 — Decide `applicable_skills` (for agents).**\nRead the body for skill-task language: verbs like \"plan\", \"test\", \"review\",\n\"debug\". List the skill names whose purpose aligns with those verbs in\n`applicable_skills`. Use `[\"*\"]` only if the agent is genuinely purpose-\nagnostic. Do not leave the field blank or set it to `[]` unless you\nintentionally want no skills attached.\n\n**Step 6 — Prefer the v6 sidecar location over inline frontmatter.**\nPlace the resulting YAML in the sidecar rather than embedding it in the\nagent or skill file's frontmatter block. Sidecars isolate trigger config\nfrom body copy, which makes diffs cleaner and code review faster. The\ncorrect paths are:\n\n- Owned skills: `skills\u002F\u003Cname>\u002Ftriggers.yml`\n- Plugin agents: `triggers\u002F\u003Cplugin>\u002Fagents\u002F\u003Cname>.yml`\n\nInline frontmatter is still read by the generator, but a sidecar at\nthe location above always overrides it.\n\n---\n\n## 7. Tuning Workflow\n\nUse this workflow when improving trigger frontmatter that already exists\nbut is producing poor match results.\n\n**Step 1 — Read the body and the current triggers side-by-side.**\nOpen both the sidecar (or inline frontmatter) and the agent or skill body\nat the same time. This side-by-side read is the only reliable way to spot\ndivergence between what the entry does and what the triggers say it does.\n\n**Step 2 — Find stale keywords.**\nLook for terms in `triggers.keywords` that no longer appear in the body.\nBodies change over time; triggers often do not. A stale keyword raises\nthe entry's score on inputs that no longer reflect its actual purpose,\ncreating misleading matches. Remove or replace stale terms.\n\n**Step 3 — Find missing keywords.**\nScan the body for recurring terms that are absent from `triggers.keywords`.\nIf a concept appears in every paragraph but is not listed as a keyword,\nthe entry will miss prompts that use that concept. Add the term at the\nweight level appropriate to how central it is.\n\n**Step 4 — Check weight alignment.**\nFor each existing keyword, ask whether its weight still reflects its\ncentrality to the body. The most common drift pattern is a term that was\nelevated to `1.0` during an early iteration and was never revisited as\nthe scope of the entry narrowed. A `1.0` weight that should be `0.5`\ninflates the score on prompts that mention that term even tangentially\nand widens conflict-pair risk.\n\n**Step 5 — Check conflict-pair risk.**\nEyeball the catalog for other entries that share several of the same\nkeywords. If two or more entries have three or more overlapping terms at\n`0.5` or `1.0` weight and no differentiating `path_globs` or\n`tool_mentions`, they will produce `advisory` decisions on the prompts\nwhere those terms overlap (the gap falls below 0.2, preventing `delegate`).\nIntroduce a discriminator (see Section 5) or run `audit-catalog`\n(see Section 9) to surface all conflict pairs at once.\n\n**Step 6 — Check for structural violations.**\nBefore committing, verify that:\n\n- Every `keywords` entry is a `{term, weight}` mapping, not a bare string.\n- Every weight is exactly one of `0.25`, `0.5`, or `1.0`.\n- No term contains leading or trailing whitespace (the generator does not\n  strip these; `\" python\"` and `\"python\"` are different terms).\n- `command_prefixes` entries each start with `\u002F`.\n- Acronyms, product names, and CLI flags carry `no_stem: true` so they are\n  not over-stemmed; run `python -m claude_wayfinder catalog build --check-stems`\n  to confirm no unintended cross-entry stem collisions were introduced.\n\n---\n\n## 8. Troubleshooting Workflow\n\nWhen an agent is not being dispatched or a skill is not attaching as\nexpected, work through the symptom table below to identify the cause.\n\n| Symptom | Likely cause |\n|---|---|\n| Routable agent scores 0 on prompts that should match | Unreachable routable: `triggers` is empty or every keyword weight is `0`. |\n| Score never crosses the delegation floor (`0.85`) | One-dimensional triggers — the entry has only `keywords` and no `path_globs` or `tool_mentions`; max reachable score is limited. |\n| Agent matches everything indiscriminately | Keyword set too generic (`code`, `file`, `run`); conflict-pair risk against many other entries. |\n| Skill never attaches to the expected agent | `applicable_agents` on the skill sidecar excludes that agent name; or `applicable_skills: []` on the agent sidecar mutes all skill attachment. |\n| Weight you set in the sidecar is not what the matcher uses | Non-ladder weight (e.g. `0.75`) was silently clamped to the nearest step; check `catalog-generation.log`. |\n| A specific term never contributes to the score | The term appears in the entry's own `excludes` list, zeroing the entry whenever it is present in the input. |\n| A `tool_mentions` entry never matches | Case mismatch — the harness passes `Bash`, not `bash`; `WebFetch`, not `webfetch`. Use the exact harness casing. |\n| A term matches inputs that share only a word stem (`university` firing on `universe`) | Porter2 over-stemming collapsed two distinct terms to one stem. Add `no_stem: true` to the term, or run `catalog build --check-stems` to find the collision (§ 1, § 5, § 9). |\n| An acronym \u002F product name matches unexpected inflections | The token was stemmed when it should be literal. Add `no_stem: true` to match it verbatim. |\n\n**Diagnostic sequence when none of the above is obvious:**\n\n1. Run `audit-catalog` (see Section 9) and check the output for\n   structural warnings on the entry.\n2. Compare the entry's trigger YAML against the schema in `docs\u002Fschema.md`\n   field by field.\n3. Check whether a sidecar overrides the inline frontmatter you edited —\n   both exist, the sidecar wins, and the edit may have gone to the wrong\n   file.\n4. Confirm the entry is marked `routable: true` (or that the key is absent,\n   which defaults to `true`). An explicit `routable: false` removes the\n   entry from the scored-agent pool entirely.\n\n---\n\n## 9. When to Run the CLI\n\n> The matcher-aware checks the LLM cannot do consistently across all ~70\n> catalog entries — conflict-pair detection, unreachable-routable scans,\n> structural validation across the whole catalog — live in\n> `python -m claude_wayfinder audit-catalog`. Run it whenever you add or\n> substantially edit a routable agent, before opening a PR that ships new\n> frontmatter, or as a periodic catalog sanity check. See\n> `docs\u002Fdispatch-authoring-guide.md` for the rule reference and exit-code\n> contract.\n\nThe CLI is the authoritative source for catalog-wide problems. It is not a\nsubstitute for the field-by-field checks in Sections 6 and 7, but it\ncatches conflict pairs and unreachable entries that would require reading\nthe full catalog by hand to detect otherwise.\n\n**Stem-collision pre-flight.** Run\n`python -m claude_wayfinder catalog build --check-stems` whenever you add or\nedit keyword terms. It detects pairs of distinct keyword terms — across\ndifferent catalog entries — that share the same Porter2 stem, printing each\nto stderr as a `STEM_COLLISION` line. Review each: accept the collision if\nit is harmless, or add `no_stem: true` to one of the terms to disambiguate\n(see the § 5 stemming footgun). This check is distinct from `audit-catalog`'s\nconflict-pair detection — a stem collision can manufacture a conflict pair\nthat the hand-authored keyword lists do not reveal on inspection.\n\n---\n\n## 10. References\n\n- `docs\u002Fschema.md` — canonical trigger field reference; start here when\n  looking up the exact name, type, or default for any trigger field.\n- `docs\u002Fdesign\u002Ftrigger-schema.md` — design rationale for the schema;\n  explains why certain field shapes were chosen and what alternatives were\n  considered.\n- `docs\u002Fdispatch-authoring-guide.md` — extended worked-examples companion\n  to this skill; covers edge cases and advanced calibration patterns not\n  addressed above.\n- `agent-authoring` skill (in `~\u002F.claude\u002Fskills\u002Fagent-authoring\u002F`) —\n  broader harness authoring discipline covering agent structure, routing\n  configuration, and the full lifecycle of a new agent; this\n  dispatch-authoring skill is its matcher-specific counterpart.\n","# Frontmatter Authoring Guide\n\nThis skill covers everything you need to write, improve, and troubleshoot\ntrigger frontmatter for claude-wayfinder agents and skills. It explains\nwhat fields the matcher reads, how scoring works, the seven routing\ndecisions the matcher can produce, and the most common mistakes that cause\nan entry to match poorly or never match at all.\n\n---\n\n## 1. What the Matcher Consumes\n\n### Source precedence\n\nThe catalog generator accepts trigger configuration from two places: inline\nfrontmatter inside the agent or skill file itself, and a **sidecar file**\nplaced next to the main file. The sidecar always wins when both are present.\n\nThe current sidecar format is **v6**. Under v6:\n\n- A **skill** stores its trigger configuration in a file named `triggers.yml`\n  placed in the same directory as `SKILL.md`:\n\n  ```\n  skills\u002Fpython\u002FSKILL.md\n  skills\u002Fpython\u002Ftriggers.yml   ← authoritative trigger config\n  ```\n\n  Per issue #150, a colocated `\u003Cname>.triggers.yml` next to `SKILL.md`\n  (owned and project agent sidecars) overrides inline frontmatter. The\n  `SKILL.md` file itself should not contain `triggers:`,\n  `applicable_agents:`, or `applicable_skills:` keys; the generator emits\n  a warning and ignores them if they appear there.\n\n- A **plugin-shipped agent** stores its trigger override at\n  `triggers\u002F\u003Cplugin>\u002Fagents\u002F\u003Cname>.yml` (per issue #142). This file\n  activates a dormant plugin agent that would otherwise score zero.\n\nFor the canonical field reference see `docs\u002Fschema.md`. For the design\ndiscussion behind the sidecar approach see `docs\u002Fdesign\u002Ftrigger-schema.md`.\n\n### Schema fields\n\n| Field | Where it lives | Purpose |\n|---|---|---|\n| `command_prefixes` | `triggers:` block | Slash commands that immediately short-circuit to score `1.0`. |\n| `agent_mentions` | `triggers:` block | Agent names whose explicit mention in the prompt immediately short-circuits to score `1.0`. |\n| `path_globs` | `triggers:` block | `fnmatch`-style globs matched against the `file_paths` dimension of the input. Each matched glob adds `0.4` to the score. |\n| `keywords` | `triggers:` block | List of `{term, weight}` mappings. Each term found in the input keywords adds `0.5 × weight` to the score. Terms are Porter2-stemmed unless `no_stem: true` is set (see § 1 \"Stemming\"). |\n| `no_stem` | per-keyword flag | Optional `no_stem: true` on a `{term, weight}` mapping exempts that term from stemming — it matches the raw (unstemmed) input token verbatim. Use for acronyms, product names, and CLI flags (`aws`, `gh`, `ps1`). |\n| `keyword_groups` | `triggers:` block | **AND-group conjunctive triggers** (added v0.6.0, #135). List of `{slots: [{name, terms: [...]}, ...], weight}` groups. A group fires only when **all** of its slots match — each slot must have ≥ 1 of its terms present in the input keywords. On match, the group adds `1.0 × weight` (via `_GROUP_MULTIPLIER`, distinct from the `0.5` `_KEYWORD_MULTIPLIER` so a satisfied weight-1.0 group can solo-decide `delegate`). Use when a routing decision should require co-occurrence of two or more terms (e.g. verb + noun) rather than either alone. |\n| `tool_mentions` | `triggers:` block | Tool names matched against the input `tool_mentions` dimension. Each match adds `0.5`. |\n| `excludes` | `triggers:` block | Terms that hard-zero the entry's score when found in the input keywords. |\n| `applicable_agents` | skill sidecar top-level | Hard allowlist of agent names that may receive this skill. `[\"*\"]` means any agent. `[]` means no agent — the skill is dormant. |\n| `applicable_skills` | agent sidecar top-level | Hard allowlist of skill names to attach when routing to this agent. `[\"*\"]` means any. `[]` means no skills. |\n| `routable` | agent frontmatter top-level | When `false`, the agent is excluded from the scored-agent pool. Set to `false` on the router itself so it is never selected as a delegation target. Absent on skill entries. |\n\n### How each field type feeds the matcher\n\n`command_prefixes` and `agent_mentions` are checked before any additive\nscoring begins — a match on either field returns `1.0` immediately without\nexamining any other field. `excludes` is also a pre-scoring check: a match\nzeroes the entry and stops further evaluation.\n\n`path_globs`, `keywords`, and `tool_mentions` contribute additively to a\nrunning score that is capped at `1.0` before being returned. An entry\nwith no triggers in any of these three fields will score `0.0` on any\nprompt that does not happen to name the entry directly by command prefix\nor agent mention.\n\n### Stemming (symmetric Porter2, issue #304)\n\nThe matcher applies **symmetric Porter2 (Snowball English) stemming** to\nkeyword matching. Catalog terms are stemmed at catalog-build time; input\ntokens are stemmed at dispatch time; matching is stem-vs-stem. The practical\nconsequence for authors: **list the base form only — you do not need to\nenumerate inflections.** `implement` matches `implementing` and\n`implemented`; `refactor` matches `refactored`; `lint` matches `linting`.\n\nThis applies to flat `keywords` terms and to `keyword_groups` slot terms\nalike. Two distinct catalog terms that collapse to the same stem are\ndeduped at parse time so a single input token cannot double-count.\n\n**`no_stem` opt-out.** Add `no_stem: true` to a `{term, weight}` mapping to\nexempt that term from stemming. A `no_stem` term is matched verbatim against\nthe raw (unstemmed) input token. Use it for tokens that must not collapse —\nacronyms, product names, and CLI flags:\n\n```yaml\ntriggers:\n  keywords:\n    - { term: \"deploy\", weight: 1.0 }                 # stemmed: matches \"deploying\", \"deployed\"\n    - { term: \"aws\", weight: 1.0, no_stem: true }     # exact: matches \"aws\" only\n    - { term: \"gh\", weight: 0.5, no_stem: true }      # exact: matches \"gh\" only\n```\n\nStemming changes nothing about the scoring formula or thresholds — it only\nchanges which input tokens count as a match. See `docs\u002Fdispatch-authoring-guide.md`\nfor the canonical reference, and § 9 for the `--check-stems` collision\npre-flight.\n\n---\n\n## 2. The Seven-Decision Ladder\n\nThe matcher evaluates the catalog against the input features and emits\nexactly one of seven decisions. The ladder is evaluated in order; the\nfirst branch whose conditions are satisfied wins.\n\n1. **`needs_more_detail`** — the input's extracted features populate fewer\n   than two distinct dimensions (paths, keywords, tools, command prefixes,\n   agent mentions); the matcher did not attempt to score the catalog at all.\n\n2. **`delegate`** — one routable agent scored ≥ 0.85 and its gap above\n   the second-place agent is ≥ 0.2; high-confidence single winner,\n   delegation is appropriate.\n\n3. **`self_handle`** — no dominant agent, but at least one skill scored\n   ≥ 0.5; the router handles the task itself with the matched skills\n   attached.\n\n4. **`mixed_content`** — the gap between the top two agents is \u003C 0.2 and\n   ≥ 2 agents are each clamped at 1.0 on path-disjoint lanes (every\n   qualifying agent has at least one path-glob match, and no input path\n   is claimed by more than one agent). The decision carries a `lanes[]`\n   array (one entry per specialist, each with `agent`, `score`,\n   `matched_paths`, and `skills`) and an `unassigned_paths[]` list for\n   input paths not claimed by any lane. Fires after `self_handle` and\n   before `advisory`.\n\n5. **`advisory`** — the best agent scored ≥ 0.5 but the `delegate`\n   threshold was not met (gap \u003C 0.2 or score \u003C 0.85) and `mixed_content`\n   conditions were not satisfied; delegation is suggested but not certain.\n\n6. **`ask_user`** — reserved in v0.1 and v0.2; the current matcher never\n   produces this decision. Include a handler for forward compatibility.\n\n7. **`self_handle_unaided`** — no agent and no skill scored above\n   threshold; the router proceeds without delegation or skill attachment.\n\n### Input-side density floor vs. entry-side weak scoring\n\nThese are two separate concerns. Conflating them leads to incorrect\ndiagnosis when an entry fails to match.\n\n**Input-side density floor (the `needs_more_detail` branch above).**\nThe matcher emits `needs_more_detail` when the *user prompt's* extracted\n`Features` populate fewer than two dimensions — paths, keywords, tools,\ncommand prefixes, or agent mentions. This is a property of how thin the\n*input* is, not of how thin any catalog entry's triggers are. A two-word\nprompt with no file paths and no recognised keywords triggers this branch\nregardless of how rich the catalog is. The fix is to provide a richer\nprompt, not to change the entry's triggers.\n\n**Entry-side weak scoring (a calibration footgun — see Section 5).**\nAn entry whose triggers populate only one dimension — for example\nkeywords-only with no `path_globs`, `tool_mentions`, or\n`command_prefixes` — will score weakly on most inputs, because it can\nonly accumulate score when the input happens to mention one of its\nspecific terms. This is not an unreachability theorem; the entry *can*\nscore if the input fills its one dimension. But it is a calibration\nsmell: the score ceiling on matching inputs is limited (`+0.5 × weight`\nper keyword hit, clamped at `1.0`), and any prompt that doesn't mention\none of the entry's specific terms scores it at zero. Section 5 elaborates\nthe practical guidance.\n\n---\n\n## 3. Scoring Math\n\nThe matcher computes a per-entry score using the following rules, applied\nin order. Short-circuits fire before any additive contribution is\ncalculated.\n\n**Short-circuit rules (evaluated first, in this order):**\n\n- `command_prefixes` match → score = `1.0` immediately.\n- `agent_mentions` match → score = `1.0` immediately.\n- `excludes` match in `features.keywords` → score = `0.0` immediately.\n\n**Additive scoring (when no short-circuit fired):**\n\n- Per `path_globs` match: `+0.4`\n- Per `keywords` match: `+0.5 × weight` (verified at\n  `src\u002Fclaude_wayfinder\u002Fmatch.py:84` — `_KEYWORD_MULTIPLIER = 0.5`;\n  raised from 0.3 to fix single-keyword skills never attaching)\n- Per `keyword_groups` match: `+1.0 × weight` per group that fires\n  (a group fires only when **all** of its slots are satisfied;\n  `_GROUP_MULTIPLIER = 1.0` is deliberately distinct from\n  `_KEYWORD_MULTIPLIER = 0.5` so a satisfied weight-1.0 group can\n  solo-decide `delegate`; #135 \u002F v0.6.0)\n- Per `tool_mentions` match: `+0.5`\n\nThe final additive score is **clamped to `1.0`** before being returned.\n\n### AND-group worked example\n\nAn entry has a `keyword_groups` block requiring both a \"verb\" and a \"noun\"\nto co-occur:\n\n```yaml\nkeyword_groups:\n  - slots:\n      - {name: verbs, terms: [create, open, file]}\n      - {name: nouns, terms: [issue, ticket, bug]}\n    weight: 1.0\n```\n\n| Prompt                              | verbs slot | nouns slot | Group fires? | Score from this group |\n| ----------------------------------- | :---------: | :---------: | :-----------: | --------------------: |\n| \"open the issue tracker\"            |     ✓       |     ✓       |     yes       |  `+1.0 × 1.0 = +1.0`  |\n| \"create the issue body\"             |     ✓       |     ✓       |     yes       |  `+1.0`               |\n| \"open the file\"                     |     ✓       |     ✗       |     no        |  `+0.0`               |\n| \"tell me about issues\"              |     ✗       |     ✓       |     no        |  `+0.0`               |\n\nA satisfied weight-`1.0` group contributes `1.0` to the entry — enough to\nclamp at the ceiling on its own and solo-decide `delegate` if the gap to\nthe runner-up is ≥ `0.2`. That is the design intent of\n`_GROUP_MULTIPLIER = 1.0`: a group is a stronger signal than any single\nflat keyword (which maxes at `+0.5`) because the group already encodes\nco-occurrence — the matcher has more evidence that the prompt intends\nthis entry, so the score reflects that.\n\nThe flat-`keywords` equivalent of the same term lists would score on\neither side firing alone — scoring `+0.5 × weight` on \"open the file\" and\n\"tell me about issues\" too, since each individual term contributes\nindependently. The AND-group structurally requires co-occurrence, which\nis the right shape when the trigger only makes sense for the combined\nintent.\n\n### Worked example\n\nAn entry has one `path_globs` entry (`**\u002F*.py`) and one `keywords` entry\n(`python`, weight `1.0`). For a prompt that mentions a `.py` file and\nthe word \"python\":\n\n```\npath_glob match:   +0.4\nkeyword match:     +0.5 × 1.0 = +0.5\ntotal:              0.9   (below 1.0, no clamping needed)\n```\n\nA score of `0.9` with a gap ≥ 0.2 above the second-place entry would\nyield a `delegate` decision.\n\n### Clamping footgun\n\nBecause the final score is hard-clamped at `1.0`, stacking additional\nhigh-weight keywords past the ceiling adds nothing. Consider an entry\nwith one path-glob hit (`+0.4`) and two weight-`1.0` keyword hits\n(`+0.5` + `+0.5`): the additive total is `1.4`, which clamps to `1.0` —\nexactly the same as one path-glob plus one weight-`1.0` keyword. The\nsecond high-weight keyword is dead weight on any input that already\ncrosses the ceiling.\n\nThe practical guidance: once an entry can plausibly reach `≥ 1.0` on its\nhighest-signal inputs, prefer broadening *coverage* — add more distinct\nterms at `0.25` or `0.5` weight — over stacking duplicate `1.0` weights.\nBroadening raises the score on a wider range of inputs; stacking only\ninflates the sum on the inputs where the ceiling would already be hit,\nand the clamp throws that extra score away.\n\n---\n\n## 4. Trigger Field Rules\n\nThese are the validation rules the catalog generator enforces. Violating\nthem produces a warning at build time and may cause the entry to score\nunexpectedly.\n\n- **Weight ladder is exactly `{0.25, 0.5, 1.0}`.** Any other numeric value\n  is clamped to the nearest ladder step with a validator warning (see\n  `_clamp_weight` in `build_catalog.py`). There is no weight of `0.75`,\n  `0.3`, or `2.0`.\n\n- **`keywords` is a list of `{term, weight}` mappings.** Bare strings are\n  rejected by the generator. Every keyword entry must be an object with\n  exactly two keys: `term` (a string) and `weight` (one of `0.25`,\n  `0.5`, `1.0`).\n\n- **Keyword terms are Porter2-stemmed unless `no_stem: true`.** List base\n  forms; stemming matches inflections automatically (see § 1 \"Stemming\").\n  Set `no_stem: true` on terms that must match verbatim — acronyms, product\n  names, CLI flags. A `no_stem` term is compared against the raw input token,\n  not its stem. Authoring inflected variants of a stemmed term (`deploy`,\n  `deploying`, `deployed`) is redundant — they all collapse to one stem and\n  are deduped.\n\n- **`path_globs` uses Python `fnmatch` semantics, not gitignore semantics.**\n  The matcher calls `fnmatch.fnmatch(path, glob)`. This has important\n  consequences — see the footguns section for the most common mistake.\n\n- **`tool_mentions` is case-sensitive.** The matcher compares tool names as\n  literal strings. `Bash` and `bash` are different values; the correct\n  casing matches what the Claude Code harness uses. Wrong case silently\n  fails to match.\n\n- **`excludes` matches against `features.keywords` only.** The `excludes`\n  list is not checked against `file_paths`, `tool_mentions`, or\n  `agent_mentions`. An exclude term that appears only in a file path will\n  not zero the score.\n\n- **`command_prefixes` should start with `\u002F`.** A prefix like `dispatch`\n  without a leading slash will not match a user-typed `\u002Fdispatch` command,\n  because the dispatcher passes the slash as part of the string.\n\n- **`keyword_groups` requires ≥ 2 slots per group.** A single-slot group is\n  semantically equivalent to a flat `keywords` entry — the catalog\n  generator warns and drops single-slot groups. Use plain `keywords`\n  instead when you only want one set of alternatives. Each slot needs a\n  non-empty `terms` list; empty `terms` makes the slot unsatisfiable and\n  drops the group.\n\n- **`keyword_groups` weights follow the same `{0.25, 0.5, 1.0}` ladder as\n  flat keywords.** Off-ladder weights on a group are clamped with a\n  validator warning, same as on flat keyword entries.\n\n---\n\n## 5. Footguns\n\nThese are the most common authoring mistakes, in roughly descending order\nof frequency.\n\n**`fnmatch *.py` does not match nested files.** Python's `fnmatch` matches\nonly within a single path component when the glob contains no path\nseparator. `*.py` matches `foo.py` but not `src\u002Ffoo.py`. Use `**\u002F*.py` if\nyou mean \"any `.py` file anywhere under the tree.\" This is the most common\npath-glob mistake and the one most likely to cause silent non-matching on\nreal inputs.\n\n**Tool names are case-sensitive.** The harness passes tool names with the\ncasing it uses internally: `Bash`, `Read`, `Edit`, `WebFetch`, `Glob`.\nLowercase variants like `bash` or `webfetch` will silently fail to match.\nWhen in doubt, check the tool name in the harness output rather than\nguessing the casing.\n\n**`applicable_skills: []` mutes the agent's skill attachment entirely.**\nSetting this to an empty list means the agent will never have any skill\nattached, regardless of how well those skills score against the input.\nOnly set `[]` when you genuinely want no skills auto-attached to this\nagent. The most common unintended form of this is inheriting a default\nempty list in a new agent sidecar template and forgetting to change it.\n\n**One-dimensional triggers are a calibration footgun (entry-side).**\nA routable agent or skill with only `keywords` and no `path_globs`,\n`tool_mentions`, or `command_prefixes` will score zero on any prompt that\ndoes not mention at least one of its specific keyword terms. Even on\nmatching prompts, the score is bounded by `+0.5 × weight` per hit,\nclamped at `1.0`. This is not the same as the input-side `needs_more_detail`\nfloor described in Section 2, which fires when the *user's prompt* is too\nthin. This is about the *entry* being weakly reachable across the distribution\nof prompts the matcher actually sees. The fix is to pair keywords with at\nleast one `path_globs`, `tool_mentions`, or `command_prefixes` entry, giving\nthe matcher a second scoring dimension to work with.\n\n**Flat `keywords` over-fire when terms only make sense together.** If your\nentry should match `\"open issue\"` but not `\"open file\"` or `\"recent issues\"`\nalone, flat keywords score each term independently and accumulate on\neither side firing alone. Use `keyword_groups` to require co-occurrence:\neach `slot` carries one set of alternatives, and the group fires only\nwhen **all** slots are satisfied. See the §3 worked example.\n\n**Conflict pairs produce `advisory` decisions.** Two entries whose\n`keywords` lists share three or more overlapping case-insensitive terms,\nwith no discriminating `path_globs`, `tool_mentions`, or\n`command_prefixes` to break the tie, will both score similarly on inputs\nthat mention those shared terms. The gap falls below 0.2, so neither\nreaches the `delegate` floor, and the matcher emits `advisory` — the top\nagent is suggested but not confirmed. (Prior to v0.9.0 this scenario\nproduced an `ambiguous` decision; that outcome was removed. The runtime\nnow emits `advisory` for all gap-tied and below-threshold cases.) Heavy\nkeyword overlap is a design smell. The remedy is to introduce a\ndiscriminator: a `path_globs` entry that is unique to one of the two\nentries, a `tool_mentions` entry that only one of them legitimately fires\non, or a `command_prefixes` entry that explicitly routes one of them. If\nthe overlap is fundamental — the two entries genuinely do the same thing\nin the same context — consider whether they should be merged into one.\n\n**Stemming can make two distinct terms collide silently.** Because matching\nis stem-vs-stem, two terms you intended to be different can collapse to the\nsame Porter2 stem and fire as one — `universe` and `university` both stem to\n`univers`, `operating` and `operate` both stem to `oper`. When that collision\nspans two competing catalog entries, it manufactures a conflict pair you did\nnot author by hand. The fix is either to accept the collision (often it is\nharmless) or to add `no_stem: true` to one of the terms so it matches\nverbatim. Run `python -m claude_wayfinder catalog build --check-stems` (see\n§ 9) to surface cross-entry stem collisions as `STEM_COLLISION` warnings\nbefore they reach the live catalog. Acronyms and product names are the most\ncommon over-stem casualties — prefer `no_stem: true` on those by default.\n\n---\n\n## 6. Authoring Workflow\n\nUse this workflow when writing trigger frontmatter for a new agent or skill\nfrom scratch.\n\n**Step 1 — Read the body in full.**\nOpen the agent or skill file and read it completely before writing a single\ntrigger. Triggers that are drafted from a one-line summary routinely miss\nthe recurring terminology the body actually uses.\n\n**Step 2 — Identify prominent terms and assign weights.**\nAs you read, note terms by how central they are to the entry's purpose:\n\n- The skill or agent **name**, or the core verb it acts on (e.g. `refactor`\n  for the refactoring agent, `dispatch` for the routing skill) → weight\n  `1.0`. At most one or two terms should sit here; if many terms seem equally\n  central, that is a sign the scope is too broad.\n- Recurring concept terms — vocabulary the body uses repeatedly and that\n  distinguishes this entry from neighboring ones → weight `0.5`.\n- Supporting or contextual terms — words that appear in the body and hint at\n  the use-case, but are not discriminating on their own → weight `0.25`.\n\nA well-calibrated entry typically has one or two `1.0` terms, three to five\n`0.5` terms, and a handful of `0.25` terms. If the `1.0` bucket is full of\ngeneric words (`code`, `file`, `run`) the entry will conflict with half the\ncatalog.\n\nList **base forms only** — terms are Porter2-stemmed, so `implement` already\ncovers `implementing` and `implemented` (see § 1 \"Stemming\"). Mark acronyms,\nproduct names, and CLI flags with `no_stem: true` so they are not over-stemmed\ninto a collision with another entry's term.\n\n**Step 3 — Add `path_globs` for any file patterns the body implies.**\nIf the body directs attention to specific file types or directory trees, add\na `path_globs` entry for each. Always use `**\u002F*.ext` for extension-based\npatterns (not `*.ext` — see the fnmatch footgun in Section 5). A\n`path_globs` entry adds `+0.4` per match and provides a second scoring\ndimension that significantly improves disambiguation against other entries\nwith similar keyword sets.\n\n**Step 4 — Add `tool_mentions` for any tools the body explicitly names.**\nIf the body tells the user to reach for a specific tool — `Bash`, `Edit`,\n`WebFetch`, etc. — list those tools in `tool_mentions`. Use the exact\ncasing the harness uses (capitalize the first letter; see the case-sensitive\nfootgun in Section 5).\n\n**Step 5 — Decide `applicable_skills` (for agents).**\nRead the body for skill-task language: verbs like \"plan\", \"test\", \"review\",\n\"debug\". List the skill names whose purpose aligns with those verbs in\n`applicable_skills`. Use `[\"*\"]` only if the agent is genuinely purpose-\nagnostic. Do not leave the field blank or set it to `[]` unless you\nintentionally want no skills attached.\n\n**Step 6 — Prefer the v6 sidecar location over inline frontmatter.**\nPlace the resulting YAML in the sidecar rather than embedding it in the\nagent or skill file's frontmatter block. Sidecars isolate trigger config\nfrom body copy, which makes diffs cleaner and code review faster. The\ncorrect paths are:\n\n- Owned skills: `skills\u002F\u003Cname>\u002Ftriggers.yml`\n- Plugin agents: `triggers\u002F\u003Cplugin>\u002Fagents\u002F\u003Cname>.yml`\n\nInline frontmatter is still read by the generator, but a sidecar at\nthe location above always overrides it.\n\n---\n\n## 7. Tuning Workflow\n\nUse this workflow when improving trigger frontmatter that already exists\nbut is producing poor match results.\n\n**Step 1 — Read the body and the current triggers side-by-side.**\nOpen both the sidecar (or inline frontmatter) and the agent or skill body\nat the same time. This side-by-side read is the only reliable way to spot\ndivergence between what the entry does and what the triggers say it does.\n\n**Step 2 — Find stale keywords.**\nLook for terms in `triggers.keywords` that no longer appear in the body.\nBodies change over time; triggers often do not. A stale keyword raises\nthe entry's score on inputs that no longer reflect its actual purpose,\ncreating misleading matches. Remove or replace stale terms.\n\n**Step 3 — Find missing keywords.**\nScan the body for recurring terms that are absent from `triggers.keywords`.\nIf a concept appears in every paragraph but is not listed as a keyword,\nthe entry will miss prompts that use that concept. Add the term at the\nweight level appropriate to how central it is.\n\n**Step 4 — Check weight alignment.**\nFor each existing keyword, ask whether its weight still reflects its\ncentrality to the body. The most common drift pattern is a term that was\nelevated to `1.0` during an early iteration and was never revisited as\nthe scope of the entry narrowed. A `1.0` weight that should be `0.5`\ninflates the score on prompts that mention that term even tangentially\nand widens conflict-pair risk.\n\n**Step 5 — Check conflict-pair risk.**\nEyeball the catalog for other entries that share several of the same\nkeywords. If two or more entries have three or more overlapping terms at\n`0.5` or `1.0` weight and no differentiating `path_globs` or\n`tool_mentions`, they will produce `advisory` decisions on the prompts\nwhere those terms overlap (the gap falls below 0.2, preventing `delegate`).\nIntroduce a discriminator (see Section 5) or run `audit-catalog`\n(see Section 9) to surface all conflict pairs at once.\n\n**Step 6 — Check for structural violations.**\nBefore committing, verify that:\n\n- Every `keywords` entry is a `{term, weight}` mapping, not a bare string.\n- Every weight is exactly one of `0.25`, `0.5`, or `1.0`.\n- No term contains leading or trailing whitespace (the generator does not\n  strip these; `\" python\"` and `\"python\"` are different terms).\n- `command_prefixes` entries each start with `\u002F`.\n- Acronyms, product names, and CLI flags carry `no_stem: true` so they are\n  not over-stemmed; run `python -m claude_wayfinder catalog build --check-stems`\n  to confirm no unintended cross-entry stem collisions were introduced.\n\n---\n\n## 8. Troubleshooting Workflow\n\nWhen an agent is not being dispatched or a skill is not attaching as\nexpected, work through the symptom table below to identify the cause.\n\n| Symptom | Likely cause |\n|---|---|\n| Routable agent scores 0 on prompts that should match | Unreachable routable: `triggers` is empty or every keyword weight is `0`. |\n| Score never crosses the delegation floor (`0.85`) | One-dimensional triggers — the entry has only `keywords` and no `path_globs` or `tool_mentions`; max reachable score is limited. |\n| Agent matches everything indiscriminately | Keyword set too generic (`code`, `file`, `run`); conflict-pair risk against many other entries. |\n| Skill never attaches to the expected agent | `applicable_agents` on the skill sidecar excludes that agent name; or `applicable_skills: []` on the agent sidecar mutes all skill attachment. |\n| Weight you set in the sidecar is not what the matcher uses | Non-ladder weight (e.g. `0.75`) was silently clamped to the nearest step; check `catalog-generation.log`. |\n| A specific term never contributes to the score | The term appears in the entry's own `excludes` list, zeroing the entry whenever it is present in the input. |\n| A `tool_mentions` entry never matches | Case mismatch — the harness passes `Bash`, not `bash`; `WebFetch`, not `webfetch`. Use the exact harness casing. |\n| A term matches inputs that share only a word stem (`university` firing on `universe`) | Porter2 over-stemming collapsed two distinct terms to one stem. Add `no_stem: true` to the term, or run `catalog build --check-stems` to find the collision (§ 1, § 5, § 9). |\n| An acronym \u002F product name matches unexpected inflections | The token was stemmed when it should be literal. Add `no_stem: true` to match it verbatim. |\n\n**Diagnostic sequence when none of the above is obvious:**\n\n1. Run `audit-catalog` (see Section 9) and check the output for\n   structural warnings on the entry.\n2. Compare the entry's trigger YAML against the schema in `docs\u002Fschema.md`\n   field by field.\n3. Check whether a sidecar overrides the inline frontmatter you edited —\n   both exist, the sidecar wins, and the edit may have gone to the wrong\n   file.\n4. Confirm the entry is marked `routable: true` (or that the key is absent,\n   which defaults to `true`). An explicit `routable: false` removes the\n   entry from the scored-agent pool entirely.\n\n---\n\n## 9. When to Run the CLI\n\n> The matcher-aware checks the LLM cannot do consistently across all ~70\n> catalog entries — conflict-pair detection, unreachable-routable scans,\n> structural validation across the whole catalog — live in\n> `python -m claude_wayfinder audit-catalog`. Run it whenever you add or\n> substantially edit a routable agent, before opening a PR that ships new\n> frontmatter, or as a periodic catalog sanity check. See\n> `docs\u002Fdispatch-authoring-guide.md` for the rule reference and exit-code\n> contract.\n\nThe CLI is the authoritative source for catalog-wide problems. It is not a\nsubstitute for the field-by-field checks in Sections 6 and 7, but it\ncatches conflict pairs and unreachable entries that would require reading\nthe full catalog by hand to detect otherwise.\n\n**Stem-collision pre-flight.** Run\n`python -m claude_wayfinder catalog build --check-stems` whenever you add or\nedit keyword terms. It detects pairs of distinct keyword terms — across\ndifferent catalog entries — that share the same Porter2 stem, printing each\nto stderr as a `STEM_COLLISION` line. Review each: accept the collision if\nit is harmless, or add `no_stem: true` to one of the terms to disambiguate\n(see the § 5 stemming footgun). This check is distinct from `audit-catalog`'s\nconflict-pair detection — a stem collision can manufacture a conflict pair\nthat the hand-authored keyword lists do not reveal on inspection.\n\n---\n\n## 10. References\n\n- `docs\u002Fschema.md` — canonical trigger field reference; start here when\n  looking up the exact name, type, or default for any trigger field.\n- `docs\u002Fdesign\u002Ftrigger-schema.md` — design rationale for the schema;\n  explains why certain field shapes were chosen and what alternatives were\n  considered.\n- `docs\u002Fdispatch-authoring-guide.md` — extended worked-examples companion\n  to this skill; covers edge cases and advanced calibration patterns not\n  addressed above.\n- `agent-authoring` skill (in `~\u002F.claude\u002Fskills\u002Fagent-authoring\u002F`) —\n  broader harness authoring discipline covering agent structure, routing\n  configuration, and the full lifecycle of a new agent; this\n  dispatch-authoring skill is its matcher-specific counterpart.\n",{"name":5,"description":7},"main","e906955a5bf962247a87d755ae63495538ce36b5","skills\u002Fdispatch-authoring",1,"https:\u002F\u002Fgithub.com\u002Fglitchwerks\u002Fclaude-wayfinder","https:\u002F\u002Fpypi.org\u002Fproject\u002Fclaude-wayfinder\u002F","https:\u002F\u002Fgithub.com\u002Fglitchwerks","2026-11-14 06:56:04",{"source":8,"skillName":5,"commands":32,"prompt":42,"zipAvailable":43},[33,36,39],{"tool":34,"command":35},"npx","npx skills add glitchwerks\u002Fclaude-wayfinder --skill dispatch-authoring",{"tool":37,"command":38},"bunx","bunx skills add glitchwerks\u002Fclaude-wayfinder --skill dispatch-authoring",{"tool":40,"command":41},"pnpm","pnpm dlx skills add glitchwerks\u002Fclaude-wayfinder --skill dispatch-authoring","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fglitchwerks\u002Fclaude-wayfinder\u002Fblob\u002Fmain\u002Fskills\u002Fdispatch-authoring\u002FSKILL.md",true,[45],{"path":46,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":49,"sourceHtmlUrl":50},"triggers.yml","REFERENCE","参考文档",599,"https:\u002F\u002Fgithub.com\u002Fglitchwerks\u002Fclaude-wayfinder\u002Fblob\u002Fmain\u002Fskills\u002Fdispatch-authoring\u002Ftriggers.yml",[52,59,66,73,79,86],{"skillNo":53,"name":54,"nameZh":6,"description":55,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":56,"categories":57,"keywords":58,"publishedAt":18},"01M72V35HRZHT8N6NZWAGY4CDS","refactoring-discipline","Behavior-preserving refactoring discipline. Activates when the task involves restructuring, extracting, or renaming existing code without adding new behavior.","https:\u002F\u002Fgithub.com\u002Fglitchwerks\u002Fclaude-wayfinder\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fskills\u002Frefactoring-discipline\u002FSKILL.md",[],[],{"skillNo":60,"name":61,"nameZh":6,"description":62,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":63,"categories":64,"keywords":65,"publishedAt":18},"01M72V33XS39XGHFYH5RM0HSW3","legacy","Pre-migration skill.","https:\u002F\u002Fgithub.com\u002Fglitchwerks\u002Fclaude-wayfinder\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fskills\u002Flegacy\u002FSKILL.md",[],[],{"skillNo":67,"name":68,"nameZh":6,"description":69,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":70,"categories":71,"keywords":72,"publishedAt":18},"01M72V289JXSDJBQK1GW5RCJAP","csv-utils","Helpers for reading and writing CSV files in Python.","https:\u002F\u002Fgithub.com\u002Fglitchwerks\u002Fclaude-wayfinder\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fskills\u002Fcsv-utils\u002FSKILL.md",[],[],{"skillNo":74,"name":75,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":76,"categories":77,"keywords":78,"publishedAt":18},"01M72V1GJFXNZ8CVZZG8T66E3G","broken","https:\u002F\u002Fgithub.com\u002Fglitchwerks\u002Fclaude-wayfinder\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fskills\u002Fbroken\u002FSKILL.md",[],[],{"skillNo":80,"name":81,"nameZh":6,"description":82,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":83,"categories":84,"keywords":85,"publishedAt":18},"01M72V0SWXW4XJE2EWCZWM5EDP","agent-authoring","Expert guidance for writing, editing, and debugging agent and skill frontmatter, CLAUDE.md harness rules, and SKILL.md files.","https:\u002F\u002Fgithub.com\u002Fglitchwerks\u002Fclaude-wayfinder\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fskills\u002Fagent-authoring\u002FSKILL.md",[],[],{"skillNo":87,"name":88,"nameZh":6,"description":89,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":90,"categories":91,"keywords":92,"publishedAt":18},"01M72V00NQ401XMPQZV0PH01J3","setup-wayfinder","Materialize the claude-wayfinder Python venv at ${CLAUDE_PLUGIN_DATA}\u002Fvenv\u002F\nand write the setup-state flag. Use when:\n- User types \u002Fsetup-wayfinder\n- User says \"set up claude-wayfinder\", \"install wayfinder dependencies\"\n- User says \"wayfinder isn't working\", \"fix wayfinder\", \"repair wayfinder\"\n- SessionStart banner indicates setup is required and the user wants to proceed\n- Plugin version bumped and re-setup needed\nDo NOT trigger on casual mentions of \"wayfinder\" without setup\u002Finstall\u002Ffix intent.","https:\u002F\u002Fgithub.com\u002Fglitchwerks\u002Fclaude-wayfinder\u002Fblob\u002Fmain\u002Fskills\u002Fsetup-wayfinder\u002FSKILL.md",[],[]]