@deepseek-ai/dsh-tool-skill 0.0.1-rc.1

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, DeepSeek
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/skill/tool-skill/README.md
+README.md: 704eb7eb1f611c20f76ce79190326296ff63da42
+README.zh.md: 09fb5b954ea595b962f7670ce09db1ae22dce29c

package/README.md

@@ -0,0 +1,169 @@
+# @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
+
+At every eligible `agent/pre-step`, the plugin calls `ctx.skills.snapshot()` for the calling session's cwd, forwards the pre-step abort signal to discovery, applies exact `skill` tool visibility, and renders the ordered `name` and `description` entries. When no prior catalog exists and that view is non-empty, it adds an initial durable user-role `<system-reminder>` to a downstream `enter` decision. Catalog messages contain only those summaries; skill bodies, paths, sources, providers, and `whenToUse` hints remain outside the catalog.
+
+Every catalog message carries the `skill-catalog` source: a `catalog`-form context whose `entries` record exactly the `name` and `description` pairs it published, plus `update` on a replacement. The digest covers those durable entries, not the rendered prose, so the surrounding `<system-reminder>` framing cannot decide whether a republish is needed and consumers never re-parse the `<available_skills>` block. The plugin scans durable session events backwards without copying them and derives the comparison baseline from the newest visible `skill-catalog` message it can read; unreadable and foreign records are skipped. When the digest changes, the downstream `enter` decision receives a durable user-role message containing the complete replacement catalog; an empty replacement explicitly retires earlier names. If no catalog remains visible but a recognizable historical catalog exists, compaction hid it and the next complete observation re-establishes the current catalog. An incomplete provider snapshot emits nothing and preserves the last-good model view for retry at the next pre-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. Identity is compared against the definition this plugin registered rather than a lookup of its own name, so the plugin works mounted globally or inside one agent's composition, where `register()` files into that agent's layer alone. Visibility changes participate in the digest, keeping prompt guidance, model-visible schema, and executable dispatch aligned.
+
+`catalogDescriptionMaxLength` controls normalized catalog descriptions; rendering XML-escapes them. Its default is `500` and values must be integers of at least `3`, which reserves room for a truncation ellipsis. The [skill catalog hot-refresh Agent Note](../../../.agents/notes/implemented/feature/2026-07-27-skill-catalog-hot-refresh.md) owns the durable initial catalog and replacement lifecycle.
+
+## 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 skills whose `invocation.modelInvocable` is `false` produce distinct error results. `invocation.userInvocable` does not restrict this model-facing surface.
+
+Tool execution does not add a synthetic context message. Its freshly loaded result is already recorded as the tool result and becomes available to the next model step without duplicating the body. Only the catalog projection adds replacement summaries.
+
+## Model Experience
+
+### Session catalog
+
+#### What the model sees
+
+If model-invocable skills exist and this exact `skill` tool is visible, the agent receives the catalog template below as a durable user-role message before the first request, with one data-dependent entry per sorted skill. 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. The template's closing sentence is the rule against double-loading: the user-explicit gesture boundary (the pre-step listener below) injects the same `renderSkillContent` output (shared from `@deepseek-ai/dsh-skill`) inline, and the catalog tells the model to follow that block instead of re-loading the skill through the tool; the replacement-catalog template carries the same sentence in both arms, including the emptied catalog.
+
+##### 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.
+A user may also invoke a skill directly; its <skill_content> block then appears in this conversation. Follow it, and do not call the `skill` tool again for that skill.
+</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 durable catalog is appended after the existing reusable prefix. Dynamic changes are append-only history after that catalog, so earlier reusable tokens stay intact while each newly appended catalog and later turns form a new suffix. A new or resumed instance with a changed digest may affect cache reuse from the newly appended catalog position.
+
+### 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.
+
+### User-explicit invocation injection
+
+#### What the model sees
+
+A whitespace-bounded `/name` token anywhere in a claimed user message, naming a user-invocable skill in the workspace catalog, injects that skill's full `<skill_content>` rendering (the exact result-template shape above) as a `user`-role instructions context appended after every other injection of that step — background first, the material to act on last. Only direct user input is scanned, the check runs on the loaded definition, and unknown or user-disabled names stay ordinary prose. This is the sole entry point for `disable-model-invocation` skills, which the catalog and the `skill` tool never expose; the catalog's closing sentence tells the model to follow the injected block instead of re-loading it.
+
+#### Token effect
+
+Each gesture adds one rendered skill body to that turn as injected context — the same size as the tool result for the same skill, paid deterministically at the user's request instead of at the model's discretion. Repeated gestures for one skill within one step inject once.
+
+#### KV Cache effect
+
+Append-only; the injection lands after the reusable request prefix inside the step's message batch 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.

