技能目录的触发规则存在结构性缺陷：常驻型技能永远不会被加载，whenToUse 字段对模型完全不可见

[raphael-y7]

摘要

DSH 的 skill（技能）系统存在两个相互关联的缺陷。第一，目录注入给模型的触发规则只覆盖「任务匹配」这一种情形，导致输出风格类、常驻类技能永远不会被加载——哪怕技能作者在描述里明确写了「每次会话开始时加载」。第二，whenToUse 字段被解析、被校验、被传给界面，但从不进入模型可见的任何输出，官方文档也承认了这一点。

第一个缺陷是设计缺口，第二个是已记录但未修复的功能空转。两者叠加的后果是：技能作者写在元数据里的意图，对模型而言等于不存在。

---

一、常驻型技能永远不会被加载

事实

会话开始时注入的目录消息，结尾指令原文如下（@deepseek-ai/dsh-tool-skill 的 renderCatalogMessage）：

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.

这条规则只有两个触发条件：用户点名，或任务明确匹配技能描述。

问题

这两个条件都预设了「技能绑定某个具体任务」。但有一类技能不绑定任何任务——它们约束的是输出形式本身。这类技能永远不「匹配」任何一次具体任务，因此永远不触发。

具体实例：本机安装的 i-have-adhd 技能，其描述含以下文字：

Active by default: load this skill at the start of every session,
before the first response, and follow it for all responses until the
reader says "stop adhd mode".

这段话是技能作者写给模型的直接指令。但它在实际使用中从未生效，必须由用户每轮手动点名。

已排除的其他原因

为免被归因于配置问题，以下均已核查：

可能原因	核查结果
描述被长度截断	否。该描述 348 字符，未超过 catalogDescriptionMaxLength 默认值 500
技能不可被模型调用	否。invocation 默认 modelInvocable: true、userInvocable: true
技能未被发现	否。目录中正常列出
frontmatter 写错	否。name、description 齐备，YAML 合法

真正的原因就是触发规则本身：没有「无条件加载」这一触发路径。

缺少机制

全库搜索，不存在任何常驻加载字段：

alwaysLoad      0 处
always-load     0 处
autoInvoke      0 处
forceLoad       0 处
eagerLoad       0 处
preloadSkill    0 处

@deepseek-ai/dsh-skill-filesystem 解析的 frontmatter 字段为：name、description、whenToUse、metadata、disable-model-invocation、user-invocable。其中没有任何一个能让技能常驻加载。

后果

目前唯一能让指令常驻生效的路径，是把内容写进 AGENTS.md（由 @deepseek-ai/dsh-agent-instructions 注入）。这意味着：技能系统无法表达「常驻」这一语义，用户被迫绕过技能系统，改用另一套机制。

对技能生态而言，这是能力缺口。任何希望提供「全局输出规范」「统一回复风格」「团队编码约定」的插件作者，都无法通过技能系统实现，只能引导用户手工编辑 AGENTS.md。而技能系统正是官方主推的扩展机制。

---

二、whenToUse 字段对模型完全不可见

事实

whenToUse 是一个被官方支持的 frontmatter 字段，语义是「何时使用本技能」。它被完整地解析、校验、并随技能摘要传递给界面层。

但面向模型的两处渲染，都没有使用它：

1. 目录条目只含两个字段（catalogSourceEntries）：

function catalogSourceEntries(skills, descriptionMaxLength) {
  return skills.map((skill) => ({
    name: skill.name,
    description: catalogDescription(skill.description, descriptionMaxLength)
  }));
}

渲染时也只输出这两项（renderCatalogEntries）：

return entries.map((entry) => `- \`${entry.name}\`: ${escapeText(entry.description)}`);

2. skill 工具返回给模型的内容不含 whenToUse：

return {
  name: skill.name,
  provider: skill.provider,
  ...skill.resourceBase !== void 0 ? { resourceBase: { ...skill.resourceBase } } : {},
  content: skill.content
};

