From 9d06345ba3123524858f361b00fa21255e9666ac Mon Sep 17 00:00:00 2001 From: Igor Wnek Date: Wed, 24 Jun 2026 17:37:16 +0200 Subject: [PATCH 1/5] feat: add tsh-creating-router-skills skill --- .../tsh-creating-router-skills/SKILL.md | 160 ++++++++++++++++++ .../examples/tsh-building-backend/SKILL.md | 109 ++++++++++++ .../reference/patterns/pattern-composition.md | 42 +++++ .../reference/stacks/stack-selection.md | 40 +++++ .../resources/backend-router.template.md | 23 +++ .../templates/pattern-leaf.template.md | 50 ++++++ .../templates/router-skill.template.md | 92 ++++++++++ .../templates/stack-leaf.template.md | 50 ++++++ 8 files changed, 566 insertions(+) create mode 100644 .github/skills/tsh-creating-router-skills/SKILL.md create mode 100644 .github/skills/tsh-creating-router-skills/examples/tsh-building-backend/SKILL.md create mode 100644 .github/skills/tsh-creating-router-skills/examples/tsh-building-backend/reference/patterns/pattern-composition.md create mode 100644 .github/skills/tsh-creating-router-skills/examples/tsh-building-backend/reference/stacks/stack-selection.md create mode 100644 .github/skills/tsh-creating-router-skills/examples/tsh-building-backend/resources/backend-router.template.md create mode 100644 .github/skills/tsh-creating-router-skills/templates/pattern-leaf.template.md create mode 100644 .github/skills/tsh-creating-router-skills/templates/router-skill.template.md create mode 100644 .github/skills/tsh-creating-router-skills/templates/stack-leaf.template.md diff --git a/.github/skills/tsh-creating-router-skills/SKILL.md b/.github/skills/tsh-creating-router-skills/SKILL.md new file mode 100644 index 00000000..3c3aa886 --- /dev/null +++ b/.github/skills/tsh-creating-router-skills/SKILL.md @@ -0,0 +1,160 @@ +--- +name: tsh-creating-router-skills +description: "Creates router-style skills that keep one-domain SKILL.md files lean and route tasks to leaf references. Use when a single skill domain (backend, DevOps, SecOps, AI or agentic engineering, data, testing, or any other) is growing too large to navigate, when a domain spans many concerns or mutually exclusive choices, or when codifying a one-hop routing table where each leaf carries a load cue and mutually exclusive alternatives are flagged." +user-invocable: false +--- + +# Creating Router Skills + +Router skills keep a growing domain navigable without turning the root `SKILL.md` into a knowledge dump. They route tasks to concept-first leaves and keep selection separate from ownership. + +## Core Design Principles + + + + +The problem is selection and ownership, not context pressure. In normal use, only 1-3 skills load at once; the cost of scale is navigating and owning a growing library, not token bloat. + + + +Use one domain, one router, one `SKILL.md`. The router is a selector, not the knowledge container. Its job is to recognize the task, name the right leaf, and stay lean. + + + +The router body holds only the sharp domain description, the few global rules, and the routing table. All deeper domain knowledge belongs in leaves. + + + + +## File Topology vs Routing Topology + +Folders MAY nest, but the routing link graph from `SKILL.md` must stay one hop. Keep it one-hop end to end. + +If a reference grows its own internal structure, give it a folder. That helps ownership and keeps templates with the leaf that uses them. But the router must link straight to the leaf itself, never to a directory index that sends the agent onward. Reads degrade past one referenced file, so a second hop weakens the handoff. + +A thin, human-facing index can exist for browseability, but it is not the router. The agent should still be able to land on the leaf in one hop. + +## The Routing Table + +A router is one routing table. Each row names a leaf and the cue that tells the agent when to load it: + +| one-hop leaf | when to load / how to identify | +|---|---| +| `reference//leaf-a.md` | load when the task matches this leaf's cue (a signal in the repo, the task shape, or a declared target) | +| `reference//leaf-b.md` | load when the task matches this leaf's cue | + +The agent decides how many leaves to load by reading the cues: it loads every leaf whose cue applies. That default — load what fits — needs no special declaration. + +### Flag mutually exclusive leaves + +The one thing the agent cannot infer from independent cues is exclusivity: when two leaves are alternatives and loading both would cross-wire them — for example, two competing tech-stack leaves whose idioms must not blend. Cues are written one row at a time, so nothing tells the agent that matching two is a mistake rather than a feature. + +When leaves are mutually exclusive, say so in the cue: + +| one-hop leaf | when to load / how to identify | +|---|---| +| `reference/stacks/stack-a.md` | load **exactly one** stack leaf — the one matching the repo's manifest or lockfile; never load a second | +| `reference/stacks/stack-b.md` | alternative to stack-a; load only if it is the matching stack | + +Everything else is combinable by default. You do not declare a mode; you only flag exclusivity where loading two siblings would be wrong. + +Every routing-table row still needs a per-leaf cue alongside its one-hop link. A bare label and link are not enough. + +## Concept-First Leaf Authoring + +Leaves are about 80% structure and 20% primitives. They should explain boundaries, lifecycle, decision rules, and diagrams first; concrete syntax comes last. + + +A leaf should be concept-first. Prefer diagrams, shape sketches, and abstract interfaces over filled-in domain objects or concrete business code. A leaf that ships copied production code stops guiding the model and starts recruiting it into the wrong local idiom. + + +Use primitives only when they stay abstract: empty skeletons, interface shapes, config defaults, or other minimal anchors that help the model build the right local result. Never turn the leaf into a code sample repository. + +## Router Sizing and Naming + +Keep the router body roughly under 500 lines. A router routes; it does not teach the whole domain. + +Names are load-bearing: + +- lowercase only +- hyphenated only +- `tsh-` prefix required +- directory name must match the `name` field exactly +- do not namespace with `/` or `:` because such skills silently fail to load + +The router should read like a selector index for one domain, not like a handbook for the entire collection. + +## `SKILL.md`, not `README.md` + +Only `SKILL.md` frontmatter is loaded for selection. `README.md` is never auto-read, so it cannot route anything unless something else points to it. Case matters: `SKILL.md` is uppercase and must stay that way. + +Use `README.md` for humans browsing the repository. Use `SKILL.md` for agent selection and routing. + +## Applying the Pattern + +1. Pick one domain and write its router `SKILL.md`. + - Give it a sharp description. + - Add the global rules that apply to every task in the domain. + - List every leaf in one routing table, each with a `when to load / how to identify` cue. For leaves that are mutually exclusive alternatives, make the cue say to load exactly one. +2. Move detailed content into concept-first leaves under `reference/`. + - Keep each leaf focused on one choice or one concern. + - Give larger leaves their own folder when they need local templates or supporting files. +3. Link the router straight to each leaf. + - Do not route through a directory index. + - Keep the link graph one hop. +4. Verify on a live task. + - Confirm the agent loads every applicable leaf. + - Confirm it never loads two mutually exclusive leaves at once. + - Confirm unrelated leaves stay out of context. + - Watch for cross-wiring. +5. Iterate until the router is crisp. + - If the router is carrying knowledge instead of selection, move that content into leaves. + - If a leaf is still too concrete, raise it back to concept-first shape. + +## Validation Checklist + +```text +- [ ] Frontmatter: `name` uses lowercase hyphenated `tsh-` prefix and matches the directory name +- [ ] Frontmatter: `description` states what the skill does and when to use it, including router-pattern triggers +- [ ] Frontmatter: `user-invocable` is `false` +- [ ] Routing: mutually exclusive leaves say "load exactly one" in their cue; all other leaves are combinable by default +- [ ] Routing: every row has a one-hop leaf link +- [ ] Routing: every row includes a per-leaf `when to load / how to identify` cue +- [ ] Routing: the router stays one hop and never routes through an intermediate index +- [ ] Leaves: leaves stay concept-first and avoid filled-in domain objects or concrete business code +- [ ] Files: router body stays roughly under 500 lines +- [ ] Files: directory name matches the `name` field exactly +- [ ] Files: no namespaced `"/"` or `":"` form is used for the skill name +- [ ] Testing: a live task loads every applicable leaf and never loads two mutually exclusive leaves at once +- [ ] Testing: no cross-wiring appears between unrelated leaves +``` + +## Anti-Patterns to Avoid + +| Anti-pattern | Why it's harmful | Fix | +|---|---|---| +| Routing through an intermediate index | Adds a second hop and degrades reads past the first referenced file | Link the router straight to the leaf | +| Loading two mutually exclusive leaves at once | Cross-wires alternatives whose idioms must not blend | Flag exclusivity in the cue: say "load exactly one — the one matching X" | +| Letting a leaf leak concrete code | Forces the model to imitate local implementation details instead of the domain shape | Keep the leaf concept-first and abstract | +| Using a namespaced name with `/` or `:` | Such skills silently fail to load | Use a flat `tsh-` prefixed hyphenated name | +| Putting routing logic in `README.md` | `README.md` is never auto-read for selection | Put routing in `SKILL.md` frontmatter and body | +| Listing leaves without per-row load cues | The router says where, but not why, so selection becomes guesswork | Add a `when to load / how to identify` cue to every row | +| Letting the router turn into a knowledge dump | The root file becomes hard to navigate and defeats the router pattern | Move detail into leaf references and keep the router lean | + +## Templates and Examples + +Use these supporting files when authoring or reviewing router skills: + +A leaf is just a concept-first reference. The two leaf templates show two common shapes — a mutually exclusive alternative and a composable concern — and their filenames keep the canonical "stack"/"pattern" examples; rename them for any domain (provider, framework, control, runner, capability...). + +- [Router template](./templates/router-skill.template.md) — scaffold for a router `SKILL.md`. +- [Stack leaf template](./templates/stack-leaf.template.md) — scaffold for a leaf that is a mutually exclusive alternative (stacks are the canonical example; its router cue says "load exactly one"). +- [Pattern leaf template](./templates/pattern-leaf.template.md) — scaffold for a composable concern leaf (patterns are the canonical example; combinable by default). +- [Worked example: tsh-building-backend](./examples/tsh-building-backend/SKILL.md) — one example domain among many (DevOps, SecOps, AI engineering, data, and testing use the same routing); a complete one-hop router with two leaves and an on-demand resource. + +## Connected Skills + +- `tsh-creating-skills` - to author single-file skills when the domain stays small enough that a router is unnecessary +- `tsh-creating-agents` - to align router skills with agent behavior and keep responsibilities separate +- `tsh-creating-prompts` - to understand how prompts trigger skills and keep routing entry points clear +- `tsh-creating-instructions` - to place repository rules in instructions instead of inflating the router diff --git a/.github/skills/tsh-creating-router-skills/examples/tsh-building-backend/SKILL.md b/.github/skills/tsh-creating-router-skills/examples/tsh-building-backend/SKILL.md new file mode 100644 index 00000000..1bc42550 --- /dev/null +++ b/.github/skills/tsh-creating-router-skills/examples/tsh-building-backend/SKILL.md @@ -0,0 +1,109 @@ +--- +name: tsh-building-backend +description: "Routes a concept-first backend domain into one-hop leaf references. Use when the task needs to select a backend stack, apply backend patterns, or load on-demand resources." +user-invocable: false +--- + + + +# Building Backend Router + +> This backend domain is one illustrative example. The same one-hop routing model applies to DevOps, SecOps, AI engineering, data, testing, and any other domain — only the leaves change. + + +Selection and ownership for a concept-first backend domain. + + + + +This router keeps the domain lean and resolves tasks in one-hop routing. + + +One-hop routing stays straight from the router to the leaf; no intermediate index, no second hop. + + + +## Core Design Principles + + + + The problem is selection and ownership, not context pressure. + + + One domain, one router, one `SKILL.md`. + + + The router is a selector, not the knowledge container. + + + +## File Topology vs Routing Topology + + +Folders MAY nest deeper for ownership, but the routing link graph stays one hop end to end. The router links straight to leaves and never routes through an intermediate index. + + +## Routing Table + + +| one-hop leaf | when to load / how to identify | +|---|---| +| [stack-selection](reference/stacks/stack-selection.md) | load **exactly one** stack leaf — the one matching the repo's backend manifest or lockfile; never load a second | +| [pattern-composition](reference/patterns/pattern-composition.md) | load when the task needs composition guidance; combinable with other applicable concern leaves | + + +## On-Demand Resource + + +On-demand support material: [backend-router.template](resources/backend-router.template.md) + + +## Concept-First Leaf Authoring + + +Keep every leaf concept-first and abstract. Use shape sketches, boundaries, and minimal primitives only; never introduce filled-in backend business code. + + +## Router Sizing and Naming + + +Keep the router compact and selector-like so the model can resolve the right leaf without carrying the whole domain. + + +## `SKILL.md`, not `README.md` + + +Only `SKILL.md` frontmatter is loaded for selection, so this router lives in `SKILL.md` and points directly to its leaves. + + +## Applying the Pattern + + +1. Match the task against the routing table cues. +2. Load every applicable leaf in one hop; load exactly one stack leaf. +3. Keep the leaf concept-first and abstract. +4. If supporting material is needed, load it on demand from the co-located resource. + + +## Validation Checklist + + +- [ ] Frontmatter uses `tsh-building-backend` +- [ ] Frontmatter description follows `{what}. {when — triggers}.` and includes `Use when` +- [ ] `user-invocable` is `false` +- [ ] The body contains the literal `one-hop` +- [ ] The stack leaf cue says to load exactly one +- [ ] Other leaves are combinable by default +- [ ] Each row includes a `when to load / how to identify` cue +- [ ] The router links directly to `reference/stacks/stack-selection.md` +- [ ] The router links directly to `reference/patterns/pattern-composition.md` +- [ ] The router links directly to `resources/backend-router.template.md` +- [ ] No intermediate index appears between router and leaf + + +## Connected Skills + + +- `tsh-creating-skills` — aligns with the skill-format conventions for router bodies and validation +- `tsh-creating-instructions` — keeps repository rules in instructions instead of inflating the router + diff --git a/.github/skills/tsh-creating-router-skills/examples/tsh-building-backend/reference/patterns/pattern-composition.md b/.github/skills/tsh-creating-router-skills/examples/tsh-building-backend/reference/patterns/pattern-composition.md new file mode 100644 index 00000000..1ca719a6 --- /dev/null +++ b/.github/skills/tsh-creating-router-skills/examples/tsh-building-backend/reference/patterns/pattern-composition.md @@ -0,0 +1,42 @@ + + +# Pattern Composition Leaf + + +This leaf stays concept-first and abstract. + + + +This leaf is for composable pattern guidance in an abstract backend domain. + + +## Load Trigger + +loaded when: the task needs composition guidance; may load alongside other applicable concern leaves + +## Composition + +- Combine only the primitives that actually apply. +- Keep composition rules separate from stack selection. +- Favor small, reusable shape fragments over concrete examples. + +## Compatibility Notes + +- Multiple patterns may load together. +- Composition should not turn into a second router. +- If a task only needs one stack choice, stay out of the way. + +## Abstract Primitives + +- composition boundary +- compatibility cue +- primitive merge +- handoff marker + +## One-Hop Handoff + +The router links here directly; the leaf stays on the pattern side of the split. + +## Scaffold Notes + +This leaf is composable: the router may load it alongside other applicable concern leaves. diff --git a/.github/skills/tsh-creating-router-skills/examples/tsh-building-backend/reference/stacks/stack-selection.md b/.github/skills/tsh-creating-router-skills/examples/tsh-building-backend/reference/stacks/stack-selection.md new file mode 100644 index 00000000..fc2e3910 --- /dev/null +++ b/.github/skills/tsh-creating-router-skills/examples/tsh-building-backend/reference/stacks/stack-selection.md @@ -0,0 +1,40 @@ + + +# Stack Selection Leaf + + +This leaf stays concept-first and abstract. + + + +This is the direct router target for an exclusive stack choice in an abstract backend domain. + + +## Load Trigger + +loaded when: the router picks exactly one stack and the repo cues point to this one + +## Selection Criteria + +- Choose exactly one stack shape. +- Prefer this leaf when the decision is about stack ownership, not pattern composition. +- Keep the handoff one-hop and stop after selection. + +## Ownership Boundaries + +This leaf owns only stack selection, not pattern composition, not resource loading, and not backend business code. + +## One-Hop Handoff + +The router links here directly; this file is the end point for stack selection. + +## Abstract Primitives + +- stack boundary +- selection gate +- cue +- handoff marker + +## Scaffold Notes + +This leaf is a mutually exclusive alternative: the router loads exactly one stack leaf and does not continue to another routing layer. diff --git a/.github/skills/tsh-creating-router-skills/examples/tsh-building-backend/resources/backend-router.template.md b/.github/skills/tsh-creating-router-skills/examples/tsh-building-backend/resources/backend-router.template.md new file mode 100644 index 00000000..ffc47cad --- /dev/null +++ b/.github/skills/tsh-creating-router-skills/examples/tsh-building-backend/resources/backend-router.template.md @@ -0,0 +1,23 @@ + + +# Backend Router Template Resource + + +This skeleton resource is loaded on-demand from the router and stays separate from the routing table. + + +## Skeleton + +- placeholder cue +- placeholder shape note +- placeholder handoff note + +## Boundaries + +- no backend business code +- no second router +- no intermediate index + +## Notes + +This file is only a co-located template resource for the example router. diff --git a/.github/skills/tsh-creating-router-skills/templates/pattern-leaf.template.md b/.github/skills/tsh-creating-router-skills/templates/pattern-leaf.template.md new file mode 100644 index 00000000..9f4a7bcc --- /dev/null +++ b/.github/skills/tsh-creating-router-skills/templates/pattern-leaf.template.md @@ -0,0 +1,50 @@ +--- +name: +description: "{what}. {when — triggers}." +--- + + + +# + + + + +This scaffold stays abstract and composable, with no concrete implementation details. + + + +This leaf is for composition rules, compatibility notes, and abstract primitives. + + +## + +loaded when: + +## + + + + + +## + + + + + +## + + + + + +## + + + + + +## + + diff --git a/.github/skills/tsh-creating-router-skills/templates/router-skill.template.md b/.github/skills/tsh-creating-router-skills/templates/router-skill.template.md new file mode 100644 index 00000000..cfa8aa73 --- /dev/null +++ b/.github/skills/tsh-creating-router-skills/templates/router-skill.template.md @@ -0,0 +1,92 @@ +--- +name: +description: "{what}. {when — triggers}." +user-invocable: false +--- + + + +# + + +Selection and ownership. + + + + + +One-hop routing. + + + + +## + + + + + + + + + + + + + + + +## + + + + + +## + + + + +| one-hop leaf | when to load / how to identify | +|---|---| +| | | +| | | + + +## + + + + + +## + + + +## <`SKILL.md`, not `README.md`> + + + +## + + + + + +## + + + + + +## + + + + + +## + + + + diff --git a/.github/skills/tsh-creating-router-skills/templates/stack-leaf.template.md b/.github/skills/tsh-creating-router-skills/templates/stack-leaf.template.md new file mode 100644 index 00000000..7ceb6561 --- /dev/null +++ b/.github/skills/tsh-creating-router-skills/templates/stack-leaf.template.md @@ -0,0 +1,50 @@ +--- +name: +description: "{what}. {when — triggers}." +--- + + + +# + + + + +This scaffold stays concept-first: roughly 80% structure and 20% primitives. + + + +This leaf is for selection criteria, ownership boundaries, and direct router-to-leaf one-hop loading. + + +## + +loaded when: + +## + + + + + +## + + + + + +## + + + + + +## + + + + + +## + + From 00221dac37a71a9dccbdf262408dd29f9325f436 Mon Sep 17 00:00:00 2001 From: Igor Wnek Date: Wed, 24 Jun 2026 17:37:53 +0200 Subject: [PATCH 2/5] feat: link new skill in tsh-creating-skills skill --- .github/skills/tsh-creating-skills/SKILL.md | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/skills/tsh-creating-skills/SKILL.md b/.github/skills/tsh-creating-skills/SKILL.md index 95f9f170..34b6771e 100644 --- a/.github/skills/tsh-creating-skills/SKILL.md +++ b/.github/skills/tsh-creating-skills/SKILL.md @@ -334,3 +334,4 @@ For standard workflow patterns (checklists, templates, conditional workflows, fe - `tsh-technical-context-discovering` - to discover existing skill patterns in the project before creating a new one - `tsh-codebase-analysing` - to analyze existing skills and identify conventions to follow - `tsh-creating-instructions` - to understand when project rules belong in instruction files rather than skill content +- `tsh-creating-router-skills` - to switch from single-skill authoring to router-skill authoring when a domain grows too large to navigate and should be split into a one-domain router with concept-first leaf references From 37e3298c1e2b7592b64dc6d3ec9c2c89287e3310 Mon Sep 17 00:00:00 2001 From: Igor Wnek Date: Wed, 24 Jun 2026 17:38:28 +0200 Subject: [PATCH 3/5] docs(website): add info about the new skill --- website/docs/skills/creating-router-skills.md | 38 +++++++++++++++++++ website/docs/skills/creating-skills.md | 1 + website/docs/skills/overview.md | 4 +- 3 files changed, 42 insertions(+), 1 deletion(-) create mode 100644 website/docs/skills/creating-router-skills.md diff --git a/website/docs/skills/creating-router-skills.md b/website/docs/skills/creating-router-skills.md new file mode 100644 index 00000000..c2c285c5 --- /dev/null +++ b/website/docs/skills/creating-router-skills.md @@ -0,0 +1,38 @@ +--- +sidebar_position: 34 +title: Creating Router Skills +--- + +# Creating Router Skills + +**Folder:** `.github/skills/tsh-creating-router-skills/` +**Used by:** Copilot Engineer + +Router skills keep a growing domain easy to navigate without stuffing the root `SKILL.md` with everything the domain knows. They route tasks to concept-first leaves and keep selection separate from ownership. + +## Core Design Principles + +- **Selection over context pressure** — The challenge is choosing the right leaf, not fighting token limits. +- **One domain, one router, one `SKILL.md`** — The router is a selector, not the knowledge container. +- **Stay lean at the top** — Keep the router to the sharp domain description, the global rules, and the routing table. + +## The Routing Table + +A router is one routing table. Each row names a leaf and a `when to load / how to identify` cue. The agent loads every leaf whose cue matches — deciding how many to load on its own. That default needs no declaration. + +The one thing cues cannot express on their own is exclusivity: when two leaves are alternatives and loading both would cross-wire them (for example, two competing tech-stack leaves). For those, make the cue say to load exactly one — the one matching the authoritative signal (a manifest or lockfile for a tech stack, a provider config for infrastructure, a declared compliance target for security). Everything else is combinable by default. + +## Validation Checklist + +- Frontmatter `name` matches the directory name and uses the required `tsh-` prefix +- The `description` says what the router does and when to use it +- `user-invocable` remains `false` +- Mutually exclusive leaves say "load exactly one" in their cue +- All other leaves are combinable by default +- Every routing row includes a one-hop leaf link and a cue for when to load it +- The router never routes through an intermediate index +- Leaf files stay concept-first and avoid concrete business-code examples + +## Connected Skills + +- `tsh-creating-skills` — to author single-file skills when the domain is small enough that a router is unnecessary diff --git a/website/docs/skills/creating-skills.md b/website/docs/skills/creating-skills.md index c91cc478..e99a96f5 100644 --- a/website/docs/skills/creating-skills.md +++ b/website/docs/skills/creating-skills.md @@ -44,3 +44,4 @@ tsh-/ - `tsh-creating-agents` — For creating agents that load this skill. - `tsh-creating-prompts` — For creating prompts that trigger workflows using this skill. +- `tsh-creating-router-skills` — For creating router-style skills when a domain grows too large for a single-skill body. diff --git a/website/docs/skills/overview.md b/website/docs/skills/overview.md index d32f17b6..8feaf840 100644 --- a/website/docs/skills/overview.md +++ b/website/docs/skills/overview.md @@ -5,7 +5,7 @@ title: Skills Overview # Skills Overview -Copilot Collections includes **31 reusable skills** — knowledge modules that provide specialized domain expertise, structured processes, and quality templates. They encode tested best practices for every phase of the product lifecycle. Skills are stored in `.github/skills/` and loaded automatically by agents when their domain applies to the current task. +Copilot Collections includes **32 reusable skills** — knowledge modules that provide specialized domain expertise, structured processes, and quality templates. They encode tested best practices for every phase of the product lifecycle. Skills are stored in `.github/skills/` and loaded automatically by agents when their domain applies to the current task. ## How Skills Work @@ -71,6 +71,7 @@ When an agent starts a task, it checks all available skills and decides which on | Skill | Description | Used By | | ---------------------------------------------------- | ----------------------------------------------- | ---------------- | | [tsh-creating-agents](./creating-agents) | Creating custom agents (.agent.md) | Copilot Engineer | +| [tsh-creating-router-skills](./creating-router-skills) | Creating router skills (one-domain SKILL.md routers) | Copilot Engineer | | [tsh-creating-skills](./creating-skills) | Creating custom skills (SKILL.md) | Copilot Engineer | | [tsh-creating-prompts](./creating-prompts) | Creating custom prompts (.prompt.md) | Copilot Engineer | | [tsh-creating-instructions](./creating-instructions) | Creating custom instructions (.instructions.md) | Copilot Engineer | @@ -83,6 +84,7 @@ When an agent starts a task, it checks all available skills and decides which on | tsh-code-reviewing | | | | | ✅ | ✅ | | | | | | tsh-codebase-analysing | ✅ | ✅ | ✅ | ✅ | | | | | ✅ | ✅ | | tsh-creating-agents | | | | | | | | | | ✅ | +| tsh-creating-router-skills | | | | | | | | | | ✅ | | tsh-creating-instructions | | | | | | | | | | ✅ | | tsh-creating-prompts | | | | | | | | | | ✅ | | tsh-creating-skills | | | | | | | | | | ✅ | From 3ac3bff69a7b90a604aa68ec689e6721cd74d8d0 Mon Sep 17 00:00:00 2001 From: Igor Wnek Date: Wed, 24 Jun 2026 17:39:26 +0200 Subject: [PATCH 4/5] docs: add changelogs update about tsh-creating-router-skills skill --- CHANGELOG.md | 6 ++++++ website/src/pages/changelog.md | 6 ++++++ 2 files changed, 12 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6af7a33a..bad9e282 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,12 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). +## 2026-06-24 + +### Added + +- `tsh-creating-router-skills` skill — Creates the canonical authoring skill for one-domain router skills, with templates and a worked example that show the lean router shape, select-one versus combine-as-needed routing, and concept-first leaves. + ## 2026-06-01 ### Added diff --git a/website/src/pages/changelog.md b/website/src/pages/changelog.md index 69e5ec04..01f1ffe4 100644 --- a/website/src/pages/changelog.md +++ b/website/src/pages/changelog.md @@ -12,6 +12,12 @@ The canonical source for this changelog is [CHANGELOG.md](https://github.com/The The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). +## 2026-06-24 + +### Added + +- `tsh-creating-router-skills` skill — Creates the canonical authoring skill for one-domain router skills, with templates and a worked example that show the lean router shape, select-one versus combine-as-needed routing, and concept-first leaves. + ## 2026-06-01 ### Added From f42ebacfe87646fc48b23ed3a675e380caebfccb Mon Sep 17 00:00:00 2001 From: Igor Wnek Date: Thu, 25 Jun 2026 09:29:08 +0200 Subject: [PATCH 5/5] feat: add tsh-creating-router-skills guidance for copilot-related agents --- .github/agents/tsh-copilot-artifact-creator.agent.md | 1 + .github/agents/tsh-copilot-engineer.agent.md | 1 + 2 files changed, 2 insertions(+) diff --git a/.github/agents/tsh-copilot-artifact-creator.agent.md b/.github/agents/tsh-copilot-artifact-creator.agent.md index fe317bf3..93a708d8 100644 --- a/.github/agents/tsh-copilot-artifact-creator.agent.md +++ b/.github/agents/tsh-copilot-artifact-creator.agent.md @@ -27,6 +27,7 @@ Before starting any creation task, determine the artifact type from the specific - `tsh-creating-agents` — when creating or modifying a `.agent.md` file. Provides the agent file template, structural conventions, and validation checklist. - `tsh-creating-skills` — when creating or modifying a `SKILL.md` file, including associated templates and examples. Provides naming conventions, body structure guidelines, and progressive disclosure patterns. +- `tsh-creating-router-skills` — when creating or modifying router-style `SKILL.md` artifacts and their associated router resources or examples. Use it when the specification explicitly calls for a router-style skill, or when the target artifact is a routing layer for a broad domain. Do not use it for standard single-domain skill artifacts that should follow `tsh-creating-skills` alone. - `tsh-creating-prompts` — when creating or modifying a `.prompt.md` file. Provides the prompt file template, workflow focus guidelines, and validation checklist. - `tsh-creating-instructions` — when creating or modifying `.instructions.md` files or `copilot-instructions.md`. Provides templates for both repository-level and granular instruction files, decision framework for instruction vs. skill placement, and validation checklist. diff --git a/.github/agents/tsh-copilot-engineer.agent.md b/.github/agents/tsh-copilot-engineer.agent.md index d9fbe95f..42d2500b 100644 --- a/.github/agents/tsh-copilot-engineer.agent.md +++ b/.github/agents/tsh-copilot-engineer.agent.md @@ -56,6 +56,7 @@ Before starting any task, you check all available skills and decide which one is - `tsh-creating-agents` - when creating or reviewing .agent.md files; provides the structured creation process, template, and validation checklist for custom agents - `tsh-creating-skills` - when creating or reviewing SKILL.md files; provides naming conventions, body structure, progressive disclosure patterns, and validation checklists +- `tsh-creating-router-skills` - when creating, reviewing, or updating router-style SKILL.md files; use when a domain skill is growing too large, when a broad domain needs a one-hop router to focused leaves, or when the domain includes mutually exclusive choices; do not use for ordinary single-domain or small/self-contained skills that fit `tsh-creating-skills` - `tsh-creating-prompts` - when creating or reviewing .prompt.md files; provides the structured creation process, template, and workflow focus guidelines - `tsh-creating-instructions` - when creating or reviewing .instructions.md files or copilot-instructions.md; provides templates, decision framework for instruction vs. skill placement, and validation checklist - `tsh-technical-context-discovering` - to understand existing customization patterns in the project before creating or modifying any artifact