@deepseek-ai/dsh-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/skill/README.md
+README.md: 9c27a271f03f33d2b53984a6a5c18082ccc6169a
+README.zh.md: 085dec3e342c2f42a39d28b995dcb4e2cf38f440

package/README.md

@@ -0,0 +1,79 @@
+# @deepseek-ai/dsh-skill
+
+English | [中文](README.zh.md)
+
+Pure agent skill provider registry.
+
+This package owns the `ctx.skills` interface. It does not know whether skills come from local files, embedded plugin data, HTTP, or another backend; providers register those sources with `ctx.skills.registerProvider(...)`. The shipped local implementation is [`@deepseek-ai/dsh-skill-local`](../skill-local).
+
+The registry is host+per-scope layered over [`@deepseek-ai/dsh-scope`](../../core/scope), the shape the tools registry established: a registration files into the layer of its calling context's scope — host rows and repository plugins land in the global layer, a plugin mounted by an agent preset's standing composition lands in that preset's layer — and a read merges the global layer with the viewing scope's chain, the nearest layer winning a duplicate name outright while rank decides duplicates only within one layer.
+
+## Service: `SkillService` (ctx key: `skills`)
+
+### Public API
+
+- `ctx.skills.registerProvider(create): () => void` Calls a synchronous provider factory with `{ signal, invalidate }`, then registers its readonly result by `provider.name`, unique within the calling context's layer. Duplicate names in one layer throw, `runtime` is reserved, and failed registration aborts the signal. The exact Cordis disposer unregisters the provider, aborts the signal, and preserves ordered composite teardown.
+- `ctx.skills.snapshot({ cwd?, signal?, scope? })` Returns the invocation-neutral `{ skills, complete }` observation for the viewing scope's merged layers. `complete` is false when any provider rejects or explicitly reports incomplete discovery, or when a second catalog revision races the bounded retry; candidates supplied by that observation remain in this result, which is never cached.
+- `ctx.skills.list({ cwd?, signal?, scope? })` Borrows the readonly view options, then returns every winning summary for the current workspace, merged across the global layer and the viewing scope's chain and sorted by name. Consumers apply `isModelInvocable(skill)` or `isUserInvocable(skill)` at their own boundary.
+- `ctx.skills.get(name, { cwd?, signal?, scope? })` Uses the same readonly options and winning candidate for discovery and loading, rechecks cancellation after discovery or a cache hit, races provider loading against the signal, validates the loaded definition, then returns it regardless of invocation policy.
+- `ctx.skills.register(skill): () => void` Registers a readonly runtime embedded skill into the calling context's layer, adding the all-invocable policy and `provider: "runtime"` when omitted. Same-name runtime registrations in one layer are first-wins: a duplicate logs a warning and gets a no-op disposer. Successful registrations return the exact Cordis disposer for ordered composite teardown.
+
+### Events
+
+- `skills/change` is an unfiltered invalidation notification emitted after a provider or runtime contribution is registered or disposed and after an active provider's registration control invalidates. It carries no catalog or diff: each consumer refetches `snapshot()` with its own lookup options. Listener throws and rejected promises are logged and cannot veto the registry mutation or starve later listeners.
+
+### Config
+
+| Field | Default | Meaning |
+|---|---|---|
+| `collectCacheMaxEntries` | `128` | Maximum completed cwd/provider catalogs kept in memory. |
+
+### Invocation policy
+
+`SkillSummary.invocation` is a required typed policy object whose positive booleans `modelInvocable` and `userInvocable` describe the two surfaces independently. Providers return this resolved shape on every candidate and definition; only the `SkillRegistration` input may omit it, in which case `register()` supplies `{ modelInvocable: true, userInvocable: true }`. The registry keeps all four combinations so one discovery result can serve model-facing tools, human-facing commands, and trusted internal callers without conflating their catalogs.
+
+| Policy | Model | User |
+|---|---|---|
+| `{ modelInvocable: true, userInvocable: true }` | included | included |
+| `{ modelInvocable: true, userInvocable: false }` | included | excluded |
+| `{ modelInvocable: false, userInvocable: true }` | excluded | included |
+| `{ modelInvocable: false, userInvocable: false }` | excluded | excluded |
+
+### Shared model-facing rendering
+
+`renderSkillContent(skill)` renders one loaded skill as the canonical `<skill_content>` block (escaped `name` attribute, resource hints, verbatim body). It is the single truth for both loading paths: `dsh-tool-skill` returns it as the `skill` tool result and injects it at the user-explicit gesture boundary, so the model sees one shape regardless of who initiated the load. `escapeText` is exported beside it for consumers embedding prose in the same markup frame. The package also declares the `skill-invocation` `MessageSource` kind ({ name, form: 'instructions' }) that user-explicit injection stamps on its messages — transcript consumers present the invocation from this metadata instead of re-parsing the body.
+
+`isModelInvocable(skill)` and `isUserInvocable(skill)` read the matching positive field directly. `ctx.skills.get()` remains the trusted, policy-neutral loading primitive, so every user- or model-facing consumer must enforce the predicate that matches its surface before exposing or loading a skill.
+
+## Provider Contract
+
+A provider factory runs synchronously and receives one registration-scoped control. `control.signal` aborts when registration fails or is disposed; `control.invalidate()` clears completed catalogs only while that exact registration remains active, so late callbacks cannot affect a replacement with the same name. Immutable providers may ignore the control. Remote setup, authentication, and discovery belong in the provider's awaited `list(options)` call. An array return is shorthand for complete discovery; a provider that collected usable candidates but could not establish an authoritative observation returns `{ candidates, complete: false }`. Provider objects, lookup options, candidates, and definitions are borrowed readonly rather than cloned or rebound. Providers should honor `options.signal`; the registry also stops awaiting uncooperative discovery or loading after cancellation.
+
+The registry validates candidates before caching and definitions before returning them. The winning provider receives the same candidate and opaque `locator` it returned from `list()`, allowing backend-specific file, URL, id, or version handles. Callers and providers must preserve the readonly contract.
+
+Contract violations fail fast. A rejected provider `list()` is treated as a transient source failure and omitted. An explicit incomplete observation still contributes its candidates for `list()` and `get()`, but makes the aggregate snapshot incomplete and uncacheable. A provider or runtime revision change discards an in-flight result and retries once. If the retry is also superseded, its candidates are returned incomplete and uncached so a continuously invalidating provider cannot monopolize the caller. Within one layer, duplicate names resolve by rank, provider registration order, then provider-local order; across layers the nearest scope's entry wins the name. Summaries are sorted by skill name.
+
+Definitions remain progressively loaded. `get()` asks the winning provider for the body on every call rather than caching it in this registry. If the returned definition has a different name from the selected candidate, the stale selection is rejected and the registry internally invalidates that exact provider so the next snapshot rediscovers its catalog.
+
+## Runtime Skills
+
+`ctx.skills.register(...)` is a convenience for embedded runtime skills. Runtime skills use rank `250`: project providers can override them, while they override the shipped local provider's custom and user roots. Runtime definitions and nested resource metadata are borrowed readonly; the service materializes one top-level definition to supply omitted invocation and provider defaults. Registration is first-wins within runtime contributions, so a duplicate contribution cannot remove the active one through its disposer.
+
+## Consumer boundary
+
+The registry does not render model guidance or register model-facing tools. [`@deepseek-ai/dsh-tool-skill`](../tool-skill) consumes `ctx.skills` to provide durable session catalogs and the `skill` tool, so providers remain independent of the model surface.
+
+## Model Experience
+
+Indirectly, through `dsh-tool-skill`, which renders provider summaries into durable initial or replacement catalog messages and loaded instructions into retained tool results.
+
+#### KV Cache effect
+
+No direct prompt effect. The named consumer owns the durable initial catalog and append-only replacements after invalidation.
+
+## Known Limitations and Deferred Work
+
+- **Invalidation is provider-driven** — the registry has no TTL and cannot infer that an arbitrary remote source changed; each mutable provider must retain and call its registration-scoped `invalidate()` capability from its own observation mechanism.
+- **Providers are queried sequentially** — one slow cooperative provider delays every provider registered after it; cancellation stops the caller's wait but cannot terminate work an uncooperative provider keeps running.
+- **Incomplete observations are not retained** — rejected providers are omitted and explicitly supplied candidates remain available only to the current lookup; the registry owns neither a last-good catalog nor per-provider diagnostics.
+- **Duplicate resolution is first-wins** — later lower-priority candidates within a layer are logged and hidden, and a nearer layer shadows a farther one silently; there is no API to inspect all shadowed definitions.

