Skill Taxonomy And Routing
Inputs
| Input |
Source/provider |
If absent |
| Live active-skill inventory, candidate skill/reference, and neighbouring descriptions |
Filesystem and change request |
Stop taxonomy changes and rediscover the catalogue. |
| Routing fixtures and alias/migration records |
Repository |
Mark collision and compatibility checks unassessed. |
Capability Contract
Taxonomy analysis defaults to read-only. Renaming, moving, deactivating, deleting, or changing routers and aliases requires explicit repository authority and migration evidence.
Degraded Mode
If the live catalogue, neighbouring descriptions, or routing fixtures are unavailable, return candidate placement and collision risks without changing taxonomy. Do not declare a route collision-free.
Decision Rules
| Choice |
Action |
Failure/risk avoided |
| Capability has distinct triggers and workflow |
Keep or create a skill |
Hidden specialist behaviour |
| Material only deepens an existing workflow |
Store it as a linked reference |
Catalogue fragmentation |
| Names or triggers overlap |
Tighten descriptions and negative triggers |
Ambiguous routing |
Preliminary Taxonomy Corrections
- Trusting a cached catalogue. Fix: discover SKILL.md files.
- Naming by technology buzzword. Fix: name the user intent.
- Deleting an alias without migration evidence. Fix: preserve the route.
- Counting references as active skills. Fix: separate roots.
- Resolving collision by broadening both descriptions. Fix: distinguish neighbours.
Worked Example
If two skills both claim research planning, reserve wave and cohort planning for research-orchestration and formal method selection for research-design, then add fixtures for both boundaries.
Use When
- Use when a router mentions a capability that may not exist as a top-level skill.
- Use when adding, renaming, merging, or splitting research skills.
- Use when aliases like verification, gap analysis, or synthesis create ambiguity.
Do Not Use When
- The request only needs the current task executed.
- A skill name is already canonical and no routing change is involved.
Taxonomy Source Requirements
- Current skill folders, router references, and requested capability.
- Evidence of overlapping skills or missing standalone folders.
Taxonomy Method Summary
- Inventory top-level skill names.
- Inventory router mentions and companion-skill references.
- Classify each capability as standalone skill, reference under a skill, alias, deprecated name, or planned gap.
- Normalize routers to point to canonical names.
- Add alias notes only when they prevent future confusion.
- Do not create a new skill when a reference file under an existing skill is enough.
Quality Standards
- Each skill has a single reason to exist.
- Router rows distinguish top-level skills from reference files.
- Deprecated names have replacements.
- Taxonomy changes reduce ambiguity rather than increase surface area.
Legacy Taxonomy Warnings
- Creating a new skill for every checklist.
- Hiding major workflows inside references that routers call as top-level skills.
- Letting several names refer to the same operation.
Initial Taxonomy Deliverables
- Canonical skill map.
- Alias/deprecation register.
- Reference-vs-skill decision.
Evidence Produced
| Category |
Artifact |
Format |
Example |
| Operability |
Canonical skill map |
Markdown table |
Capability, canonical skill, aliases |
| Release evidence |
Routing audit |
Markdown table |
Router mention and correction |
References
- Load
references/canonical-skill-map.md for taxonomy decisions.
Companion Skills
skill-writing governs skill authoring.doctrine-spine governs operating order.
Workflow
- Discover the live catalogue and candidate capability; stop if active roots are unclear.
- Compare closest neighbours, aliases, triggers, workflows, and references.
- Decide whether the material is a skill, reference, alias, or existing route.
- Test positive, negative, and collision prompts.
- Recover from failed routing by narrowing names/descriptions and rerunning fixtures.
Outputs
| Artifact |
Consumer |
Acceptance condition |
| Taxonomy decision and routing changes |
Maintainer and router |
Decision cites neighbours, migration impact, and passing fixtures. |
Anti-Patterns
- Trusting a cached catalogue. Fix: discover files.
- Naming by buzzword. Fix: name intent.
- Removing aliases without migration. Fix: preserve routes.
- Counting references as skills. Fix: separate roots.
- Broadening collisions. Fix: distinguish neighbours.
1---2name: skill-taxonomy-and-routing3description: Use when normalizing skill names, resolving whether a capability should be a standalone skill or a reference file, updating routers, removing alias drift, or auditing the repository's research skill taxonomy.4---56# Skill Taxonomy And Routing78## Inputs910| Input | Source/provider | If absent |11|---|---|---|12| Live active-skill inventory, candidate skill/reference, and neighbouring descriptions | Filesystem and change request | Stop taxonomy changes and rediscover the catalogue. |13| Routing fixtures and alias/migration records | Repository | Mark collision and compatibility checks unassessed. |1415## Capability Contract1617Taxonomy analysis defaults to read-only. Renaming, moving, deactivating, deleting, or changing routers and aliases requires explicit repository authority and migration evidence.1819## Degraded Mode2021If the live catalogue, neighbouring descriptions, or routing fixtures are unavailable, return candidate placement and collision risks without changing taxonomy. Do not declare a route collision-free.2223## Decision Rules2425| Choice | Action | Failure/risk avoided |26|---|---|---|27| Capability has distinct triggers and workflow | Keep or create a skill | Hidden specialist behaviour |28| Material only deepens an existing workflow | Store it as a linked reference | Catalogue fragmentation |29| Names or triggers overlap | Tighten descriptions and negative triggers | Ambiguous routing |3031## Preliminary Taxonomy Corrections3233- Trusting a cached catalogue. Fix: discover SKILL.md files.34- Naming by technology buzzword. Fix: name the user intent.35- Deleting an alias without migration evidence. Fix: preserve the route.36- Counting references as active skills. Fix: separate roots.37- Resolving collision by broadening both descriptions. Fix: distinguish neighbours.3839## Worked Example4041If two skills both claim research planning, reserve wave and cohort planning for research-orchestration and formal method selection for research-design, then add fixtures for both boundaries.4243<!-- dual-compat-start -->4445## Use When4647- Use when a router mentions a capability that may not exist as a top-level skill.48- Use when adding, renaming, merging, or splitting research skills.49- Use when aliases like verification, gap analysis, or synthesis create ambiguity.5051## Do Not Use When5253- The request only needs the current task executed.54- A skill name is already canonical and no routing change is involved.5556## Taxonomy Source Requirements5758- Current skill folders, router references, and requested capability.59- Evidence of overlapping skills or missing standalone folders.6061## Taxonomy Method Summary62631. Inventory top-level skill names.642. Inventory router mentions and companion-skill references.653. Classify each capability as standalone skill, reference under a skill, alias, deprecated name, or planned gap.664. Normalize routers to point to canonical names.675. Add alias notes only when they prevent future confusion.686. Do not create a new skill when a reference file under an existing skill is enough.6970## Quality Standards7172- Each skill has a single reason to exist.73- Router rows distinguish top-level skills from reference files.74- Deprecated names have replacements.75- Taxonomy changes reduce ambiguity rather than increase surface area.7677## Legacy Taxonomy Warnings7879- Creating a new skill for every checklist.80- Hiding major workflows inside references that routers call as top-level skills.81- Letting several names refer to the same operation.8283## Initial Taxonomy Deliverables8485- Canonical skill map.86- Alias/deprecation register.87- Reference-vs-skill decision.8889## Evidence Produced9091| Category | Artifact | Format | Example |92|---|---|---|---|93| Operability | Canonical skill map | Markdown table | Capability, canonical skill, aliases |94| Release evidence | Routing audit | Markdown table | Router mention and correction |9596## References9798- Load `references/canonical-skill-map.md` for taxonomy decisions.99100<!-- dual-compat-end -->101102## Companion Skills103104- `skill-writing` governs skill authoring.105- `doctrine-spine` governs operating order.106107## Workflow1081091. Discover the live catalogue and candidate capability; stop if active roots are unclear.1102. Compare closest neighbours, aliases, triggers, workflows, and references.1113. Decide whether the material is a skill, reference, alias, or existing route.1124. Test positive, negative, and collision prompts.1135. Recover from failed routing by narrowing names/descriptions and rerunning fixtures.114115## Outputs116117| Artifact | Consumer | Acceptance condition |118|---|---|---|119| Taxonomy decision and routing changes | Maintainer and router | Decision cites neighbours, migration impact, and passing fixtures. |120121## Anti-Patterns122123- Trusting a cached catalogue. Fix: discover files.124- Naming by buzzword. Fix: name intent.125- Removing aliases without migration. Fix: preserve routes.126- Counting references as skills. Fix: separate roots.127- Broadening collisions. Fix: distinguish neighbours.
peterbamuhigire