155 lines
8.6 KiB
Markdown
155 lines
8.6 KiB
Markdown
# @deepseek-ai/dsh-tool-skill
|
|
|
|
English | [中文](README.zh.md)
|
|
|
|
The model-facing skill catalog and `skill` tool.
|
|
|
|
Requires `ctx.agents`, `ctx.tools`, and `ctx.skills` (`inject: ['agents', 'tools', 'skills']`).
|
|
|
|
## Catalog lifecycle
|
|
|
|
The plugin contributes the initial user-role `<system-reminder>` catalog through `agent/session-prefix`. Before every later model step it observes `ctx.skills.snapshot()` and computes a digest over exact `skill` tool visibility plus the ordered rendered `name` and `description` entries. It resolves skills for the calling session's cwd and lists only those summaries; skill bodies, paths, sources, providers, and `whenToUse` hints remain outside the catalog.
|
|
|
|
When that digest changes, `agent.inject()` records a durable user-role message containing the complete replacement catalog and metadata `{ kind: 'skill-catalog', version: 1, digest }`. An empty replacement explicitly retires names from earlier catalogs. The latest still-visible metadata supplies the comparison baseline across replay or plugin reload. If compaction shadows that replacement, the next pre-step falls back to the loop's initial-prefix baseline and re-establishes the current catalog when needed. An incomplete provider snapshot emits nothing and preserves the last-good model view for retry on the next step. If no prior catalog exists and the current view is empty, no tombstone is necessary.
|
|
|
|
The catalog is omitted when no model-invocable skills are initially available, and also when that agent's tool view restricts away the shipped `skill` tool or resolves a same-name scoped shadow instead. Visibility changes participate in the digest, keeping prompt guidance, model-visible schema, and executable dispatch aligned.
|
|
|
|
`catalogDescriptionMaxLength` controls normalized, XML-escaped catalog descriptions. Its default is `500` and values must be integers of at least `3`, which reserves room for a truncation ellipsis. The [session-prefix Agent Note](../../../.agents/notes/implemented/feature/2026-07-07-session-prefix.md) defines the request-only, header-logged lifecycle of the initial message; the [skill catalog hot-refresh Agent Note](../../../.agents/notes/implemented/feature/2026-07-27-skill-catalog-hot-refresh.md) owns durable replacements.
|
|
|
|
## Tool: `skill`
|
|
|
|
| Arg | Type | Notes |
|
|
|---|---|---|
|
|
| `name` | string (required) | Exact kebab-case skill name from the available skills listing. |
|
|
|
|
Execution uses the calling agent's `session.header.cwd` so workspace-sensitive providers resolve the winning skill. A successful call returns canonical `{ name, provider, resourceBase?, content }`, excluding catalog ranking and provider-internal machinery; its Native renderer produces one text result containing `<skill_content name="...">`, `<skill_resources>`, and `<skill_instructions>`.
|
|
|
|
Resource guidance resolves only paths or URLs explicitly referenced by the instructions against `resourceBase`; scripts, references, and assets load on demand, and the result does not enumerate a skill directory. Local providers may supply a directory, while remote or embedded providers may supply a URL or opaque loading guidance.
|
|
|
|
An unresolved name reports that the skill is unknown or no longer available. Invalid names and `disableModelInvocation: true` skills produce distinct error results.
|
|
|
|
Tool execution does not call `agent.inject()`. Its freshly loaded result is already recorded as the tool result and becomes available to the next model step without duplicating the body as synthetic context. Only the catalog projection injects replacement summaries.
|
|
|
|
## Model Experience
|
|
|
|
### Session prefix
|
|
|
|
#### What the model sees
|
|
|
|
If model-invocable skills exist and this exact `skill` tool is visible, the agent receives the catalog template below, with one data-dependent entry per sorted skill. The initial catalog is a user-role session prefix. Later membership, description, or visibility changes append a complete replacement using the same `<available_skills>` envelope; deleting every skill appends an empty envelope with an explicit instruction not to use older names.
|
|
|
|
##### Skill catalog template
|
|
|
|
```markdown
|
|
<system-reminder>
|
|
A skill is a reusable set of task-specific instructions. The following skills are available in this session:
|
|
|
|
<available_skills>
|
|
- `<name>`: <normalized-and-capped-description>
|
|
</available_skills>
|
|
|
|
If the user names a skill, or the task clearly matches a skill's description, call the `skill` tool with the exact skill name before taking task actions. Load all applicable skills, then follow their full instructions. This catalog contains summaries only; do not infer or follow a skill's instructions until it has been loaded.
|
|
</system-reminder>
|
|
```
|
|
|
|
#### Token effect
|
|
|
|
Repeated input cost scales with skill count and `catalogDescriptionMaxLength`; no initial catalog tokens are sent when the list is empty or the tool is hidden or shadowed. Each actual catalog change adds one retained complete replacement message.
|
|
|
|
#### KV Cache effect
|
|
|
|
The initial catalog remains prefix-stable. Dynamic changes are append-only history after that prefix, so existing reusable tokens stay intact while the replacement and later turns form a new suffix.
|
|
|
|
### Tool schema
|
|
|
|
#### What the model sees
|
|
|
|
The model sees the generated [`skill` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-skill).
|
|
|
|
#### Token effect
|
|
|
|
Fixed schema cost per request where the tool is visible.
|
|
|
|
#### KV Cache effect
|
|
|
|
Prefix-stable while the tool definition and visibility are unchanged. Shadowing, restrictions, or plugin lifecycle changes may invalidate reuse from this schema.
|
|
|
|
### Tool result
|
|
|
|
#### What the model sees
|
|
|
|
A successful call uses the result template and the provider-managed, directory, URL, or opaque resource guidance below.
|
|
|
|
##### Skill result template
|
|
|
|
```markdown
|
|
<skill_content name="<escaped-name>">
|
|
<skill_resources>
|
|
<resource-guidance>
|
|
</skill_resources>
|
|
|
|
<skill_instructions>
|
|
<provider-owned-instruction-body>
|
|
</skill_instructions>
|
|
</skill_content>
|
|
```
|
|
|
|
##### Provider-managed resource guidance
|
|
|
|
```markdown
|
|
Resources for this skill are managed by provider "<provider>".
|
|
Load referenced resources only as needed.
|
|
```
|
|
|
|
##### Directory resource guidance
|
|
|
|
```markdown
|
|
Base directory for this skill: <path>
|
|
Resolve relative paths mentioned by this skill against the base directory before using them. Load referenced resources only as needed.
|
|
```
|
|
|
|
##### URL resource guidance
|
|
|
|
```markdown
|
|
Base URL for this skill: <url>
|
|
Resolve relative URLs mentioned by this skill against the base URL before using them. Load referenced resources only as needed.
|
|
```
|
|
|
|
##### Opaque resource guidance
|
|
|
|
```markdown
|
|
Resources for this skill: <description>
|
|
Load referenced resources only as needed.
|
|
```
|
|
|
|
#### Token effect
|
|
|
|
Loaded instructions are data-dependent tool-result tokens, resent on later steps until compaction; no duplicate `agent.inject()` copy is made.
|
|
|
|
#### KV Cache effect
|
|
|
|
Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
|
|
|
|
### Tool errors
|
|
|
|
#### What the model sees
|
|
|
|
Invalid or stale selections return exactly `Error: invalid skill name "<name>"`, `Error: skill "<name>" is unknown or no longer available`, or `Error: skill "<name>" is not available for model invocation`. Provider-thrown lookup text is data-dependent and receives the same `Error: <message>` wrapper.
|
|
|
|
#### Token effect
|
|
|
|
Only a failing call adds these retained tokens.
|
|
|
|
#### KV Cache effect
|
|
|
|
Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
|
|
|
|
## Known Limitations and Deferred Work
|
|
|
|
- **The catalog omits `whenToUse`, source, and provider metadata** — routing is based only on name and a capped description; `whenToUse` remains provider metadata and is not rendered by the loaded wrapper either.
|
|
- **Loaded instruction bodies have no size cap** — a provider can return a skill large enough to consume substantial next-step context; only catalog descriptions are truncated.
|
|
- **Resources are guidance, not attachments** — the tool reports a base directory/URL/opaque hint but neither enumerates nor fetches referenced files for the model.
|
|
- **Loading is one-shot text** — there is no partial, streaming, or cached-content handle when a remote provider is slow or a skill body is large.
|
|
- **Catalog replacement is whole-list** — one changed name or description appends every currently visible summary; this keeps stale-name retirement explicit but costs tokens proportional to the catalog.
|
|
- **Bodies are not versioned** — body-only edits do not change the catalog digest or notify the model; a later tool call reads the current provider content while earlier tool results remain historical facts.
|