DSH plugin Skills: identity, discovery, and invocation
Which same-name skill wins is decided by layer, rank, and invocation policy — not by filename. DSH plugin's skill registry is layered: host plus scope. Layer distance decides first, and rank only settles ties within a layer. Conflate the two and you get the classic confusion of a project-directory skill being overridden.
The registry is layered: host plus scope
The nearest layer's entry wins outright; rank only matters after that.(source)
The registry uses the host-plus-scope layering the tool registry established on top of dsh-scope. Registration lands in the layer matching the caller context's scope:
- Host row and repository plugins — the global layer;
- Plugins mounted by an agent preset's standing composition — that preset's layer.
Provider names are unique per layer, not per process. Reads merge the global layer with the observed scope's chain: the nearest layer's entry wins a name collision, and rank ordering only adjudicates within one layer.
Discovery caches are keyed by the resolved scope chain, so resetting a scope parent (empty-session recomposition) needs no registry change — the next read already sees it.
Six local discovery ranks
Rank decides within a layer; the root directory decides workspace ownership.(source)
| Rank | Source | Root |
|---|---|---|
| 100 | project-dsh | <projectRoot>/.dsh/skills |
| 200 | project-agents | <projectRoot>/.agents/skills |
| 300 | custom | Config.customSkillDirs |
| 400 | user-dsh | <dshHome>/skills |
| 500 | user-agents | <agentsHome>/skills |
| 600 | bundled | Used when Config.bundledSkillDir is configured |
The project root is the nearest ancestor containing .git, falling back to the current cwd. When ctx.fs is available, the git-root walk probes .git through the filesystem service, so remote or sandboxed workspaces never fall back to the host filesystem boundary.
Two easily missed details: the user DSH root skips its .system subdirectory, and the local provider synthesizes no built-in system skills — package-shipped skills need a configured bundled root or a dedicated provider.
Failure-root behavior is worth knowing: it supplies no candidates, so until it recovers, a lower-priority same-name skill in another root may supply both the catalog description and the loaded body. "Description from A, body from B" is a possible transitional state.
Identity rules and file shapes
Names must be kebab-case, and nested recursive discovery is unsupported.(source)
Skill names match ^[a-z0-9]+(?:-[a-z0-9]+)*$. The local provider accepts two shapes: a directory package <name>/SKILL.md and a flat Markdown file <name>.md.
Recursive **/SKILL.md discovery is not supported, so a skill directory buried two levels deep is simply never found.
Summaries are policy-independent
list() keeps all four policy combinations; filtering happens at consumer boundaries.(source)
SkillSummary carries an optional path (the absolute instruction file path the provider supplied, absent for virtual skills), name, description, optional whenToUse, invocation, source, provider, and optional resourceBase.
SkillInvocationPolicy has exactly two positive booleans, modelInvocable and userInvocable, with four meanings:
- both
true— model and user can invoke; { modelInvocable: true, userInvocable: false }— model only;{ modelInvocable: false, userInvocable: true }— user only;- both
false— only a trustedctx.skills.get()caller can load it.
The local provider reads the exactly-named kebab-case frontmatter keys disable-model-invocation and user-invocable, defaults omitted fields to true, and produces this normalized policy per parsed skill.
Candidates, definitions, and incomplete snapshots
The registry stores locators only; bodies are always fetched live.(source)
SkillCandidate is the provider-to-registry shape with three additions beyond a summary: rank, an opaque locator, and optional metadata. The registry stores only the locator and passes it back verbatim when calling the winning provider's get().
SkillDefinition is the fully resolved result from ctx.skills.get(), adding content and optional metadata beyond the summary for the skill tool to use. resourceBase tells the tool how to render relative resource guidance for local, URL, or provider-managed skills.
SkillCatalogSnapshot distinguishes "definitely absent" from "a provider failed briefly or the directory keeps changing": skills holds this observation's collected, sorted, policy-independent summaries, and complete is true only when every registered provider finished discovery without a concurrent catalog revision. Incomplete snapshots are not cached, so the next query retries.
SkillProviderObservation lets a provider surface candidates that are still directly loadable while reporting the observation is not authoritative. That is more practical than all-or-nothing: the catalog is incomplete, but discovered skills still work.
Lookup reloads the body every time
get() re-reads content and re-validates the name match.(source)
Skill lookup is cwd-sensitive because providers may expose workspace-local skills; the optional signal lets callers cancel provider work. Registry reads also carry the observation scope through SkillViewOptions — consumers pass the agent in the call, and an agent is its own scope key. The registry consumes scope for layer selection, while providers read SkillLookupOptions from the same borrowed options object.
Cancellation is checked before and after catalog selection, including cache hits, and races against discovery and full-definition loading. When no git root is found, the local provider treats the supplied cwd as the project root.
The key caching semantic: the registry never caches full definitions. Every get() calls the winning provider with the selected candidate, so the local provider reloads current content. A definition whose name no longer matches that candidate is rejected, and that provider instance is invalidated for re-discovery.
Session and browser catalogs are different paths
One goes through pre-step injection, the other through Remote reads; they serve different entry points.(source)
dsh-tool-skill injects the initial persistent user-role <system-reminder> at the first agent/pre-step that observes available skills or incomplete discovery in a live session. The catalog holds only sorted skill names and normalized, XML-escaped descriptions — no bodies, paths, sources, providers, or routing hints. catalogDescriptionMaxLength defaults to 500 with an integer minimum of 3.
Before every later model step, the consumer applies exact tool visibility and compares entries plus completeness with the latest recognizable, still-visible catalog message in the session log. On change it publishes a persistent replacement catalog; removing all skills appends an explicit empty replacement; incomplete discovery publishes the usable subset with a warning and optional incomplete: true source metadata. After compaction hides every historical catalog message, the next observation rebuilds the current catalog, and a complete empty view sends nothing when no catalog was ever published.
The model-facing skill({ name }) tool validates the kebab-case name, looks the summary up in the policy-independent catalog, rejects unauthorized skills through isModelInvocable before loading, then re-reads the full definition against the caller agent's cwd and checks policy again before returning content. Results carry <skill_content name="...">, <skill_resources>, and <skill_instructions>, with resourceBase resolving only explicitly referenced scripts, references, and assets.
The browser side is separate: SkillListRequest names a Session via sessionId, and SkillListValue returns entries the user may invoke with name, description, optional usage hint, and model-invocation availability. SessionSkillCatalog reads the Session cwd and recorded preset without activating an Agent: a live Agent can supply its scoped registry, while a cold Session uses the preset's standing scope.
Verification: one name in two directories
Check layer, rank, and invocation policy in three separate steps, or you cannot tell what won.(source)
- Put one same-name skill in the project
.dsh/skillsand one in the user directory, and assert the project copy'ssourceisproject-dsh. - Set the project copy's frontmatter to
user-invocable: falseand assert the model tool can still call it while the user directory listing excludes it. - Put two same-name candidates with different ranks in one layer and assert the lower rank wins inside that layer.
- Register a same-name skill at the preset layer and assert it beats the global layer instead of comparing ranks.
- Call
snapshot()and assertcompleteis true; make one provider'slist()throw and assertcompleteis false and the result is not cached. - Change a skill body without renaming it, call
get()again, and assert you receive the new body while the catalog message is unchanged.
If step 6 returns the old body, the caller cached SkillDefinition itself; the registry re-reads every time.
For configuring skill directories, see skill directory configuration; for enabling and using skills, see skill usage.
One line to close: layer beats rank, names are kebab-case, summaries keep all four policy combinations, locators stay opaque, bodies are never cached, and the session catalog syncs with the log instead of re-sending every step.
FAQ
Layer first, then rank. In DSH plugin the nearest layer's entry wins outright; rank only settles ties inside one layer, so a lower-ranked skill in an upper layer can still beat a lower layer.
No. DSH plugin's registry never caches full definitions. DSH plugin calls the winning provider's get with the selected candidate on every read, so the local provider reloads the current body.
No. DSH plugin controls the two entry points with two separate fields. With both set to false, only a trusted ctx.skills.get caller can reach the skill.
No. DSH plugin states that unfinished observations are never cached. DSH plugin has consumers keep the last good state and retry discovery at the next request boundary.
Related Terms
- SkillInvocationPolicy
- SkillInvocationPolicy normalizes two independent invocation controls into positive booleans: modelInvocable and userInvocable.— packages/skill/skill/src/index.ts
- SkillSummary
- SkillSummary is a policy-independent skill summary with name, description, optional path, invocation policy, source, and provider.— packages/skill/skill/src/index.ts
- SkillCandidate
- SkillCandidate is the provider-to-registry shape: a summary plus rank, an opaque locator, and optional metadata.— packages/skill/skill/src/index.ts
- SkillCatalogSnapshot
- SkillCatalogSnapshot is one catalog observation with sorted summaries and a complete flag true only when all providers finished stably.— packages/skill/skill/src/index.ts
Sources
- DeepSeek Harness reference - Skills· deepseek-ai
- packages/skill/skill/src/index.ts· deepseek-ai