3. 渲染给模型的 <skill_content> 包装层只含 name 与 content（renderSkillContent）。

计数佐证：whenToUse 在 @deepseek-ai/dsh-skill 中出现 14 次（校验与传递），在 @deepseek-ai/dsh-tool-skill 中出现 0 次——即负责面向模型渲染的那个包，从不读取该字段。

官方已承认

@deepseek-ai/dsh-tool-skill 的 README 在「已知限制与延期工作」中原文写道：

目录省略 whenToUse、来源和提供方元数据——路由只基于名称和有长度上限的描述；whenToUse 仍是提供方元数据，加载后的包装层也不渲染它。

也就是说，这不是未知问题，是已记录但未修复。

后果

这构成一个功能性矛盾：官方提供了一个字段让作者声明使用场景，又把它从模型的全部视野中删除。

• 技能作者认真填写 whenToUse，得到零收益——模型永远看不到它。
• 路由完全依赖 description。而 description 同时承担「给人看的简介」和「给模型看的路由依据」两种职责，当作者按常规写法把它写成简介时，路由准确率必然下降。
• 界面层拿到了 whenToUse（dsh-api-session-controller 传递该字段），但客户端 UI 也未使用（dsh-client-ui-skill 中 0 处引用）。该字段目前处于全链路空转状态：解析它、校验它、传递它，却没有任何消费者。

---

三、这两件事叠加起来是什么

单独看，第一条是缺一个字段，第二条是少一行渲染。叠加之后，问题的性质变了：

技能系统无法表达「无条件生效」，而唯一能表达「何时生效」的字段又不可见。

结果是技能作者与模型之间不存在可靠的意图传递通道：

1. 想表达「永远生效」——没有字段可用，只能放弃技能系统去改 AGENTS.md；
2. 想表达「这种情况才生效」——whenToUse 写了也白写，模型看不见。

对使用者而言，表现为技能时灵时不灵、需要人工点名；对生态而言，表现为技能作者无法可靠控制技能的生效时机。

---

四、请求

1. 为技能增加常驻加载能力。建议在 frontmatter 中增加字段（例如 always-load: true），使标记的技能在每次会话的首次请求前即注入正文，而非仅出现在目录中。这对输出风格类、全局规范类技能是必需的。

2. 让 whenToUse 真正到达模型。既然字段被官方支持并已通过校验，就应至少渲染进目录条目（例如以 - \name`: description | when to use: ...的形式），或进入<skill_content>` 包装层。若判定该字段确无用途，请在文档中明确说明并考虑移除，而不是维持「可填写但永不生效」的状态。

3. 修正目录注入的指令措辞。当前措辞只描述「用户点名」与「任务匹配」两种触发路径，未提及任何其他情形。建议明确说明：对于要求全程生效的技能，模型应如何处理——或明确说明当前不支持此类技能，以免作者产生错误预期。

4. 在文档中明确技能的生效语义。当前文档描述了目录与加载工具的行为，但未明确回答「技能能否常驻」这一作者最关心的问题。请补充说明。

---

五、复现方式

环境：DeepSeek Harness 0.2.0-rc.2（desktop profile），Windows 11。

1. 在 ~/.agents/skills/ 下放置一个技能，其 description 中写明「每次会话开始时加载本技能」（示例：i-have-adhd）。
2. 开启新会话，提出任意请求，观察模型是否自动调用 skill 工具加载该技能。
3. 实际结果：不会自动加载，需用户手动点名。
4. 对照检查：在 ~/.dsh/AGENTS.md 中写入同样的要求，则每轮自动生效——证明缺的是技能系统的常驻机制，而非提示内容本身。

---