package/README.zh.md

@@ -0,0 +1,79 @@
+# @deepseek-ai/dsh-skill
+
+[English](README.md) | 中文
+
+纯 agent skill（智能体技能）提供方注册表。
+
+该包负责 `ctx.skills` 接口。它不知道 skill 来自本地文件、嵌入式插件数据、HTTP 还是其他后端；提供方通过 `ctx.skills.registerProvider(...)` 注册这些来源。已发布的本地实现是 [`@deepseek-ai/dsh-skill-local`](../skill-local)。
+
+注册表基于 [`@deepseek-ai/dsh-scope`](../../core/scope) 采用宿主 + 按 scope 的分层结构，即工具注册表确立的形态：注册落入调用方上下文 scope 对应的层——宿主行与 repository 插件落入全局层，由 agent preset 常驻组合挂载的插件落入该 preset 的层——读取时将全局层与观察 scope 的链合并，最近层直接赢得重名，rank 只在单层内裁决重名。
+
+## 服务：`SkillService`（ctx 键：`skills`）
+
+### 公开 API
+
+- `ctx.skills.registerProvider(create): () => void` 调用同步提供方工厂并向其传入 `{ signal, invalidate }`，随后以在调用方上下文所在层内唯一的 `provider.name` 注册其只读结果。同层重复提供方名称会抛错，`runtime` 为保留名称；注册失败会中止信号。精确的 Cordis disposer 会注销提供方、中止信号，并保持有序组合拆卸。
+- `ctx.skills.snapshot({ cwd?, signal?, scope? })` 返回观察 scope 各层合并后、与调用策略无关的 `{ skills, complete }` 观测。任一提供方调用被拒绝或显式报告发现不完整，或有界重试期间又发生目录修订时，`complete` 为 false；该次观测提供的候选项仍保留在此结果中，但该结果绝不缓存。
+- `ctx.skills.list({ cwd?, signal?, scope? })` 借用只读视图选项，然后返回当前工作区中的全部胜出摘要；这些摘要在全局层与观察 scope 链之间合并，并按名称排序。消费方在自身边界调用 `isModelInvocable(skill)` 或 `isUserInvocable(skill)`。
+- `ctx.skills.get(name, { cwd?, signal?, scope? })` 在发现和加载中使用同一组只读选项和胜出候选项；在发现或缓存命中后重新检查取消，让提供方加载与信号竞速，验证已加载定义，然后无论调用策略如何都将其返回。
+- `ctx.skills.register(skill): () => void` 将只读运行时嵌入式 skill 注册进调用方上下文所在层，省略时添加允许模型和用户调用的策略以及 `provider: "runtime"`。同层同名运行时注册使用先到先得：重复项会记录警告，并获得无操作 disposer。成功注册会返回精确的 Cordis disposer，以供有序组合拆卸。
+
+### 事件
+
+- `skills/change` 是一条不带过滤条件的失效通知，在提供方或运行时贡献注册或释放后，以及活动提供方的注册控制触发失效后发出。它不携带目录或 diff；每个消费方都使用自身的查找选项重新获取 `snapshot()`。监听器抛错或 Promise 拒绝会被记录，既不能否决注册表变更，也不能阻止后续监听器执行。
+
+### 配置
+
+| 字段 | 默认值 | 含义 |
+|---|---|---|
+| `collectCacheMaxEntries` | `128` | 内存中保留的最大已完成 cwd/提供方目录数。 |
+
+### 调用策略
+
+`SkillSummary.invocation` 是一个必填的类型化策略对象，其正向布尔字段 `modelInvocable` 和 `userInvocable` 分别描述两个接口。提供方会在每个候选项和定义中返回这一已解析形状；只有 `SkillRegistration` 输入可以省略它，此时 `register()` 会补入 `{ modelInvocable: true, userInvocable: true }`。注册表保留全部四种组合，使一次发现结果可以同时服务面向模型的工具、面向用户的命令和受信内部调用方，而不会混淆各自的目录。
+
+| 策略 | 模型 | 用户 |
+|---|---|---|
+| `{ modelInvocable: true, userInvocable: true }` | 包含 | 包含 |
+| `{ modelInvocable: true, userInvocable: false }` | 包含 | 排除 |
+| `{ modelInvocable: false, userInvocable: true }` | 排除 | 包含 |
+| `{ modelInvocable: false, userInvocable: false }` | 排除 | 排除 |
+
+### 共享的面向模型渲染
+
+`renderSkillContent(skill)` 把一个已加载 skill 渲染为规范的 `<skill_content>` 块（转义后的 `name` 属性、资源提示、原样正文）。它是两条加载路径的唯一真源：`dsh-tool-skill` 将其作为 `skill` 工具结果返回，并在用户显式的手势边界将其注入，因此无论加载由谁发起，模型看到的都是同一种形态。`escapeText` 随之一并导出，供要在同一标记框架中嵌入文案的消费方使用。该包还声明 `skill-invocation` 这个 `MessageSource` kind（{ name, form: 'instructions' }），用户显式注入会把它打在自己的消息上——transcript（文本记录）消费方依据这份元数据呈现该次调用，而不是重新解析正文。
+
+`isModelInvocable(skill)` 和 `isUserInvocable(skill)` 分别直接读取对应的正向字段。`ctx.skills.get()` 仍是受信且与策略无关的加载原语，因此每个面向用户或模型的消费方都必须先执行与自身接口匹配的判定，再暴露或加载 skill。
+
+## 提供方约定
+
+提供方工厂同步运行，并接收一项注册作用域内的控制能力。注册失败或释放时，`control.signal` 会中止；仅当该精确注册仍处于活动状态时，`control.invalidate()` 才会清除已完成目录，因此延迟回调无法影响同名替代项。不可变提供方可以忽略该控制能力。远程设置、身份验证和发现由提供方可等待的 `list(options)` 调用执行。返回数组是完整发现的简写形式；若提供方已收集到可用候选项，却无法建立权威观测，则返回 `{ candidates, complete: false }`。提供方对象、查找选项、候选项和定义都以只读方式借用，而不是克隆或重新绑定。提供方应遵守 `options.signal`；取消后，注册表也会停止等待不协作的发现或加载。
+
+注册表在缓存前验证候选项，在返回前验证定义。胜出提供方会收到同一候选项和不透明 `locator`，两者都是它从 `list()` 返回的内容，从而支持后端专用文件、URL、id 或版本句柄。调用方和提供方必须保持只读约定。
+
+违反约定时会快速失败。`list()` 返回的 Promise 被拒绝会被视为瞬时来源失败，并省略其结果。显式的不完整观测仍会为 `list()` 和 `get()` 提供其候选项，但会使聚合快照不完整且不可缓存。提供方或运行时修订发生变化时，会丢弃正在进行的结果并重试一次。如果这次重试也被后续修订取代，则返回其候选项，并将结果标为不完整且不予缓存，以免持续触发失效的提供方一直占用调用方。单层内重复名称依次按 rank、提供方注册顺序和提供方本地顺序解决冲突；跨层则由最近 scope 的条目赢得名称。摘要按 skill 名称排序。
+
+定义仍采用渐进式加载。`get()` 每次调用都会向胜出提供方请求正文，而不是在此注册表中缓存正文。若返回定义的名称不同于所选候选项，系统会拒绝该陈旧选择，并由注册表在内部使该精确提供方失效，以便下一次快照重新发现其目录。
+
+## 运行时 skill
+
+`ctx.skills.register(...)` 是嵌入式运行时 skill 的便利接口。运行时 skill 使用 rank `250`：项目提供方可覆盖它们，它们则覆盖已发布本地提供方的自定义根目录和用户根目录。运行时定义和嵌套资源元数据均以只读方式借用；服务只物化补入默认调用策略和 `provider` 所需的顶层定义。运行时贡献内的注册使用先到先得，因此重复贡献无法通过其 disposer 移除当前生效的贡献。
+
+## 消费方边界
+
+注册表不渲染模型指引，也不注册面向模型的工具。[`@deepseek-ai/dsh-tool-skill`](../tool-skill) 消费 `ctx.skills` 以提供持久会话目录和 `skill` 工具，因此提供方仍与模型接口独立。
+
+## 模型体验
+
+通过 `dsh-tool-skill` 间接影响模型；该包将提供方摘要渲染到持久的初始目录或替换目录消息中，并将已加载指令渲染到已保留工具结果中。
+
+#### KV Cache 影响
+
+不直接影响提示词。指定的消费方负责持久初始目录，以及失效后的仅追加式目录替换。
+
+## 已知限制与暂缓事项
+
+- **失效由提供方驱动**：注册表没有 TTL，无法推断任意远程来源是否已发生变化；每个可变提供方都必须保留其注册作用域内的 `invalidate()` 能力，并由自身的观测机制调用它。
+- **提供方依次查询**：一个响应取消但速度缓慢的提供方会延迟之后注册的所有提供方；取消会停止调用方等待，但无法终止不响应取消的提供方持续运行的工作。
+- **不保留不完整观测**：被拒绝的提供方会被省略，显式提供的候选项也仅在当前查找中可用；注册表既不负责上一份可用目录，也不负责逐提供方诊断。
+- **重复解析使用先到先得**：系统会记录并隐藏层内较晚出现的低优先级候选项，较近的层会静默遮蔽较远的层；不提供检查全部被遮蔽定义的 API。