package/README.zh.md

@@ -0,0 +1,169 @@
+# @deepseek-ai/dsh-tool-skill
+
+[English](README.md) | 中文
+
+面向模型的 skill（技能）目录和 `skill` 工具。
+
+需要 `ctx.agents`、`ctx.tools` 和 `ctx.skills`（`inject: ['agents', 'tools', 'skills']`）。
+
+## 目录生命周期
+
+每次符合条件的 `agent/pre-step`，该插件都会使用调用会话的 cwd 调用 `ctx.skills.snapshot()`，将 pre-step 中止信号转发到发现流程，应用 `skill` 工具的精确可见性，并按顺序渲染 `name` 和 `description` 条目。如果先前不存在目录且该视图非空，插件会向下游 `enter` 决策添加初始的持久用户角色 `<system-reminder>`。目录消息只包含这些摘要；skill 正文、路径、来源、提供方和 `whenToUse` 提示仍位于目录之外。
+
+每条目录消息都携带 `skill-catalog` 来源，也就是 `catalog` 形态的上下文。它的 `entries` 精确记录本次发布的 `name` 与 `description` 对，替换目录另带 `update`。digest 覆盖这些持久条目，而不是渲染后的正文，因此 `<system-reminder>` 包装不会影响是否需要重新发布，消费方也不需要重新解析 `<available_skills>` 块。插件从后向前扫描持久会话事件且不复制，并以最新一条仍可见且可读的 `skill-catalog` 消息作为比较基线；不可读和外来的记录都会跳过。digest 变化时，下游 `enter` 决策会收到一条包含完整替换目录的持久用户角色消息；空替换会显式停用较早的名称。如果没有目录仍然可见，但历史中存在可识别目录，则说明压缩（compaction）已将其遮蔽，下一次完整观察会重新建立当前目录。提供方快照不完整时，插件不会发送任何内容，并会保留最后一次完整的模型视图，在下一次 pre-step 重试。若不存在先前目录且当前视图为空，则不需要 tombstone。
+
+如果最初没有模型可调用 skill，则省略目录；如果该 agent（智能体）的工具视图排除了随附的 `skill` 工具，或解析出同名的作用域内遮蔽项，也会省略目录。身份比对针对本插件所注册的那个定义，而非按自身名字回查，因此本插件既可全局挂载，也可挂在单个 agent 的组装内——在后者中 `register()` 只归档进该 agent 的分层。可见性变更参与 digest 计算，使提示词指引、模型可见 schema 和可执行分派保持对齐。
+
+`catalogDescriptionMaxLength` 控制规范化后的目录描述，渲染时会对其执行 XML 转义。其默认值是 `500`，且必须是不小于 `3` 的整数，以便为截断省略号保留空间。[skill 目录热刷新 Agent Note](../../../.agents/notes/implemented/feature/2026-07-27-skill-catalog-hot-refresh.md) 负责定义持久初始目录和替换目录的生命周期。
+
+## 工具：`skill`
+
+| 参数 | 类型 | 说明 |
+|---|---|---|
+| `name` | string（必填） | 可用 skill 列表中精确的 kebab-case skill 名称。 |
+
+执行使用调用 agent 的 `session.header.cwd`，使结果随工作区变化的提供方能够解析出胜出的 skill。成功调用返回规范形式的 `{ name, provider, resourceBase?, content }`，其中不包含目录排名和提供方内部机制；其 Native 渲染器会生成一个文本结果，其中包含 `<skill_content name="...">`、`<skill_resources>` 和 `<skill_instructions>`。
+
+资源指引只会根据 `resourceBase` 解析指令显式引用的路径或 URL；脚本、参考资料和资源文件按需加载，结果不会列举 skill 目录。本地提供方可以提供目录，而远程或嵌入式提供方可以提供 URL 或不透明加载指引。
+
+无法解析的名称会报告 skill 未知或已不可用。无效名称和 `invocation.modelInvocable` 为 `false` 的 skill 会产生不同的错误结果。`invocation.userInvocable` 不限制这个面向模型的接口。
+
+工具执行不会添加合成上下文消息。新加载的结果已作为工具结果记录，并在下一个模型步骤可用，无需重复正文。只有目录投影会添加替换摘要。
+
+## 模型体验
+
+### 会话目录
+
+#### 模型看到的内容
+
+如果存在模型可调用 skill，且可见的正是这个 `skill` 工具，agent 会在第一个请求之前收到下方目录模板，其中包含每个已排序 skill 的一条随数据而定的条目。该目录是一条持久的用户角色消息。后续成员关系、描述或可见性的变化会使用同一个 `<available_skills>` 信封追加完整替换；删除所有 skill 时，会追加一个空信封，并明确指示不得使用旧名称。模板的结尾一句是防止双重加载的规则：用户显式的手势边界（下文的 pre-step 监听器）会把同一份 `renderSkillContent` 输出（共享自 `@deepseek-ai/dsh-skill`）内联注入，目录则告诉模型遵循该块，而不是再经工具重新加载该 skill；替换目录模板的两个臂——包括清空后的目录——都携带同一句话。
+
+##### Skill 目录模板
+
+```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.
+A user may also invoke a skill directly; its <skill_content> block then appears in this conversation. Follow it, and do not call the `skill` tool again for that skill.
+</system-reminder>
+```
+
+#### Token 影响
+
+重复输入成本随 skill 数量和 `catalogDescriptionMaxLength` 增长；当列表为空或工具被隐藏或遮蔽时，不会发送初始目录 token。每次实际目录变更都会添加一条保留的完整替换消息。
+
+#### KV Cache 影响
+
+初始持久目录追加在现有可重用前缀之后。动态变更作为该目录之后的仅追加历史，因此较早的可重用 token 保持不变，每条新追加的目录和后续轮次都会形成新的后缀。新建或恢复的实例如果 digest 发生变化，可能会从新追加的目录位置起影响缓存重用。
+
+### 工具 schema
+
+#### 模型看到的内容
+
+模型会看到生成的 [`skill` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-skill)。
+
+#### Token 影响
+
+工具可见时，每次请求都有固定的 schema token 开销。
+
+#### KV Cache 影响
+
+工具定义和可见性不变时，前缀稳定。遮蔽、限制或插件生命周期变更可能从该 schema 起使重用失效。
+
+### 工具结果
+
+#### 模型看到的内容
+
+成功调用使用下方结果模板，以及提供方管理的资源指引、目录资源指引、URL 资源指引或不透明资源指引。
+
+##### Skill 结果模板
+
+```markdown
+<skill_content name="<escaped-name>">
+<skill_resources>
+<resource-guidance>
+</skill_resources>
+
+<skill_instructions>
+<provider-owned-instruction-body>
+</skill_instructions>
+</skill_content>
+```
+
+##### 提供方管理的资源指引
+
+```markdown
+Resources for this skill are managed by provider "<provider>".
+Load referenced resources only as needed.
+```
+
+##### 目录资源指引
+
+```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 资源指引
+
+```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.
+```
+
+##### 不透明资源指引
+
+```markdown
+Resources for this skill: <description>
+Load referenced resources only as needed.
+```
+
+#### Token 影响
+
+已加载指令是取决于数据的工具结果 token，并在后续步骤中重新发送，直到压缩（compaction）；不会制作重复的 `agent.inject()` 副本。
+
+#### KV Cache 影响
+
+仅追加；新可见内容位于可重用请求前缀之后，不会使现有 KV Cache 条目失效。
+
+### 工具错误
+
+#### 模型看到的内容
+
+无效或陈旧选择会精确返回 `Error: invalid skill name "<name>"`、`Error: skill "<name>" is unknown or no longer available` 或 `Error: skill "<name>" is not available for model invocation`。提供方抛出的查找文本取决于数据，并接收同一个 `Error: <message>` 包装层。
+
+#### Token 影响
+
+只有失败调用会添加这些已保留 token。
+
+#### KV Cache 影响
+
+仅追加；新可见内容位于可重用请求前缀之后，不会使现有 KV Cache 条目失效。
+
+### 用户显式调用注入
+
+#### 模型看到的内容
+
+已认领用户消息中任意位置、以空白为界、指名工作区目录中某个用户可调用 skill 的 `/name` token，会把该 skill 的完整 `<skill_content>` 渲染（与上文结果模板完全相同的形态）作为 `user` 角色的指令上下文注入，追加在该步骤所有其他注入之后——背景在前，模型要着手处理的材料在最后。只扫描直接的用户输入，检查在已加载定义上进行，未知名称和用户不可调用的名称保持为普通行文。这是 `disable-model-invocation` skill 唯一的入口，目录和 `skill` 工具永不暴露这类 skill；目录的结尾一句会告诉模型遵循注入块，而不是重新加载它。
+
+#### Token 影响
+
+每次手势会把一份渲染后的 skill 正文作为注入上下文加进该轮次——尺寸与同一 skill 的工具结果相同，按用户的请求确定性地支付，而非由模型自行裁量。同一步骤内对同一 skill 的重复手势只注入一次。
+
+#### KV Cache 影响
+
+仅追加；注入落在该步骤的消息批次中、可重用请求前缀之后，不会使现有 KV Cache 条目失效。
+
+## 已知限制与暂缓事项
+
+- **目录省略 `whenToUse`、来源和提供方元数据**：路由只基于名称和有长度上限的描述；`whenToUse` 仍是提供方元数据，加载后的包装层也不渲染它。
+- **已加载指令正文没有大小上限**：提供方可返回足以占用大量下一步上下文的 skill；只有目录描述会被截断。
+- **资源是指引，而非附件**：工具报告基础目录/URL/不透明提示，但既不列举也不为模型获取引用文件。
+- **加载是一次性文本**：远程提供方缓慢或 skill 正文很大时，不提供部分内容、流式输出或缓存内容句柄。
+- **目录替换采用全量列表**：一个名称或描述发生变化，就会追加当前所有可见摘要；这样能显式停用陈旧名称，但 token 成本与目录大小成正比。
+- **正文不做版本化**：仅修改正文不会改变目录 digest，也不会通知模型；后续工具调用会读取提供方的当前内容，而先前工具结果仍是历史事实。

package/lib/index.js

@@ -0,0 +1,375 @@
+import { createHash } from "node:crypto";
+import z from "@deepseek-ai/schemastery";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import { createUserMessage } from "@deepseek-ai/dsh-llm";
+import { escapeText, isModelInvocable, isSkillName, isUserInvocable, renderSkillContent } from "@deepseek-ai/dsh-skill";
+//#region lib/types/index.js
+/**
+* Durable session skill catalog and model-facing `skill` loader tool.
+*
+* @module @deepseek-ai/dsh-tool-skill
+*/
+const name = "tool-skill";
+const inject = [
+	"agents",
+	"tools",
+	"skills"
+];
+const DEFAULT_CATALOG_DESCRIPTION_MAX_LENGTH = 500;
+/** Durable entry list mirroring the rendered catalog lines, for non-model consumers. */
+function catalogSourceEntries(skills, descriptionMaxLength) {
+	return skills.map((skill) => ({
+		name: skill.name,
+		description: catalogDescription(skill.description, descriptionMaxLength)
+	}));
+}
+/** Validate and default the model-facing skill catalog configuration. */
+const Config = z.object({ catalogDescriptionMaxLength: z.number().default(DEFAULT_CATALOG_DESCRIPTION_MAX_LENGTH) });
+/**
+* Register the model-facing skill loader and its visibility-matched
+* durable session catalog. The catalog is emitted only when the calling agent
+* resolves this plugin's exact tool registration; a restriction or scoped
+* same-name shadow therefore removes both the schema and its call guidance.
+*/
+function apply(ctx, config = {}) {
+	const catalogDescriptionMaxLength = config.catalogDescriptionMaxLength ?? DEFAULT_CATALOG_DESCRIPTION_MAX_LENGTH;
+	assertPositiveInteger("catalogDescriptionMaxLength", catalogDescriptionMaxLength, 3);
+	const skillTool = defineTool({
+		name: "skill",
+		description: "Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.",
+		parameters: { name: {
+			type: "string",
+			required: true,
+			description: "The exact skill name from the available skills list."
+		} },
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					name: {
+						type: "string",
+						required: true
+					},
+					provider: {
+						type: "string",
+						required: true
+					},
+					resourceBase: { oneOf: [
+						{
+							type: "object",
+							additionalProperties: false,
+							properties: {
+								kind: {
+									type: "string",
+									required: true,
+									const: "directory"
+								},
+								path: {
+									type: "string",
+									required: true
+								}
+							}
+						},
+						{
+							type: "object",
+							additionalProperties: false,
+							properties: {
+								kind: {
+									type: "string",
+									required: true,
+									const: "url"
+								},
+								url: {
+									type: "string",
+									required: true
+								}
+							}
+						},
+						{
+							type: "object",
+							additionalProperties: false,
+							properties: {
+								kind: {
+									type: "string",
+									required: true,
+									const: "opaque"
+								},
+								description: {
+									type: "string",
+									required: true
+								}
+							}
+						}
+					] },
+					content: {
+						type: "string",
+						required: true
+					}
+				}
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: renderSkillContent(value)
+			}]
+		},
+		async execute(args, exec) {
+			if (!isSkillName(args.name)) throw new Error(`invalid skill name "${args.name}"`);
+			const lookup = {
+				cwd: exec.agent?.session.header.cwd,
+				signal: exec.signal,
+				scope: exec.agent
+			};
+			const summary = (await ctx.skills.list(lookup)).find((skill) => skill.name === args.name);
+			if (!summary) throw new Error(`skill "${args.name}" is unknown or no longer available`);
+			if (!isModelInvocable(summary)) throw new Error(`skill "${args.name}" is not available for model invocation`);
+			const skill = await ctx.skills.get(args.name, lookup);
+			if (!skill) throw new Error(`skill "${args.name}" is unknown or no longer available`);
+			if (!isModelInvocable(skill)) throw new Error(`skill "${args.name}" is not available for model invocation`);
+			return {
+				name: skill.name,
+				provider: skill.provider,
+				...skill.resourceBase !== void 0 ? { resourceBase: { ...skill.resourceBase } } : {},
+				content: skill.content
+			};
+		},
+		presentCall(args) {
+			return {
+				card: "generic",
+				title: `Load skill ${args.name}`,
+				kind: "read",
+				rawInput: args.name
+			};
+		}
+	});
+	ctx.tools.register(skillTool);
+	ctx.on("agent/pre-step", async ({ agent, messages, signal }, next) => {
+		const decision = await next();
+		if (decision.kind === "reject") return decision;
+		const names = invokedSkillNames(messages);
+		if (names.length === 0) return decision;
+		signal.throwIfAborted();
+		const lookup = {
+			cwd: agent.session.header.cwd,
+			signal,
+			scope: agent
+		};
+		const injections = [];
+		for (const name of names) {
+			const skill = await ctx.skills.get(name, lookup);
+			signal.throwIfAborted();
+			if (skill === void 0 || !isUserInvocable(skill)) continue;
+			const source = {
+				kind: "skill-invocation",
+				name,
+				form: "instructions"
+			};
+			injections.push(createUserMessage({
+				content: [{
+					type: "text",
+					text: renderSkillContent(skill)
+				}],
+				source
+			}));
+		}
+		if (injections.length === 0) return decision;
+		return {
+			kind: "enter",
+			messages: [...decision.messages, ...injections]
+		};
+	});
+	ctx.on("agent/pre-step", async ({ agent, signal }, next) => {
+		const decision = await next();
+		if (decision.kind === "reject") return decision;
+		signal.throwIfAborted();
+		const snapshot = ctx.tools.get(skillTool.name, agent) === skillTool ? await ctx.skills.snapshot({
+			cwd: agent.session.header.cwd,
+			signal,
+			scope: agent
+		}) : {
+			skills: [],
+			complete: true
+		};
+		signal.throwIfAborted();
+		if (!snapshot.complete) return decision;
+		const skills = snapshot.skills.filter(isModelInvocable);
+		const entries = catalogSourceEntries(skills, catalogDescriptionMaxLength);
+		const digest = digestCatalogEntries(entries);
+		const history = catalogHistory(agent);
+		const existing = catalogMessage(decision.messages);
+		if (history.visibleDigest === digest) return existing === void 0 ? decision : {
+			kind: "enter",
+			messages: decision.messages.filter((message) => message.id !== existing.message.id)
+		};
+		if (existing !== void 0 && digestCatalogEntries(existing.entries) === digest) return decision;
+		if (!history.published && skills.length === 0) return existing === void 0 ? decision : {
+			kind: "enter",
+			messages: decision.messages.filter((message) => message.id !== existing.message.id)
+		};
+		const catalog = history.published ? renderCatalogUpdate(entries) : renderCatalogMessage(entries);
+		return {
+			kind: "enter",
+			messages: existing === void 0 ? [...decision.messages, catalog] : decision.messages.map((message) => message.id === existing.message.id ? catalog : message)
+		};
+	});
+}
+function renderCatalogMessage(entries) {
+	return createUserMessage({
+		content: [{
+			type: "text",
+			text: [
+				"<system-reminder>",
+				"A skill is a reusable set of task-specific instructions. The following skills are available in this session:",
+				"",
+				"<available_skills>",
+				...renderCatalogEntries(entries),
+				"</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.",
+				"A user may also invoke a skill directly; its <skill_content> block then appears in this conversation. Follow it, and do not call the `skill` tool again for that skill.",
+				"</system-reminder>"
+			].join("\n")
+		}],
+		source: {
+			kind: "skill-catalog",
+			form: "catalog",
+			entries
+		}
+	});
+}
+function renderCatalogUpdate(entries) {
+	const availability = entries.length === 0 ? ["No skills are currently available through the `skill` tool. Do not use names from earlier skill catalogs.", "A user may still invoke a skill directly; its <skill_content> block then appears in this conversation. Follow it, and do not call the `skill` tool for it."] : ["Use only names in this replacement catalog. If the user names a listed skill, or the task clearly matches its description, call the `skill` tool with the exact name before acting.", "A user may also invoke a skill directly; its <skill_content> block then appears in this conversation. Follow it, and do not call the `skill` tool again for that skill."];
+	return createUserMessage({
+		content: [{
+			type: "text",
+			text: [
+				"<system-reminder>",
+				"The available skill catalog changed. This complete catalog replaces every earlier available-skills list in this session:",
+				"",
+				"<available_skills>",
+				...renderCatalogEntries(entries),
+				"</available_skills>",
+				"",
+				...availability,
+				"</system-reminder>"
+			].join("\n")
+		}],
+		source: {
+			kind: "skill-catalog",
+			form: "catalog",
+			update: true,
+			entries
+		}
+	});
+}
+/**
+* Model-facing catalog lines, projected from the same entries the source records.
+* The pseudo-XML escaping belongs to this frame, not to the published fact, so it
+* is applied here and never stored. Names are `isSkillName`-validated and carry
+* no escapable character.
+*/
+function renderCatalogEntries(entries) {
+	return entries.map((entry) => `- \`${entry.name}\`: ${escapeText(entry.description)}`);
+}
+/**
+* Catalog identity over the durable entry list rather than the rendered prose.
+* The entries are what changes; the surrounding `<system-reminder>` framing is
+* written for the model and must not decide whether a republish is needed.
+*/
+function digestCatalogEntries(entries) {
+	const canonical = entries.map((entry) => JSON.stringify([entry.name, entry.description])).join("\n");
+	return createHash("sha256").update(canonical).digest("hex");
+}
+/**
+* Entries of one durable catalog message, or undefined when the record is not a
+* usable catalog.
+*
+* `agent.session.events` may be a resumed, forked, or externally written seed,
+* and seed validation only guarantees a source object with a non-empty `kind`;
+* no per-kind field is checked there. An unreadable record is therefore treated
+* as "not this plugin's catalog" — the posture the replaced content digest had —
+* rather than throwing inside the step listener, which would fail every
+* subsequent turn of that session.
+*/
+function readCatalogEntries(source) {
+	const entries = source.entries;
+	if (!Array.isArray(entries)) return void 0;
+	const readable = [];
+	for (const entry of entries) {
+		if (typeof entry !== "object" || entry === null) return void 0;
+		const { name, description } = entry;
+		if (typeof name !== "string" || name === "" || typeof description !== "string") return void 0;
+		readable.push({
+			name,
+			description
+		});
+	}
+	return readable;
+}
+function catalogHistory(agent) {
+	const visible = new Set(agent.session.surface.nodes);
+	const events = agent.session.events;
+	let published = false;
+	for (let index = events.length - 1; index >= 0; index -= 1) {
+		const event = events[index];
+		if (event.type !== "user/message" || event.data.source.kind !== "skill-catalog") continue;
+		const entries = readCatalogEntries(event.data.source);
+		if (entries === void 0) continue;
+		const digest = digestCatalogEntries(entries);
+		published = true;
+		if (visible.has(event.seq)) return {
+			visibleDigest: digest,
+			published
+		};
+	}
+	return { published };
+}
+function catalogMessage(messages) {
+	for (const message of messages) {
+		if (message.source.kind !== "skill-catalog") continue;
+		const entries = readCatalogEntries(message.source);
+		if (entries !== void 0) return {
+			message,
+			entries
+		};
+	}
+}
+/** Normalized, length-bounded description exactly as the catalog publishes it (unescaped). */
+function catalogDescription(value, maxLength) {
+	const normalized = value.replaceAll(/\s+/g, " ").trim();
+	return normalized.length <= maxLength ? normalized : `${normalized.slice(0, maxLength - 3)}...`;
+}
+function assertPositiveInteger(name, value, minimum = 1) {
+	if (!Number.isInteger(value) || value < minimum) throw new Error(`tool-skill: ${name} must be an integer greater than or equal to ${minimum}`);
+}
+/**
+* A whitespace-bounded `/name` token (the public skill-name grammar) anywhere
+* in the text — the same word-boundary shape the transcript chip decoration
+* uses, so a gesture reads as one wherever it sits in the sentence. A second
+* `/` or any non-boundary character breaks the match, which keeps file paths
+* (`/usr/bin`) and fractions (`5/8`) out.
+*/
+const SKILL_GESTURE = /(^|\s)\/([a-z0-9]+(?:-[a-z0-9]+)*)(?=\s|$)/g;
+/**
+* `/name` gesture tokens from the claimed user messages, deduplicated in
+* first-seen order. Every text block of direct user input is scanned; no
+* other source can forge a gesture.
+* @param messages - the step's claimed batch.
+* @returns candidate skill names, unvalidated against the registry.
+*/
+function invokedSkillNames(messages) {
+	const names = [];
+	for (const message of messages) {
+		if (message.source.kind !== "user") continue;
+		for (const block of message.content) {
+			if (block.type !== "text") continue;
+			for (const match of block.text.matchAll(SKILL_GESTURE)) {
+				const name = match[2];
+				if (name !== void 0 && !names.includes(name)) names.push(name);
+			}
+		}
+	}
+	return names;
+}
+//#endregion
+export { Config, apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-tool-skill`.
+* @module @deepseek-ai/dsh-tool-skill/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-tool-skill";
+/** Cordis companion plugin name. */
+const name = "tool-skill-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this model-facing adapter has no independent lifecycle stream; execution
+* relations are owned by the capability seam it calls.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Durable session skill catalog and model-facing `skill` loader tool.
+ *
+ * @module @deepseek-ai/dsh-tool-skill
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+export declare const name = "tool-skill";
+export declare const inject: string[];
+/**
+ * Durable provider and item records for one published session skill catalog. The catalog is a
+ * `catalog`-form context, so it records the entries it published beside the
+ * model-facing prose: a consumer presenting the list must not re-parse the
+ * `<available_skills>` block, whose framing exists for the model.
+ */
+export interface SkillCatalogSource {
+    readonly kind: 'skill-catalog';
+    readonly form: 'catalog';
+    /** Marks a replacement catalog rather than this session's first publication. */
+    readonly update?: true;
+    /** Exactly the entries this message published, in catalog order. */
+    readonly entries: readonly {
+        readonly name: string;
+        readonly description: string;
+    }[];
+}
+declare module '@deepseek-ai/dsh-llm' {
+    interface MessageSourceMap {
+        'skill-catalog': SkillCatalogSource;
+    }
+}
+/** Model-facing skill catalog configuration. */
+export interface Config {
+    /** Maximum normalized description length rendered in the session catalog; minimum 3. */
+    catalogDescriptionMaxLength?: number;
+}
+/** Validate and default the model-facing skill catalog configuration. */
+export declare const Config: z<Config>;
+/**
+ * Register the model-facing skill loader and its visibility-matched
+ * durable session catalog. The catalog is emitted only when the calling agent
+ * resolves this plugin's exact tool registration; a restriction or scoped
+ * same-name shadow therefore removes both the schema and its call guidance.
+ */
+export declare function apply(ctx: Context, config?: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-tool-skill`.
+ * @module @deepseek-ai/dsh-tool-skill/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "tool-skill-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@deepseek-ai/dsh-tool-skill",
+  "description": "Model-facing skill loading tool for the DeepSeek Harness",
+  "version": "0.0.1-rc.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/skill/tool-skill"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-skill": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.0.1-rc.1"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-scope": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-agent": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-skill": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-skill-local": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  }
+}