说明：以上结论均基于对 app.asar 中 @deepseek-ai/dsh-skill、@deepseek-ai/dsh-skill-filesystem、@deepseek-ai/dsh-tool-skill、@deepseek-ai/dsh-client-ui-skill 及 @earendil-works/pi-ai 的源码核查，以及官方 README 的原文引用。未修改任何 DSH 安装文件。

[argszero]

Thanks for the thorough report — I verified both halves against d743267388 and they hold exactly as described:

• whenToUse never reaches the model: @deepseek-ai/dsh-tool-skill contains zero occurrences of the field, catalogSourceEntries() emits only {name, description}, and renderSkillContent() wraps only name + content.
• There is no resident-loading path: the catalog's closing instruction names only "the user names a skill" / "the task clearly matches a skill's description", so an output-style skill can never trigger.

One thing worth adding: both gaps are already reachable from a plugin today, without core changes — so the capability can ship before the core feature lands.

• agent/pre-step is a waterfall returning PreStepDecision.messages; appending a UserMessage is the supported injection path (@deepseek-ai/dsh-time-context does exactly this, and dedupes with a session projection).
• ctx.skills.snapshot({ cwd, signal, scope: agent }) returns SkillSummary[], and whenToUse is already carried on SkillSummary — parsed and surfaced, just never rendered on the model side. A plugin can append guidance listing whenToUse per skill.
• ctx.skills.get(name) returns SkillDefinition, which carries metadata, so a resident marker such as metadata: { resident: true } is expressible in frontmatter today (the filesystem provider preserves arbitrary metadata keys).
• Idempotency is the same shape time-context uses: a sessionProjections entry keyed on a digest of the skill set, republished only when the set changes.

I'm building that as a plugin (catalog whenToUse visibility + resident preload). The core requests in your post — an always-load frontmatter field, rendering whenToUse into the catalog, and the instruction wording — remain the right long-term fix; the plugin just makes the capability available in the meantime.

[raphael-y7]

感谢你独立核实了两部分——我逐条验证了你列出的钩子，你的判断是对的：agent/pre-step 瀑布、whenToUse 已经挂在 SkillSummary 上、metadata 不做键名白名单直接透传。

但有两点需要补充。

一、这个临时插件恰恰证明问题存在，而不是解决了问题

你说的技术在今天确实都可用。但这正是原始报告——以及另一份关于桌面客户端的报告（#9369）——所担心的事：一项基础能力的缺口，最终由社区插件补上，而不是由项目本身补上。这件事有四个具体影响：

• 安全边界。 插件运行在会话上下文内，能读取对话内容。要求用户为了获得基础行为而安装第三方代码，等于用数据安全换可用性。基础能力恰恰最不应该走这条路。
• 可持续性。 个人维护的插件会停止维护。宿主版本一变就失效。让基础行为依赖它，等于把一个本该项目自己承担的风险外部化。
• 可发现性。 新用户不知道插件存在，只会默默忍受缺口，甚至以为产品根本不支持这个能力。
• 一致性。 官方界面有统一的语言、主题和交互规范。插件守不住这条线，而且每次宿主升级都要重新适配。

二、临时插件替代不了核心修法

插件可以追加一条指引消息、可以预加载正文。但它做不到：

• 改不了目录的结尾指令——那段文字属于核心代码，而它恰恰是告诉模型何时加载技能的那句话；
• 没法让「常驻」成为一种其他提供方和消费方都会遵守的属性。

所以插件只是缩小了症状，设计缺口依然敞着。有用，但不等于解决。

我的请求：

1. 请让核心诉求保持开放：always-load frontmatter 字段、把 whenToUse 渲染进目录、修正指令措辞。不要因为有了临时插件，就把这些降级。
2. 有没有并入官方的路径？如果插件验证成功，这套机制会不会进入核心？这个问题需要一个明确答复，否则用户就被要求依赖一个没有任何承诺的东西。
3. 请看到这条的维护者回答：同样的模式也出现在 DSH 桌面端多项基础能力缺失，且被推给第三方插件实现——请作为标配纳入官方排期 #9369——提示音、会话 ID 可见性、技能/MCP 管理、归档会话删除，目前全都属于插件的地盘。请项目方明确表态：基础能力与插件的边界在哪里。「社区可以做」不是长期答案。

