[Feature] Include whenToUse in the skill catalog + optional auto-injection of skill bodies

[aavainer]

EN

Motivation. Skills carry a whenToUse routing hint, but the agent currently can't see it.

1. whenToUse is dropped from the model catalog. In dsh-tool-skill, catalogSourceEntries / renderCatalogEntries render only name + description into <available_skills>; the whenToUse field (present in SkillSummary) is not included. Result: the routing guide is invisible to the model — skills are effectively "blind" (only a short description reaches the agent).
2. No auto-injection of the skill body. The body is loaded only by a manual skill() tool call. "The skill knows when it applies" (auto-injection on match) is absent — by design the flow is call-based.

Request:

• (a) Show whenToUse in the model's skill catalog (so the routing hint reaches the agent, not just name + description).
• (b) Optional — auto-inject a skill's body when the task matches (e.g., by whenToUse), so the agent doesn't rely solely on self-invoking skill().

This is a feature request, not a bug — the current call-based behavior is by design; the ask is to make skills self-describing to the router.

---

RU

Мотивация. У скилов есть routing-подсказка whenToUse, но агент сейчас её не видит.

1. whenToUse отбрасывается в модельном каталоге. В dsh-tool-skill функции catalogSourceEntries / renderCatalogEntries рендерят в <available_skills> только name + description; поле whenToUse (есть в SkillSummary) в каталог не попадает. Итог: routing-гид невидим модели — скилы для агента фактически «слепые» (до агента доходит только короткое описание).
2. Нет авто-инъекции тела скила. Тело грузится только ручным вызовом инструмента skill(). «Скил сам знает, когда примениться» (авто-подстановка по совпадению) отсутствует — по дизайну поток call-based.

Запрос:

• (a) Показывать whenToUse в модельном каталоге скилов (чтобы routing-подсказка доходила до агента, а не только name + description).
• (b) Опционально — авто-инъекция тела скила при совпадении задачи (напр. по whenToUse), чтобы агент не полагался только на самовызов skill().

Это feature request, а не баг — текущее call-based поведение по дизайну; просьба — сделать скилы самоописывающимися для маршрутизатора.

Anonymized for public reporting: workspace names, paths, session names/ids and dates have been genericized.

[aavainer]

FWIW, part (b) — auto-injection of skill bodies — is already implemented by the community plugin lau4tin1/dsh-skill-router (RAG routing: it embeds name + description + whenToUse and auto-injects the matching bodies on each turn). So the genuinely missing upstream piece is (a): expose whenToUse in the native <available_skills> catalog, so the routing hint reaches the model without an external plugin.

Noting this so the maintainers can see (b) has a working community implementation and (a) is the core ask.

---

RU:

К слову, пункт (b) — авто-инъекция тел скилов — уже реализован community-плагином lau4tin1/dsh-skill-router (RAG-маршрутизация: эмбеддит name + description + whenToUse и авто-инъектит совпавшие тела на каждом ходу). То есть по-настоящему недостающий upstream-кусок — это (a): показывать whenToUse в нативном <available_skills>, чтобы routing-гид доходил до модели без внешнего плагина.

Помечаю, чтобы мейнтейнеры видели: у (b) есть рабочая community-реализация, а (a) — основной запрос.

Anonymized for public reporting: workspace names, paths, session names/ids and dates have been genericized.

[Paraphern]

+1 on surfacing whenToUse - one integrity note while the catalog surface is being designed: whatever fields enter the model catalog (name, description, whenToUse) become the de-facto instruction surface, especially if body auto-injection follows. Worth versioning the catalog export and giving it a digest, so an agent host or CI can pin the catalog a version ships and detect when an upgrade changes routing hints - a rewritten whenToUse redirects the agent silently, the same class as a rewritten description. We pin the underlying skill files this way (a catalog digest would be its natural export); happy to share the schema.

[argszero]

For core ask (a) — until the native catalog renders whenToUse — the routing hint can reach the model today through a plugin: @argszero/dsh-skill-residency (npm, MIT) appends each author's whenToUse to the request at the agent/pre-step waterfall, as a durable, source-attributed user message (default bound: 240 characters per skill, whitespace-normalized). It re-publishes only when the plan changes, or after compaction drops it — decided by asking the session which of its events the model can still see, not by keeping plugin state — so an unchanged catalog costs nothing.

It also covers the "always on" half of (b) for skills that declare it: resident: ['my-style'] in the mount config, or metadata: { resident: true } in the skill's own frontmatter, injects that body on every turn through the same <skill_content> envelope the skill tool and the /name gesture already produce. That is deliberately a different half from lau4tin1/dsh-skill-router: theirs is match-based RAG routing (embed name + description + whenToUse, inject what matches), while this is for instructions whose declared intent is "every turn, whatever the task" — the case the catalog's current trigger wording ("If the user names a skill, or the task clearly matches a skill's description…") cannot express.

No core package is changed; it mounts through dsh.bundle.patch; measured on the released 0.1.7-rc.2, 0.2.0-rc.2 and 0.2.1-alpha.2 lines. The whenToUse half is the same gap as (a) here, reported as #9375.

On the integrity note, two pins rather than one, because the surfaces are about to diverge: the native catalog — once it carries whenToUse — is upstream's to version and digest, while what a plugin injects is decided per turn by that plugin's own plan and bounded by its config (whenToUseMaxLength, plus mode: report to log the exact plan without sending it). Pinning the plugin version pins the second surface, and that second surface is the one a deployment is pinned to today.

[Paraphern]

The two-pin split is the right refinement of the note above - pinning the plugin version pins the injection surface as deployed, and the catalog digest belongs upstream once it lands. One third leg worth considering, because per-turn injection is computed rather than static: the plan is derived each turn from catalog state and compaction, so two deployments on the same pinned plugin version can still inject different content on different turns. mode: report gives you the plan log; a digest of what was actually sent (an injection receipt - hash of the exact <skill_content> payload, appended to the session event log) makes the surface auditable after the fact: "what instructions entered this context" stays answerable independent of plugin version. We keep that shape for MCP tool calls (receipts chain in rugsnare); it is the piece that turns the second pin from assumed into provable. And agreed the resident-skill case is the native gap of #9375 - plugin today, catalog fix eventually.