mirror of
https://github.com/deepseek-ai/deepseek-harness
synced 2026-08-15 21:04:50 +00:00
179 lines
12 KiB
Markdown
179 lines
12 KiB
Markdown
# Skills
|
|
|
|
English | [中文](skills.zh.md)
|
|
|
|
The [skill capability family](../../packages/skill) is split across three packages: the registry ([dsh-skill](../../packages/skill/skill), `ctx.skills`) merges provider catalogs; the local provider ([dsh-skill-local](../../packages/skill/skill-local)) scans and watches project/custom/user directories; the consumer ([dsh-tool-skill](../../packages/skill/tool-skill)) owns the initial and replacement catalogs plus the model-facing `skill` tool. Skills are optional instructions, not session events, so their vocabulary lives here rather than in [core.md](core.md).
|
|
|
|
Source: [`packages/skill/skill/src/index.ts`](../../packages/skill/skill/src/index.ts), [`packages/skill/skill-local/src/index.ts`](../../packages/skill/skill-local/src/index.ts), and [`packages/skill/tool-skill/src/index.ts`](../../packages/skill/tool-skill/src/index.ts).
|
|
|
|
## Provider registry
|
|
|
|
`ctx.skills` combines local, embedded, remote, or other providers. Registration is synchronous; remote initialization and discovery belong in awaited `list()`. Provider objects, options, and candidates are borrowed readonly, while semantic fields are validated.
|
|
|
|
Duplicate names resolve by rank, provider order, then local order; summaries sort by name. A rejected `list()` is logged and omitted from an incomplete observation without caching it, while malformed candidates fail fast. `invalidateProvider()` clears completed catalogs only for the exact live provider object, and an in-flight discovery retries when its provider generation changes. Provider and runtime membership mutations emit the unfiltered `skills/change` invalidation event; it carries no diff, so consumers refetch `snapshot()` with their own lookup options.
|
|
|
|
```ts type-equiv
|
|
/** Provider interface for one source of skills, such as local directories or a remote registry. */
|
|
interface SkillProvider {
|
|
/** Unique provider name in the `ctx.skills` registry. */
|
|
readonly name: string
|
|
/**
|
|
* List available skill candidates for the current lookup context. Provider
|
|
* plugins register synchronously during `apply()`; remote initialization,
|
|
* authentication, and discovery are awaited inside this method. Implementations
|
|
* should settle promptly when `options.signal` aborts.
|
|
* @param options - lookup options; `cwd` selects workspace-sensitive skills and `signal` cancels work.
|
|
* @returns provider candidates with precedence ranks and opaque locators.
|
|
*/
|
|
readonly list: (options: SkillLookupOptions) => Promise<readonly SkillCandidate[]>
|
|
/**
|
|
* Load a complete skill body for a previously listed candidate.
|
|
* @param candidate - the winning candidate originally returned by this provider.
|
|
* @param options - lookup options; `cwd` selects workspace-sensitive skills and `signal` cancels work.
|
|
* @returns the full skill body, or `undefined` if it is no longer loadable.
|
|
*/
|
|
readonly get: (candidate: SkillCandidate, options: SkillLookupOptions) => Promise<SkillDefinition | undefined>
|
|
}
|
|
```
|
|
|
|
## Local discovery priority
|
|
|
|
The shipped local provider scans roots in rank order:
|
|
|
|
| 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` | `Config.bundledSkillDir` when configured |
|
|
|
|
The project root is the nearest ancestor containing `.git`; without one, the current cwd is used. When `ctx.fs` is available, the git-root walk probes `.git` through the filesystem service so remote or sandboxed workspaces do not fall back to the host filesystem boundary. The user DSH root skips its `.system` child. The local provider does not ship built-in system skills; deployments supply built-ins through another provider.
|
|
|
|
Chokidar watches existing roots for direct bundle/flat-entry additions and removals plus direct skill-entry changes. A missing root is followed one absent path segment at a time from its nearest existing ancestor until Chokidar can attach. Resource files below a bundle are not catalog changes. Model-facing `write` and `edit` observations synchronously invalidate the provider when their target is catalog-relevant, while the host watcher covers IDE, Git, shell, and external-process mutations. Watcher failures make the current observation incomplete; project-scoped watchers use a configured bounded LRU.
|
|
|
|
## Skill identity
|
|
|
|
Skill names are kebab-case (`^[a-z0-9]+(?:-[a-z0-9]+)*$`). The local provider accepts directory bundles (`<name>/SKILL.md`) and flat Markdown files (`<name>.md`). Nested recursive `**/SKILL.md` discovery is intentionally outside v1.
|
|
|
|
```ts type-equiv
|
|
/** Origin bucket for a skill contribution. The value is prompt-visible metadata, not precedence by itself. */
|
|
type SkillSource = 'project-dsh' | 'project-agents' | 'runtime' | 'user-dsh' | 'user-agents' | 'custom' | 'bundled' | (string & {})
|
|
```
|
|
|
|
## Summaries, candidates, and complete definitions
|
|
|
|
`SkillSummary` is the registry's model-invocable summary shape. Consumers choose which fields to render; the session catalog uses only `name` and `description`, never the body or absolute file path. `disableModelInvocation` hides a skill from model listings while allowing trusted code to load it by name.
|
|
|
|
```ts type-equiv
|
|
/** Model-visible skill metadata returned by `ctx.skills.list()` and rendered into request guidance. */
|
|
interface SkillSummary {
|
|
/** Kebab-case identifier used with the `skill` tool. */
|
|
readonly name: string
|
|
/** Short routing description shown to the model. */
|
|
readonly description: string
|
|
/** Optional extra routing guidance shown to the model. */
|
|
readonly whenToUse?: string
|
|
/** Whether the skill is hidden from model listings while remaining loadable by trusted callers. */
|
|
readonly disableModelInvocation?: boolean
|
|
/** Discovery source that produced this winning skill. */
|
|
readonly source: SkillSource
|
|
/** Provider that owns this skill body. */
|
|
readonly provider: string
|
|
/** Provider-specific base for relative resources. */
|
|
readonly resourceBase?: SkillResourceBase
|
|
}
|
|
```
|
|
|
|
`SkillCatalogSnapshot` distinguishes authoritative absence from transient provider failure. `skills` contains the sorted summaries collected in that observation; `complete` is true only when every registered provider completed. Incomplete snapshots are not cached, allowing a consumer to retain its last-good model catalog and retry.
|
|
|
|
```ts type-equiv
|
|
/** One catalog observation plus whether every registered provider completed discovery. */
|
|
interface SkillCatalogSnapshot {
|
|
/** Sorted model-invocable summaries from providers that completed. */
|
|
readonly skills: SkillSummary[]
|
|
/** Whether every registered provider completed discovery for this observation. */
|
|
readonly complete: boolean
|
|
}
|
|
```
|
|
|
|
`SkillCandidate` is the provider-to-registry shape. `locator` is opaque provider state; the registry only stores it and gives it back to the winning provider's `get()`.
|
|
|
|
```ts type-equiv
|
|
/** Provider catalog entry used by the registry to merge and later load skills. */
|
|
interface SkillCandidate extends SkillSummary {
|
|
/** Lower ranks win duplicate skill names before provider registration order is considered. */
|
|
readonly rank: number
|
|
/** Opaque provider-owned handle passed back to `provider.get()`. */
|
|
readonly locator: unknown
|
|
/** Absolute file path when the provider has one. */
|
|
readonly path?: string
|
|
/** Parsed optional metadata object from provider-specific skill frontmatter. */
|
|
readonly metadata?: Readonly<Record<string, unknown>>
|
|
}
|
|
```
|
|
|
|
`SkillDefinition` is the complete parsed result returned by `ctx.skills.get()` and used by the `skill` tool. `resourceBase` tells the tool how to render relative-resource guidance for local, URL, or provider-managed skills.
|
|
|
|
```ts type-equiv
|
|
/** Optional provider-specific base used by loaded skill bodies to resolve relative resources. */
|
|
type SkillResourceBase =
|
|
| { readonly kind: 'directory'; readonly path: string }
|
|
| { readonly kind: 'url'; readonly url: string }
|
|
| { readonly kind: 'opaque'; readonly description: string }
|
|
```
|
|
|
|
```ts type-equiv
|
|
/** Complete parsed skill definition, including the body loaded by `ctx.skills.get()`. */
|
|
interface SkillDefinition extends SkillSummary {
|
|
/** Markdown instruction body after any provider-specific metadata removal. */
|
|
readonly content: string
|
|
/** Absolute file path when the skill came from disk. */
|
|
readonly path?: string
|
|
/** Parsed optional metadata object from frontmatter. */
|
|
readonly metadata?: Readonly<Record<string, unknown>>
|
|
}
|
|
```
|
|
|
|
Runtime skills use the same complete shape and participate in the same first-wins collection order. The returned disposer removes the contribution and invalidates discovery caches.
|
|
|
|
```ts type-equiv
|
|
/** Runtime skill contribution accepted by `ctx.skills.register()`. */
|
|
type SkillRegistration = Omit<SkillDefinition, 'provider'> & { readonly provider?: string }
|
|
```
|
|
|
|
## Lookup and configuration
|
|
|
|
Skill lookup is cwd-sensitive because providers may expose workspace-local skills, and its optional signal cancels provider work for the caller. Providers receive the same readonly options object used for cache identity and loading. Cancellation is checked before and after catalog selection, including cache hits, and races both discovery and full-definition loading. If no git root is found, the local provider treats the supplied cwd itself as the project root.
|
|
|
|
Full definitions are not cached by the registry. Each `get()` calls the winning provider with the selected candidate, so the local provider rereads the current body. A definition whose name no longer matches that candidate is rejected and invalidates the exact provider for rediscovery.
|
|
|
|
```ts type-equiv
|
|
/** Caller context used for cwd-sensitive and abortable provider work. */
|
|
interface SkillLookupOptions {
|
|
/** Workspace selector for the current lookup. */
|
|
readonly cwd?: string | undefined
|
|
/** Abort discovery or loading work for the current caller. */
|
|
readonly signal?: AbortSignal | undefined
|
|
}
|
|
```
|
|
|
|
The registry owns only its discovery-cache bound. The local provider owns filesystem roots (`dshHome`, `agentsHome`, `customSkillDirs`, and optional `bundledSkillDir`/`DSH_BUNDLED_SKILL_DIR`) plus watcher enablement, polling, stability, symlink, and project-capacity controls. The consumer owns its catalog description bound. Exact defaults and validation are in the generated [config catalog](../config-catalog.md).
|
|
|
|
```ts type-equiv
|
|
/** Skill registry configuration. */
|
|
interface Config {
|
|
/** Maximum number of completed cwd/provider catalogs kept in memory. */
|
|
readonly collectCacheMaxEntries?: number
|
|
}
|
|
```
|
|
|
|
## Session catalog and tool contract
|
|
|
|
`dsh-tool-skill` injects the initial durable user-role `<system-reminder>` at the first `agent/step` of a live session that observes a non-empty complete view. The catalog contains sorted skill `name` and normalized, XML-escaped `description` only; it omits bodies, paths, sources, providers, and routing hints. Discovery forwards the step's abort signal through `SkillLookupOptions`. `catalogDescriptionMaxLength` is the consumer config for the description bound, with default `500` and integer minimum `3`.
|
|
|
|
Before each later model step, the consumer applies exact tool visibility and digests the exact rendered entries between the `<available_skills>` tags from a complete snapshot. It derives the comparison baseline from the same entries in the newest recognizable visible catalog message sourced by the plugin. A changed digest appends a durable full replacement through `agent.inject()`; deleting every skill appends an explicit empty replacement. Incomplete snapshots preserve the last-good model view. If compaction hides every historical catalog message, the next complete snapshot re-establishes the current catalog; an empty view with no prior catalog emits nothing. These catalog messages are session history, not World State.
|
|
|
|
The model-facing `skill({ name })` tool validates the kebab-case name, rereads the complete definition for the calling agent cwd, reports an unresolved skill as unknown or no longer available, rejects `disableModelInvocation` skills, and returns a tool result containing `<skill_content name="...">`, `<skill_resources>`, and `<skill_instructions>`. `resourceBase` resolves explicitly referenced scripts, references, and assets only as needed; the loaded result does not enumerate a skill directory. Body-only edits therefore change later tool calls without producing catalog messages or rewriting earlier tool results.
|