说明一点：以上不是对你工作的批评。核实报告并做一个临时修复，这件事本身很有价值，有总比没有好。我反对的是这个模式，不是你。

[raphael-y7]

再补充一点，这条可能比前两条更能说明问题的普遍程度。

DSH 几乎从不主动调用技能。

我观察到的情况是：技能目录虽然每轮都会注入，但模型基本不会自己去调用 skill 工具——除非用户明确点名，或者任务与描述的字面匹配度极高。两个很典型的例子：

• ponytail。它的描述里明确写着 Use on any coding task (writing, fixing, refactoring, reviewing, choosing dependencies)——按字面意思，任何写代码、改代码、重构、审查的场合都应该触发。它自己的 SKILL.md 里还写着 Active for the whole session until the user says "stop ponytail"，设计意图就是全程生效。但实际在编码会话中，它从未被自动调用过，必须手动点名。

• dsh-plugin-upgrade-skill。描述里写着「当用户要编写或修改 DSH 插件……先调用本入口」。也就是说，「开发 DSH 插件」这个场景是它唯一的存在理由。但即使在开发插件的会话中，它也没有被自动调用。

这两个例子合起来说明：问题不只是「常驻型技能没有触发路径」（我上一条报告的那个），而是整个自动调用机制在实践中基本不工作。

我认为原因是叠加的：

1. 目录结尾指令把触发条件限定为「用户点名」或「任务明确匹配描述」，措辞偏保守，模型倾向于不主动加载；
2. 目录里只有名称和描述，没有任何「何时使用」的强信号——这正是 whenToUse 缺失造成的直接后果；
3. 一旦模型选择不加载，就没有任何后续补救：没有重试、没有提示、没有兜底。

结果是：技能目录变成了一个「需要用户记住有哪些技能、再手动点名」的功能，而不是一个自动生效的扩展机制。对技能作者来说，等于他们精心写的触发条件基本不起作用。

我不确定这是否有意为之（例如出于 token 成本的考虑）。如果是有意的，希望文档能明确写清「技能默认不会被自动调用，请依赖用户显式点名」；如果不是，那这就是技能系统当前最该修的地方——优先级应排在 whenToUse 渲染之前。

[argszero]

Following the seam analysis above: both halves of this report are now available as a published plugin, so a deployment can close them today without patching a core package.

@argszero/dsh-skill-residency — https://www.npmjs.com/package/@argszero/dsh-skill-residency (repo: https://github.com/argszero/dsh-skill-residency, MIT, zero runtime dependencies)

npm install @argszero/dsh-skill-residency

- insert:
    - id: skill-residency
      name: '@argszero/dsh-skill-residency'

What it does, at agent/pre-step:

1. Publishes each author's whenToUse to the model. The catalog message and renderSkillContent never read the field (zero occurrences in @deepseek-ai/dsh-tool-skill), so the routing sentence an author writes is currently dropped. The plugin emits it as a durable, source-attributed user message.
2. Injects the body of every resident skill. Residency is declared either in config (resident: ['house-style']) or by the skill itself (metadata: { resident: true } in frontmatter — no core change needed, the filesystem provider preserves arbitrary metadata keys). The body is rendered through renderSkillContent, so it arrives in the <skill_content> envelope the catalog already teaches the model to follow.

Both messages are durable, so a resident skill survives compaction: the plugin re-publishes when the plan changes and after the message leaves the model-visible surface (agent.session.surface.nodes), which is the mechanism tool-skill uses for its own catalog — it keeps no state of its own.