package/lib/index.js

@@ -0,0 +1,565 @@
+import { Service } from "@deepseek-ai/cordis";
+import { assertNever } from "@deepseek-ai/dsh-llm";
+import { NamedEntries, ScopedLayers, scopeChainOf, scopeOf } from "@deepseek-ai/dsh-scope";
+import z from "@deepseek-ai/schemastery";
+//#region lib/types/index.js
+/**
+* Agent skill provider registry.
+*
+* This package owns the Service Definition role of the skill capability seam.
+* Concrete
+* providers such as `@deepseek-ai/dsh-skill-local` decide where skills come
+* from; this service only merges provider catalogs, resolves the winning skill
+* for a name, and exposes the winning summaries and definitions to consumers.
+*
+* @module @deepseek-ai/dsh-skill
+*/
+const SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const DEFAULT_COLLECT_CACHE_ENTRIES = 128;
+const MAX_COLLECT_ATTEMPTS = 2;
+const RUNTIME_PROVIDER = "runtime";
+const RUNTIME_RANK = 250;
+/** Standard precedence rank for packaged skill providers and local bundled roots. */
+const BUNDLED_SKILL_RANK = 600;
+/**
+* Return whether a string is a valid kebab-case skill name.
+* @param name - candidate skill name to validate.
+* @returns whether the name matches the public skill-name grammar.
+*/
+function isSkillName(name) {
+	return SKILL_NAME.test(name);
+}
+/**
+* Return whether a skill may be advertised to and loaded by a model.
+* @param skill - skill metadata carrying resolved invocation controls.
+* @returns whether the policy permits model invocation.
+*/
+function isModelInvocable(skill) {
+	return skill.invocation.modelInvocable;
+}
+/**
+* Return whether a skill may be advertised to and loaded by a human-facing command.
+* @param skill - skill metadata carrying resolved invocation controls.
+* @returns whether the policy permits user invocation.
+*/
+function isUserInvocable(skill) {
+	return skill.invocation.userInvocable;
+}
+/**
+* Render one loaded skill for the model. The output is shared verbatim by the
+* `skill` tool result and the user-explicit invocation injection, so the model
+* sees one canonical `<skill_content>` shape on both paths. The name rides an
+* escaped attribute; the body is embedded verbatim (skills are trusted local
+* content, and user-supplied invocation text stays outside this wrapper).
+* @param skill - name, provider, optional resource base, and body to render.
+* @returns the complete model-facing `<skill_content>` block.
+*/
+function renderSkillContent(skill) {
+	const resourceHint = renderResourceHint(skill);
+	return [
+		`<skill_content name="${escapeAttr(skill.name)}">`,
+		"<skill_resources>",
+		...resourceHint,
+		"</skill_resources>",
+		"",
+		"<skill_instructions>",
+		skill.content,
+		"</skill_instructions>",
+		"</skill_content>"
+	].join("\n");
+}
+function renderResourceHint(skill) {
+	const base = skill.resourceBase;
+	if (base === void 0) return [`Resources for this skill are managed by provider "${escapeText(skill.provider)}".`, "Load referenced resources only as needed."];
+	switch (base.kind) {
+		case "directory": return [`Base directory for this skill: ${escapeText(base.path)}`, "Resolve relative paths mentioned by this skill against the base directory before using them. Load referenced resources only as needed."];
+		case "url": return [`Base URL for this skill: ${escapeText(base.url)}`, "Resolve relative URLs mentioned by this skill against the base URL before using them. Load referenced resources only as needed."];
+		case "opaque": return [`Resources for this skill: ${escapeText(base.description)}`, "Load referenced resources only as needed."];
+		/* v8 ignore start -- SkillResourceBase is a closed union; a future kind must fail compilation here. */
+		default: return assertNever(base, "SkillResourceBase.kind");
+	}
+}
+function escapeAttr(value) {
+	return value.replaceAll("&", "&amp;").replaceAll("\"", "&quot;").replaceAll("<", "&lt;");
+}
+/**
+* Escape model-facing prose embedded inside skill markup so provider-supplied
+* text cannot open or close framing tags.
+* @param value - raw prose to embed.
+* @returns the escaped text.
+*/
+function escapeText(value) {
+	return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+/** One scope's complete skill-registry contribution. */
+var SkillLayer = class {
+	/** Providers registered through contexts carrying this scope, insertion-ordered. */
+	providers;
+	/** Runtime skills registered through contexts carrying this scope. */
+	runtime = /* @__PURE__ */ new Map();
+	constructor(scope) {
+		this.providers = new NamedEntries((name) => /* @__PURE__ */ new Error(scope === void 0 ? `a skill provider named "${name}" is already registered` : `a skill provider named "${name}" is already registered in this scope`));
+	}
+	/** Whether every contribution table in this aggregate layer is empty. */
+	isEmpty() {
+		return this.providers.isEmpty() && this.runtime.size === 0;
+	}
+};
+/**
+* Layered registry of skill providers, the host+per-scope shape the tools
+* registry established. A registration files into the layer of its calling
+* context's scope ({@link scopeOf}): host rows and repository plugins land in
+* the global layer, while a plugin mounted by an agent preset's standing
+* composition lands in that preset's layer. A read merges the global layer
+* with the viewing scope's chain — the nearest layer's entry wins a duplicate
+* name outright, and the rank order decides duplicates only within one layer.
+* It exposes sorted invocation-neutral summaries and loads full skill bodies
+* on demand.
+*/
+var SkillService = class extends Service {
+	static Config = z.object({ collectCacheMaxEntries: z.number().default(DEFAULT_COLLECT_CACHE_ENTRIES) });
+	collectCacheMaxEntries;
+	layers = new ScopedLayers((scope) => new SkillLayer(scope), () => {
+		this.invalidateCache();
+	});
+	collectCache = /* @__PURE__ */ new Map();
+	revision = 0;
+	nextProviderOrder = 0;
+	/** Stable identities for cache keys; scope keys are opaque identity-compared objects. */
+	scopeIds = /* @__PURE__ */ new WeakMap();
+	nextScopeId = 1;
+	constructor(ctx, config = {}) {
+		super(ctx, "skills");
+		this.collectCacheMaxEntries = config.collectCacheMaxEntries ?? DEFAULT_COLLECT_CACHE_ENTRIES;
+		assertPositiveInteger("collectCacheMaxEntries", this.collectCacheMaxEntries);
+	}
+	/**
+	* Register a borrowed same-process provider synchronously during plugin
+	* apply, into the calling context's layer: a scoped context (an agent
+	* preset's standing mount) registers for that scope alone, an unscoped
+	* context registers globally. Duplicate names within one layer and reserved
+	* names throw; remote initialization belongs in `list()`. Fiber disposal
+	* unregisters the provider and invalidates catalog caches.
+	* @param create - synchronous factory receiving this registration's lifecycle and invalidation control.
+	* @returns the exact Cordis effect disposer that unregisters this provider;
+	*   composite effects may yield it directly to preserve teardown ordering.
+	*/
+	registerProvider(create) {
+		const lifecycle = new AbortController();
+		let registration;
+		let provider;
+		const control = {
+			signal: lifecycle.signal,
+			invalidate: () => {
+				const active = registration;
+				if (active !== void 0 && active.layer.providers.get(active.name)?.provider === provider) this.invalidateCache();
+			}
+		};
+		try {
+			provider = create(control);
+			const name = provider.name;
+			if (name === RUNTIME_PROVIDER) throw new Error(`"${RUNTIME_PROVIDER}" is reserved for runtime skill registrations`);
+			const order = this.nextProviderOrder;
+			this.nextProviderOrder += 1;
+			return this.layers.effect(this.ctx, (layer) => {
+				const undo = layer.providers.insert(name, {
+					provider,
+					order
+				});
+				registration = {
+					layer,
+					name
+				};
+				return () => {
+					registration = void 0;
+					undo();
+					lifecycle.abort(/* @__PURE__ */ new Error(`skill provider "${name}" disposed`));
+				};
+			}, { label: "skills.registerProvider()" });
+		} catch (error) {
+			lifecycle.abort(error);
+			throw error;
+		}
+	}
+	/**
+	* Register a borrowed readonly runtime skill into the calling context's
+	* layer. Project entries outrank runtime entries, which outrank user
+	* entries, within one layer. Same-name runtime entries in one layer are
+	* first-wins; a duplicate logs a warning and receives a no-op disposer so
+	* it cannot remove the winner.
+	* @param skill - the skill definition input; omitted invocation and provider fields receive defaults.
+	* @returns the exact Cordis effect disposer, preserving composite teardown order and invalidating caches.
+	*/
+	register(skill) {
+		validateRuntimeSkill(skill);
+		const scope = scopeOf(this.ctx);
+		const existingLayer = scope === void 0 ? this.layers.global : this.layers.peek(scope);
+		if (existingLayer !== void 0 && existingLayer.runtime.has(skill.name)) {
+			this.ctx.logger.warn(`runtime skill "${skill.name}" ignored because it is already registered`);
+			return () => {};
+		}
+		const definition = {
+			...skill,
+			invocation: skill.invocation ?? {
+				modelInvocable: true,
+				userInvocable: true
+			},
+			provider: skill.provider ?? RUNTIME_PROVIDER
+		};
+		return this.layers.effect(this.ctx, (layer) => {
+			layer.runtime.set(definition.name, definition);
+			return () => {
+				layer.runtime.delete(definition.name);
+			};
+		}, { label: "skills.register()" });
+	}
+	/**
+	* List invocation-neutral skill summaries for a workspace. Consumers apply
+	* model or user invocation policy at their operational boundary. Lookup
+	* options and provider candidates are readonly same-process values borrowed
+	* throughout discovery.
+	* @param options - view options; `scope` selects the viewing agent's layers, `cwd` selects project roots, and `signal` cancels discovery.
+	* @returns all sorted winning summaries.
+	*/
+	async list(options = {}) {
+		return (await this.snapshot(options)).skills;
+	}
+	/**
+	* Observe the current invocation-neutral catalog and whether discovery completed within a stable revision.
+	* Incomplete observations are never cached, allowing consumers to retain last-good state and
+	* retry on their next request boundary.
+	* @param options - view options; `scope` selects the viewing agent's layers, `cwd` selects project roots, and `signal` cancels discovery.
+	* @returns sorted summaries plus discovery-completeness state.
+	*/
+	async snapshot(options = {}) {
+		const collected = await this.collect(options);
+		return {
+			skills: [...collected.entries.values()].map((entry) => toSummary(entry.candidate)).sort(compareSkillSummary),
+			complete: collected.cacheable
+		};
+	}
+	/**
+	* Load and validate the winning candidate, passing its opaque discovery locator back to the
+	* provider. Cancellation is rechecked after selection, including cache hits, and raced against
+	* loading so an uncooperative provider cannot hang the caller.
+	* @param name - kebab-case skill name.
+	* @param options - view options; `scope` selects the viewing agent's layers,
+	*   `cwd` selects workspace-sensitive skills, and `signal` cancels work.
+	* @returns the full skill, including body content, or `undefined`.
+	*/
+	async get(name, options = {}) {
+		if (!isSkillName(name)) return void 0;
+		const collected = await this.collect(options);
+		throwIfAborted(options.signal);
+		const match = collected.entries.get(name);
+		if (match === void 0) return void 0;
+		const definition = await waitWithAbort(match.provider.get(match.candidate, options), options.signal);
+		if (definition === void 0) return void 0;
+		validateDefinition(definition);
+		if (definition.name !== match.candidate.name) {
+			this.invalidateEntry(match);
+			return;
+		}
+		return definition;
+	}
+	async collect(options) {
+		throwIfAborted(options.signal);
+		let attempt = 1;
+		while (true) {
+			const revision = this.revision;
+			const key = this.collectCacheKey(options.cwd, scopeChainOf(options.scope), revision);
+			const cached = this.collectCache.get(key);
+			if (cached !== void 0) return {
+				entries: cached,
+				cacheable: true
+			};
+			const result = await this.collectFresh(options);
+			throwIfAborted(options.signal);
+			if (revision !== this.revision) {
+				if (attempt < MAX_COLLECT_ATTEMPTS) {
+					attempt += 1;
+					continue;
+				}
+				return {
+					entries: result.entries,
+					cacheable: false
+				};
+			}
+			if (result.cacheable) {
+				this.collectCache.set(key, result.entries);
+				if (this.collectCache.size > this.collectCacheMaxEntries) {
+					const oldest = this.collectCache.keys().next();
+					this.collectCache.delete(oldest.value);
+				}
+			}
+			return result;
+		}
+	}
+	async collectFresh(options) {
+		const layers = [this.layers.global, ...this.layers.chainLayers(options.scope)];
+		const merged = /* @__PURE__ */ new Map();
+		let cacheable = true;
+		for (const layer of layers) {
+			const collected = await this.collectLayer(layer, options);
+			if (!collected.cacheable) cacheable = false;
+			for (const entry of collected.entries) merged.set(entry.candidate.name, entry);
+		}
+		return {
+			entries: merged,
+			cacheable
+		};
+	}
+	async collectLayer(layer, options) {
+		const collected = await this.listLayerCandidates(layer, options);
+		collected.entries.sort(compareIndexedCandidates);
+		const seen = /* @__PURE__ */ new Set();
+		const result = [];
+		for (const entry of collected.entries) {
+			const skill = entry.candidate;
+			if (seen.has(skill.name)) {
+				this.ctx.logger.warn(`skill "${skill.name}" from ${skill.source} ignored because a higher-priority skill already exists`);
+				continue;
+			}
+			seen.add(skill.name);
+			result.push(entry);
+		}
+		return {
+			entries: result,
+			cacheable: collected.cacheable
+		};
+	}
+	async listLayerCandidates(layer, options) {
+		throwIfAborted(options.signal);
+		const candidates = [];
+		let cacheable = true;
+		let runtimeOrder = 0;
+		for (const skill of [...layer.runtime.values()].sort((a, b) => compareCodePoints(a.name, b.name))) {
+			candidates.push({
+				candidate: runtimeCandidate(skill),
+				provider: RUNTIME_SKILL_PROVIDER,
+				providerOrder: -1,
+				localOrder: runtimeOrder,
+				layer
+			});
+			runtimeOrder += 1;
+		}
+		for (const { provider, order } of [...layer.providers.values()]) {
+			let localOrder = 0;
+			let output;
+			try {
+				output = await waitWithAbort(provider.list(options), options.signal);
+			} catch (error) {
+				if (options.signal?.aborted === true) throw toError(options.signal.reason);
+				cacheable = false;
+				this.ctx.logger.warn(`skill provider "${provider.name}" skipped: ${errorMessage(error)}`);
+			}
+			if (output === void 0) continue;
+			const observation = normalizeProviderObservation(output, provider.name);
+			if (!observation.complete) cacheable = false;
+			for (const candidate of observation.candidates) {
+				validateCandidate(candidate, provider.name);
+				candidates.push({
+					candidate,
+					provider,
+					providerOrder: order,
+					localOrder,
+					layer
+				});
+				localOrder += 1;
+			}
+		}
+		return {
+			entries: candidates,
+			cacheable
+		};
+	}
+	invalidateCache() {
+		this.revision += 1;
+		this.collectCache.clear();
+		this.notifyChange();
+	}
+	/** Invalidate after a stale definition load, only while the exact registration that produced the entry is still live. */
+	invalidateEntry(entry) {
+		/* v8 ignore else -- A definition load can outlive the exact provider registration it selected. */
+		if (entry.layer.providers.get(entry.provider.name)?.provider === entry.provider) this.invalidateCache();
+	}
+	scopeId(key) {
+		let id = this.scopeIds.get(key);
+		if (id === void 0) {
+			id = this.nextScopeId;
+			this.nextScopeId += 1;
+			this.scopeIds.set(key, id);
+		}
+		return id;
+	}
+	collectCacheKey(cwd, chain, revision) {
+		return JSON.stringify({
+			cwd,
+			scopes: chain.map((key) => this.scopeId(key)),
+			revision
+		});
+	}
+	/** Notify catalog observers without making their refresh work load-bearing. */
+	notifyChange() {
+		for (const callback of this.ctx.events.dispatch("emit", ["skills/change"])) try {
+			const returned = callback();
+			Promise.resolve(returned).catch((error) => {
+				this.ctx.logger.warn(`skills/change listener rejected: ${errorMessage(error)}`);
+			});
+		} catch (error) {
+			this.ctx.logger.warn(`skills/change listener threw: ${errorMessage(error)}`);
+		}
+	}
+};
+function normalizeProviderObservation(output, providerName) {
+	if (Array.isArray(output)) return {
+		candidates: output,
+		complete: true
+	};
+	if (output === null || typeof output !== "object") throw invalidProviderObservation(providerName);
+	const observation = output;
+	if (!Array.isArray(observation.candidates) || typeof observation.complete !== "boolean") throw invalidProviderObservation(providerName);
+	return observation;
+}
+function invalidProviderObservation(providerName) {
+	return /* @__PURE__ */ new TypeError(`skill provider "${providerName}" list() must return an array or { candidates, complete } observation`);
+}
+const RUNTIME_SKILL_PROVIDER = {
+	name: RUNTIME_PROVIDER,
+	/* v8 ignore next -- Runtime skills are injected directly by the registry; this provider only owns `get()`. */
+	list() {
+		return Promise.resolve([]);
+	},
+	get(candidate) {
+		return Promise.resolve(candidate.locator);
+	}
+};
+function runtimeCandidate(skill) {
+	return {
+		name: skill.name,
+		description: skill.description,
+		...skill.whenToUse !== void 0 ? { whenToUse: skill.whenToUse } : {},
+		invocation: skill.invocation,
+		source: skill.source,
+		provider: skill.provider,
+		...skill.resourceBase !== void 0 ? { resourceBase: skill.resourceBase } : {},
+		rank: RUNTIME_RANK,
+		locator: skill,
+		...skill.path !== void 0 ? { path: skill.path } : {},
+		...skill.metadata !== void 0 ? { metadata: skill.metadata } : {}
+	};
+}
+function validateCandidate(candidate, providerName) {
+	if (typeof candidate.name !== "string") throw new TypeError(`skill provider "${providerName}" returned a non-string skill name`);
+	if (!SKILL_NAME.test(candidate.name)) throw new Error(`skill provider "${providerName}" returned invalid skill name "${candidate.name}"`);
+	if (typeof candidate.description !== "string") throw new TypeError(`skill provider "${providerName}" returned skill "${candidate.name}" with a non-string description`);
+	if (candidate.description.length === 0) throw new Error(`skill provider "${providerName}" returned skill "${candidate.name}" without a description`);
+	validateInvocation(candidate.invocation, `skill provider "${providerName}" returned skill "${candidate.name}"`);
+	if (candidate.whenToUse !== void 0 && typeof candidate.whenToUse !== "string") throw new TypeError(`skill provider "${providerName}" returned skill "${candidate.name}" with a non-string whenToUse`);
+	if (typeof candidate.source !== "string") throw new TypeError(`skill provider "${providerName}" returned skill "${candidate.name}" with a non-string source`);
+	if (typeof candidate.rank !== "number" || !Number.isFinite(candidate.rank)) throw new Error(`skill provider "${providerName}" returned skill "${candidate.name}" with an invalid rank`);
+	if (typeof candidate.provider !== "string") throw new TypeError(`skill provider "${providerName}" returned skill "${candidate.name}" with a non-string provider`);
+	if (candidate.provider !== providerName) throw new Error(`skill provider "${providerName}" returned skill "${candidate.name}" for provider "${candidate.provider}"`);
+	if (candidate.path !== void 0 && typeof candidate.path !== "string") throw new TypeError(`skill provider "${providerName}" returned skill "${candidate.name}" with a non-string path`);
+}
+function validateRuntimeSkill(skill) {
+	if (!SKILL_NAME.test(skill.name)) throw new Error(`invalid skill name "${skill.name}"`);
+	if (skill.description.length === 0) throw new Error(`skill "${skill.name}" requires a description`);
+	validateInvocation(skill.invocation, `runtime skill "${skill.name}"`);
+}
+/** Validate a definition loaded from a provider-controlled parser or remote source. */
+function validateDefinition(skill) {
+	const name = skill.name;
+	const description = skill.description;
+	const whenToUse = skill.whenToUse;
+	const invocation = skill.invocation;
+	const source = skill.source;
+	const provider = skill.provider;
+	const content = skill.content;
+	const path = skill.path;
+	if (typeof name !== "string") throw new TypeError("loaded skill name must be a string");
+	if (!SKILL_NAME.test(name)) throw new Error(`loaded skill has invalid name "${name}"`);
+	if (typeof description !== "string") throw new TypeError(`loaded skill "${name}" description must be a string`);
+	if (description.length === 0) throw new Error(`loaded skill "${name}" requires a description`);
+	validateInvocation(invocation, `loaded skill "${name}"`);
+	if (whenToUse !== void 0 && typeof whenToUse !== "string") throw new TypeError(`loaded skill "${name}" whenToUse must be a string`);
+	if (typeof source !== "string") throw new TypeError(`loaded skill "${name}" source must be a string`);
+	if (typeof provider !== "string") throw new TypeError(`loaded skill "${name}" provider must be a string`);
+	if (typeof content !== "string") throw new TypeError(`loaded skill "${name}" content must be a string`);
+	if (path !== void 0 && typeof path !== "string") throw new TypeError(`loaded skill "${name}" path must be a string`);
+}
+function toSummary(skill) {
+	const { name, description, whenToUse, invocation, source, provider, resourceBase } = skill;
+	return {
+		name,
+		description,
+		...whenToUse !== void 0 ? { whenToUse } : {},
+		invocation,
+		source,
+		provider,
+		...resourceBase !== void 0 ? { resourceBase } : {}
+	};
+}
+function validateInvocation(invocation, subject) {
+	if (invocation === void 0) return;
+	if (typeof invocation !== "object" || invocation === null || Array.isArray(invocation)) throw new TypeError(`${subject} with a non-object invocation policy`);
+	const policy = invocation;
+	if (typeof policy.modelInvocable !== "boolean") throw new TypeError(`${subject} with a non-boolean invocation.modelInvocable`);
+	if (typeof policy.userInvocable !== "boolean") throw new TypeError(`${subject} with a non-boolean invocation.userInvocable`);
+}
+function compareSkillSummary(left, right) {
+	return compareCodePoints(left.name, right.name);
+}
+function compareCodePoints(left, right) {
+	if (left < right) return -1;
+	if (left > right) return 1;
+	return 0;
+}
+function compareIndexedCandidates(left, right) {
+	return left.candidate.rank - right.candidate.rank || left.providerOrder - right.providerOrder || left.localOrder - right.localOrder;
+}
+function assertPositiveInteger(name, value, minimum = 1) {
+	if (!Number.isInteger(value) || value < minimum) throw new Error(`skill: ${name} must be an integer greater than or equal to ${minimum}`);
+}
+function waitWithAbort(promise, signal) {
+	if (signal === void 0) return promise;
+	throwIfAborted(signal);
+	return new Promise((resolve, reject) => {
+		const cleanup = () => {
+			signal.removeEventListener("abort", onAbort);
+		};
+		const onAbort = () => {
+			cleanup();
+			reject(toError(signal.reason));
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+		promise.then((value) => {
+			cleanup();
+			resolve(value);
+		}, (error) => {
+			cleanup();
+			reject(toError(error));
+		});
+	});
+}
+/** Throw a total Error for an already-aborted lookup. */
+function throwIfAborted(signal) {
+	if (signal?.aborted === true) throw toError(signal.reason);
+}
+/** Normalize an arbitrary abort or provider failure without trusting coercion. */
+function toError(error) {
+	try {
+		if (error instanceof Error) return error;
+	} catch {}
+	return new Error(errorMessage(error));
+}
+/** Render an arbitrary provider failure without letting coercion escape containment. */
+function errorMessage(error) {
+	try {
+		return String(error);
+	} catch {
+		return "[unrenderable thrown value]";
+	}
+}
+//#endregion
+export { BUNDLED_SKILL_RANK, SkillService, SkillService as default, escapeText, isModelInvocable, isSkillName, isUserInvocable, renderSkillContent };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-skill`.
+* @module @deepseek-ai/dsh-skill/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-skill";
+/** Cordis companion plugin name. */
+const name = "skill-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: provider/runtime maps and revisioned caches mutate atomically inside the
+* registry, which exposes no independent change event or snapshot for cross-checking them.
+*/
+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,300 @@
+/**
+ * Agent skill provider registry.
+ *
+ * This package owns the Service Definition role of the skill capability seam.
+ * Concrete
+ * providers such as `@deepseek-ai/dsh-skill-local` decide where skills come
+ * from; this service only merges provider catalogs, resolves the winning skill
+ * for a name, and exposes the winning summaries and definitions to consumers.
+ *
+ * @module @deepseek-ai/dsh-skill
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+import type { ScopeKey } from '@deepseek-ai/dsh-scope';
+import type Schema from '@deepseek-ai/schemastery';
+/** Standard precedence rank for packaged skill providers and local bundled roots. */
+export declare const BUNDLED_SKILL_RANK = 600;
+/**
+ * Return whether a string is a valid kebab-case skill name.
+ * @param name - candidate skill name to validate.
+ * @returns whether the name matches the public skill-name grammar.
+ */
+export declare function isSkillName(name: string): boolean;
+/** Origin bucket for a skill contribution. The value is prompt-visible metadata, not precedence by itself. */
+export type SkillSource = 'project-dsh' | 'project-agents' | 'runtime' | 'user-dsh' | 'user-agents' | 'custom' | 'bundled' | (string & {});
+/** Optional provider-specific base used by loaded skill bodies to resolve relative resources. */
+export type SkillResourceBase = {
+    readonly kind: 'directory';
+    readonly path: string;
+} | {
+    readonly kind: 'url';
+    readonly url: string;
+} | {
+    readonly kind: 'opaque';
+    readonly description: string;
+};
+/** Invocation controls shared by skill discovery consumers. */
+export interface SkillInvocationPolicy {
+    /** Whether model-facing catalogs and loaders include this skill. */
+    readonly modelInvocable: boolean;
+    /** Whether human-facing command catalogs and loaders include this skill. */
+    readonly userInvocable: boolean;
+}
+/** Invocation-neutral skill metadata returned by `ctx.skills.list()`. */
+export interface SkillSummary {
+    /** Kebab-case identifier used to address the skill. */
+    readonly name: string;
+    /** Short routing description shown by discovery consumers. */
+    readonly description: string;
+    /** Optional extra routing guidance. */
+    readonly whenToUse?: string;
+    /** Resolved model and user invocation controls. */
+    readonly invocation: SkillInvocationPolicy;
+    /** 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;
+}
+/** Provider catalog entry used by the registry to merge and later load skills. */
+export 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>>;
+}
+/** Complete parsed skill definition, including the body loaded by `ctx.skills.get()`. */
+export 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 skill contribution accepted by `ctx.skills.register()`. */
+export type SkillRegistration = Omit<SkillDefinition, 'invocation' | 'provider'> & {
+    /** Invocation controls; omission permits both model and user surfaces. */
+    readonly invocation?: SkillInvocationPolicy;
+    /** Provider label; omission uses the registry-owned runtime provider. */
+    readonly provider?: string;
+};
+/** Caller context used for cwd-sensitive and abortable provider work. */
+export 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;
+}
+/**
+ * Registry read options: provider lookup context plus the viewing scope.
+ * The registry consumes `scope` to select layers; providers receive the same
+ * borrowed options object and read only their {@link SkillLookupOptions}
+ * contract from it.
+ */
+export interface SkillViewOptions extends SkillLookupOptions {
+    /** Viewing scope (the calling agent); omitted reads the global layer alone. */
+    readonly scope?: ScopeKey | undefined;
+}
+/**
+ * Return whether a skill may be advertised to and loaded by a model.
+ * @param skill - skill metadata carrying resolved invocation controls.
+ * @returns whether the policy permits model invocation.
+ */
+export declare function isModelInvocable(skill: Pick<SkillSummary, 'invocation'>): boolean;
+/**
+ * Return whether a skill may be advertised to and loaded by a human-facing command.
+ * @param skill - skill metadata carrying resolved invocation controls.
+ * @returns whether the policy permits user invocation.
+ */
+export declare function isUserInvocable(skill: Pick<SkillSummary, 'invocation'>): boolean;
+/**
+ * Durable source for the context message a user-explicit skill invocation
+ * injects: the user's own words ride a plain user message, and the rendered
+ * skill body follows as injected `instructions`-form context carrying this
+ * source, so transcript consumers present the injection from metadata
+ * instead of re-parsing the model-facing text.
+ */
+export interface SkillInvocationSource {
+    readonly kind: 'skill-invocation';
+    /** Invoked skill name, validated user-invocable at the injecting boundary. */
+    readonly name: string;
+    /** Injected skill bodies are instructions for the model to follow. */
+    readonly form: 'instructions';
+}
+declare module '@deepseek-ai/dsh-llm' {
+    interface MessageSourceMap {
+        /** A user-explicit skill invocation injected by the host. */
+        'skill-invocation': SkillInvocationSource;
+    }
+}
+/**
+ * Render one loaded skill for the model. The output is shared verbatim by the
+ * `skill` tool result and the user-explicit invocation injection, so the model
+ * sees one canonical `<skill_content>` shape on both paths. The name rides an
+ * escaped attribute; the body is embedded verbatim (skills are trusted local
+ * content, and user-supplied invocation text stays outside this wrapper).
+ * @param skill - name, provider, optional resource base, and body to render.
+ * @returns the complete model-facing `<skill_content>` block.
+ */
+export declare function renderSkillContent(skill: Pick<SkillDefinition, 'name' | 'provider' | 'resourceBase' | 'content'>): string;
+/**
+ * Escape model-facing prose embedded inside skill markup so provider-supplied
+ * text cannot open or close framing tags.
+ * @param value - raw prose to embed.
+ * @returns the escaped text.
+ */
+export declare function escapeText(value: string): string;
+/** One catalog observation plus whether discovery completed within a stable catalog revision. */
+export interface SkillCatalogSnapshot {
+    /** Sorted invocation-neutral summaries collected in this observation. */
+    readonly skills: SkillSummary[];
+    /** Whether every registered provider completed without a concurrent catalog revision. */
+    readonly complete: boolean;
+}
+/** Provider candidates plus whether the current discovery is authoritative. */
+export interface SkillProviderObservation {
+    /** Candidates available from the current provider discovery. */
+    readonly candidates: readonly SkillCandidate[];
+    /** Whether discovery completed and these candidates may be cached. */
+    readonly complete: boolean;
+}
+/** Provider interface for one source of skills, such as local directories or a remote registry. */
+export 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 as a complete-array shorthand, or an explicit
+     *   observation when usable candidates came from incomplete discovery.
+     */
+    readonly list: (options: SkillLookupOptions) => Promise<readonly SkillCandidate[] | SkillProviderObservation>;
+    /**
+     * 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>;
+}
+/** Registration-scoped lifecycle and invalidation capability borrowed by one provider. */
+export interface SkillProviderControl {
+    /** Aborts if registration fails or when the exact provider registration is disposed. */
+    readonly signal: AbortSignal;
+    /** Invalidate completed catalogs and notify consumers only while the exact registration remains active. */
+    readonly invalidate: () => void;
+}
+/** Skill registry configuration. */
+export interface Config {
+    /** Maximum number of completed cwd/provider catalogs kept in memory. */
+    readonly collectCacheMaxEntries?: number;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        skills: SkillService;
+    }
+    interface Events {
+        /**
+         * A skill provider, runtime contribution, or provider-backed catalog may
+         * have changed. This is an unfiltered invalidation notification; consumers
+         * refetch the catalog for their own lookup options. Listener failures are
+         * contained and cannot veto the registry mutation.
+         * @mode emit
+         */
+        'skills/change'(): void;
+    }
+}
+/**
+ * Layered registry of skill providers, the host+per-scope shape the tools
+ * registry established. A registration files into the layer of its calling
+ * context's scope ({@link scopeOf}): host rows and repository plugins land in
+ * the global layer, while a plugin mounted by an agent preset's standing
+ * composition lands in that preset's layer. A read merges the global layer
+ * with the viewing scope's chain — the nearest layer's entry wins a duplicate
+ * name outright, and the rank order decides duplicates only within one layer.
+ * It exposes sorted invocation-neutral summaries and loads full skill bodies
+ * on demand.
+ */
+export declare class SkillService extends Service {
+    static Config: Schema<Config>;
+    private readonly collectCacheMaxEntries;
+    private readonly layers;
+    private readonly collectCache;
+    private revision;
+    private nextProviderOrder;
+    /** Stable identities for cache keys; scope keys are opaque identity-compared objects. */
+    private readonly scopeIds;
+    private nextScopeId;
+    constructor(ctx: Context, config?: Config);
+    /**
+     * Register a borrowed same-process provider synchronously during plugin
+     * apply, into the calling context's layer: a scoped context (an agent
+     * preset's standing mount) registers for that scope alone, an unscoped
+     * context registers globally. Duplicate names within one layer and reserved
+     * names throw; remote initialization belongs in `list()`. Fiber disposal
+     * unregisters the provider and invalidates catalog caches.
+     * @param create - synchronous factory receiving this registration's lifecycle and invalidation control.
+     * @returns the exact Cordis effect disposer that unregisters this provider;
+     *   composite effects may yield it directly to preserve teardown ordering.
+     */
+    registerProvider(create: (control: SkillProviderControl) => SkillProvider): () => void;
+    /**
+     * Register a borrowed readonly runtime skill into the calling context's
+     * layer. Project entries outrank runtime entries, which outrank user
+     * entries, within one layer. Same-name runtime entries in one layer are
+     * first-wins; a duplicate logs a warning and receives a no-op disposer so
+     * it cannot remove the winner.
+     * @param skill - the skill definition input; omitted invocation and provider fields receive defaults.
+     * @returns the exact Cordis effect disposer, preserving composite teardown order and invalidating caches.
+     */
+    register(skill: SkillRegistration): () => void;
+    /**
+     * List invocation-neutral skill summaries for a workspace. Consumers apply
+     * model or user invocation policy at their operational boundary. Lookup
+     * options and provider candidates are readonly same-process values borrowed
+     * throughout discovery.
+     * @param options - view options; `scope` selects the viewing agent's layers, `cwd` selects project roots, and `signal` cancels discovery.
+     * @returns all sorted winning summaries.
+     */
+    list(options?: SkillViewOptions): Promise<SkillSummary[]>;
+    /**
+     * Observe the current invocation-neutral catalog and whether discovery completed within a stable revision.
+     * Incomplete observations are never cached, allowing consumers to retain last-good state and
+     * retry on their next request boundary.
+     * @param options - view options; `scope` selects the viewing agent's layers, `cwd` selects project roots, and `signal` cancels discovery.
+     * @returns sorted summaries plus discovery-completeness state.
+     */
+    snapshot(options?: SkillViewOptions): Promise<SkillCatalogSnapshot>;
+    /**
+     * Load and validate the winning candidate, passing its opaque discovery locator back to the
+     * provider. Cancellation is rechecked after selection, including cache hits, and raced against
+     * loading so an uncooperative provider cannot hang the caller.
+     * @param name - kebab-case skill name.
+     * @param options - view options; `scope` selects the viewing agent's layers,
+     *   `cwd` selects workspace-sensitive skills, and `signal` cancels work.
+     * @returns the full skill, including body content, or `undefined`.
+     */
+    get(name: string, options?: SkillViewOptions): Promise<SkillDefinition | undefined>;
+    private collect;
+    private collectFresh;
+    private collectLayer;
+    private listLayerCandidates;
+    private invalidateCache;
+    /** Invalidate after a stale definition load, only while the exact registration that produced the entry is still live. */
+    private invalidateEntry;
+    private scopeId;
+    private collectCacheKey;
+    /** Notify catalog observers without making their refresh work load-bearing. */
+    private notifyChange;
+}
+export default SkillService;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-skill`.
+ * @module @deepseek-ai/dsh-skill/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "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,49 @@
+{
+  "name": "@deepseek-ai/dsh-skill",
+  "description": "Agent skill provider registry 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/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-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/cordis": "^4.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/cordis": "^4.0.1-rc.1"
+  }
+}