It is deliberately inert: a deployment whose skills declare no whenToUse and keep no residents gets no message, no session event and no token spent. mode: report computes the plan and logs it instead of injecting, for anyone who wants to see what would be sent first. And it refuses nothing — with no working-directory service it still plans the global layer.

Two notes for whoever picks up the core side, since this is a workaround and not the fix:

• The whenToUse half is arguably a bug rather than a missing feature: the field is parsed, validated, documented and carried to the client, and only the model-facing renderer skips it.
• The resident half is a genuine gap — none of the parsed frontmatter fields (name, description, whenToUse, metadata, disable-model-invocation, user-invocable) means "always", and the catalog's trigger rule ("the user names a skill, or the task clearly matches a skill's description") presumes a task-bound skill, so an output style can never fire.

Verified against 0.1.7-rc.2, 0.2.0-rc.2 and 0.2.1-alpha.2 (31/31 arms on each; the suite drives a real Cordis context, the real skill registry, the real filesystem provider and real skill files through the dispatcher the agent loop itself uses).

[raphael-y7]

感谢你真的把它做出来了，而且我注意到你在最后两段里用的判断和我的报告是一致的——whenToUse 那一半「可以说是 bug 而非缺失功能」，常驻那一半「是真正的缺口」。这个区分很重要，说明我们对问题性质的理解没有分歧。

我也核对了你的发布：npm 上 @argszero/dsh-skill-residency v0.1.0，MIT，仓库同时间创建。你从核实报告到发布插件只用了大约一小时，这个效率值得尊重。

但正因为如此，我想把一件事说得更明确一些，因为它是这个帖子真正的重点。

你这个插件的存在本身，恰好演示了 #9369 里批评的那个模式。

这不是针对你。你在上一条里已经明确说了「这只是权宜之计，不是修复方案」，还主动写了两条给核心侧的说明——你的立场和我的报告是一致的。但客观结果是：一个今天创建、零星标、单人维护的包，现在成了这个缺口的「可用解决方案」。而缺口本身在核心侧依然敞着。

这正是问题所在。我在 #9369 里列过四条理由，放在这里同样成立：

• 安全边界。 你的插件要读取技能正文才能注入，这意味着它需要访问用户全部技能内容。功能上没问题，但用户为了获得一个「本应内建」的能力，必须把技能内容交给一个当天发布的个人包。基础能力不该要求这种取舍。
• 可持续性。 宿主版本一升级，插件就可能失效。你的测试覆盖了 0.1.7-rc.2、0.2.0-rc.2、0.2.1-alpha.2 三个版本，这很好——但这也恰恰说明维护负担真实存在。这个负担不该由基础能力来承担。
• 可发现性。 新用户不会知道有这个包。他们只会觉得技能系统就是不好用。
• 一致性。 官方目录、/ 菜单、技能卡片都有统一的交互形态，插件注入的消息绕过了这套形态。

所以我请求的是：不要让这个插件成为核心侧不作为的理由。

具体来说：

1. always-load 之类的 frontmatter 字段仍应进核心。metadata: { resident: true } 是一个可行的过渡约定，但它现在只是你一个插件的私有约定——其他提供方和消费方不会遵守它。只有核心定义了，它才成为一种语义。
2. whenToUse 的渲染仍应进核心。你把它作为 user 消息发出来是聪明的绕法，但这是绕过 renderSkillContent，不是修复它。
3. 目录结尾那句触发指令仍应修订。你绕开了它，但它对所有人（包括没有装你插件的人）依然是错的。

对看到这条的维护者：这个帖子的结局是社区成员自己写插件补上了缺口。如果这就是项目对基础能力的态度，希望明确说出来；如果不是，希望给出排期。目前 #9375 和 #9369 两条帖子都还没有官方回应。

最后，再说一次：以上不是对你工作的批评。你核实了报告、承认了问题性质、还把权宜之计和修复方案分得很清楚——这比很多官方回应都更负责。我反对的是这个模式，不是你。