DSH plugin Skills:技能身份、候选摘要与浏览器会话目录到底怎么判定谁生效的规则
同名技能到底谁生效,答案不在文件名,而在“层”“rank”和“调用策略”三处。 DSH plugin 的 Skills 注册表采用宿主加作用域的分层结构:层的远近先决胜负,rank 只在同层内裁决。把这两步混在一起看,就会出现“明明放在项目目录里却被覆盖”的困惑。 DSH插件 装了技能却找不到,先看层,再看 rank,最后看调用策略。
注册表是宿主加作用域的分层
最近层的条目直接赢,紧接着才轮到 rank。(来源)
注册表采用宿主 + 按 scope 的分层结构,也就是工具注册表在 dsh-scope 之上确立的形态。注册会落入调用方上下文 scope 对应的层:
- 宿主行与 repository 插件 — 落入全局层;
- 由 agent preset 常驻组合挂载的插件 — 落入该 preset 的层。
提供方名称在每层内唯一,而不是进程级唯一。读取时把全局层与观察 scope 的链合并:最近层的条目直接赢得重名 skill,rank 顺序只在单层内裁决重名。
发现缓存以解析后的 scope 链为键,因此重设 scope 父级(空会话重组)无需注册表变更,下一次读取就能看到。
本地发现的六个 rank
rank 决定同层内谁优先,目录本身决定工作区归属。(来源)
| Rank | 来源 | 根目录 |
|---|---|---|
| 100 | project-dsh | <projectRoot>/.dsh/skills |
| 200 | project-agents | <projectRoot>/.agents/skills |
| 300 | custom | Config.customSkillDirs |
| 400 | user-dsh | <dshHome>/skills |
| 500 | user-agents | <agentsHome>/skills |
| 600 | bundled | 配置了 Config.bundledSkillDir 时使用 |
项目根目录是包含 .git 的最近祖先目录;找不到时使用当前 cwd。当 ctx.fs 可用时,git-root 向上查找通过文件系统服务探测 .git,使远程或沙箱工作区不会回退到宿主文件系统边界。
两条容易踩的细节:用户 DSH 根目录会跳过其 .system 子目录;本地提供方不会合成内置系统 skill,随包技能要靠已配置的 bundled 根目录或专用提供方。
失败根目录的行为也值得知道:它不提供候选项,所以在恢复之前,其他根中较低优先级的同名 skill 可能同时提供目录描述与加载的正文——也就是说“描述来自 A、正文来自 B”是可能出现的过渡状态。
身份规则与文件形态
名字必须是 kebab-case,嵌套递归发现不支持。(来源)
skill 名称匹配 ^[a-z0-9]+(?:-[a-z0-9]+)*$。本地提供方接受两种形态:目录包 <name>/SKILL.md,以及扁平 Markdown 文件 <name>.md。
嵌套递归的 **/SKILL.md 发现不受支持。所以把一个技能目录塞进两层子目录里,它不会自动被发现。
摘要是与调用策略无关的形状
list() 保留四种策略组合,过滤发生在消费方边界。(来源)
SkillSummary 包含:可选 path(提供方给出的绝对指令文件路径,虚拟技能时缺失)、name、description、可选 whenToUse、invocation、source、provider 与可选 resourceBase。
SkillInvocationPolicy 只有两个正向布尔值:modelInvocable 与 userInvocable。四种组合各有含义:
- 都为
true— 模型与用户都能调用; { modelInvocable: true, userInvocable: false }— 仅供模型;{ modelInvocable: false, userInvocable: true }— 仅供用户;- 都为
false— 只能由受信的ctx.skills.get()调用方获取。
本地提供方读取名称完全匹配的 kebab-case frontmatter 键 disable-model-invocation 与 user-invocable,省略的字段默认为 true,并为每个解析出的 skill 生成这个规范化策略。
候选项、完整定义与不完整快照
注册表只存 locator,正文永远现取。(来源)
SkillCandidate 是提供方到注册表的形状,在摘要之外多出三项:rank、不透明 locator 与可选 metadata。注册表只存储 locator,并在调用获胜提供方的 get() 时原样传回。
SkillDefinition 是 ctx.skills.get() 返回的完整解析结果,在摘要之外多出 content 与可选 metadata,供 skill 工具使用。resourceBase 告知工具如何为本地、URL 或提供方管理的 skill 渲染相对资源引导。
SkillCatalogSnapshot 用来区分“确定不存在”与“提供方瞬时失败或目录持续变化”:skills 是本次观测收集、排序且与调用策略无关的摘要;只有每个已注册提供方都在没有并发目录修订时完成发现,complete 才为 true。不完整快照不会被缓存,因此下次查询会重试。
SkillProviderObservation 则允许提供方公开仍可直接加载的候选项,同时报告该观测不具权威性。这比“全有或全无”更实用:目录不完整,但已发现的技能仍能用。
查找与加载:cwd 敏感、取消可竞争
get() 每次都重新读正文,且会重新校验名称匹配。(来源)
skill 查找对 cwd 敏感,因为提供方可能暴露工作区本地的 skill;可选的 signal 为调用方取消提供方的工作。注册表读取还通过 SkillViewOptions 携带观察 scope——消费方传入调用中的 agent,agent 本身就是自己的 scope key。注册表消费 scope 做层选择,提供方只从同一个借用选项对象里读取 SkillLookupOptions。
取消在目录选择前后(包括缓存命中时)都会检查,并与发现和完整定义加载竞争。如果找不到 git root,本地提供方会把所提供的 cwd 本身视为项目根目录。
最关键的缓存语义是:注册表不缓存完整定义。每次调用 get() 都会携所选候选项调用胜出提供方,因此本地提供方会重新读取当前正文。名称与该候选项不再匹配的定义会被拒绝,并使该提供方实例失效以便重新发现。
会话目录与浏览器目录不是一条路
一个走 pre-step 注入,一个走 Remote 读取,二者服务不同入口。(来源)
dsh-tool-skill 在存活会话中第一个观察到可用 skill 或发现不完整的 agent/pre-step 注入初始的持久 user-role <system-reminder>。目录只包含已排序的 skill name 与规范化、经 XML 转义的 description;不含正文、路径、来源、提供方或路由提示。catalogDescriptionMaxLength 默认 500,整数最小值 3。
后续每个模型步骤之前,消费方都会应用精确的工具可见性,并把条目与完整性同会话日志中最新一条可识别且仍可见的目录消息比较。观测变化时提供一条持久的替换目录;删除所有 skill 时追加显式的空替换;发现不完整时发布可用子集,并附带警告与可选的 incomplete: true 来源元数据。压缩隐藏了所有历史目录消息后,下一次观测会重新建立当前目录;完整的空视图在从未发布目录时不发送任何内容。
面向模型的 skill({ name }) 工具校验 kebab-case 名称,在与调用策略无关的目录中查找摘要,并在加载前通过 isModelInvocable 拒绝无权访问的 skill;随后根据调用方 agent 的 cwd 重新读取完整定义,并在返回内容前再次检查策略。结果包含 <skill_content name="...">、<skill_resources> 与 <skill_instructions>,resourceBase 仅按需解析显式引用的脚本、参考资料与资产。
浏览器侧是另一条路径:SkillListRequest 通过 sessionId 指定一个 Session,SkillListValue 返回允许用户调用的条目,含名称、描述、可选使用提示与模型调用可用性。SessionSkillCatalog 在不激活 Agent 的前提下读取 Session cwd 与记录的 preset:live Agent 可以提供其作用域 registry,冷 Session 则使用 preset 的 standing scope。
验证:同名技能放两个目录
验证要把层、rank 与调用策略分三步看,否则无法判断谁生效。(来源) 六步:
- 在项目
.dsh/skills与用户目录各放一个同名技能,断言项目那份的source是project-dsh。 - 把项目目录那条的 frontmatter 改成
user-invocable: false,断言模型工具仍能调用、用户目录列表不含它。 - 让某一层出现两个同名候选项且 rank 不同,断言同层内 rank 小者胜出。
- 在 preset 层注册一个同名技能,断言它压过全局层,而不是比较 rank。
- 调用
snapshot(),断言complete为真;再让一个提供方list()抛错,断言complete为假且结果不被缓存。 - 修改某个技能正文但不改名,再次
get(),断言拿到新正文且目录消息没有变化。
如果第 6 步拿到旧正文,通常是调用方自己缓存了 SkillDefinition;注册表本身每次都重读。
技能目录的配置方式见技能目录配置;启用与使用流程见技能使用。
一句话收束: 先层后 rank、名称必须 kebab-case、摘要留存四种策略组合、locator 不透明、正文不缓存、会话目录与会话日志同步而不是每条都重发。
常见问题
先看层再看 rank。DSH plugin 里最近层的条目直接赢得重名技能,rank 顺序只在单层内裁决重名,所以上层目录里 rank 更低的技能仍可能压过下层。
不会,DSH plugin 的注册表不缓存完整定义。DSH plugin 每次 get 都会带着选中的候选项调用胜出提供方,本地提供方因此会重新读取当前正文。
不能,DSH plugin 用两个独立字段控制两个入口。DSH plugin 里两个字段都为 false 时,只有受信的 ctx.skills.get 调用方能拿到它。
不会,DSH plugin 明确说未完成观测不会缓存。DSH plugin 让消费方保留上一份良好状态,并在下一个请求边界重试发现。
相关术语
- SkillInvocationPolicy
- SkillInvocationPolicy 把两个独立调用控制规范化为正向布尔值,即 modelInvocable 与 userInvocable。— packages/skill/skill/src/index.ts
- SkillSummary
- SkillSummary 是与调用策略无关的技能摘要,含名称、描述、可选路径、调用策略、来源与提供方。— packages/skill/skill/src/index.ts
- SkillCandidate
- SkillCandidate 是提供方交给注册表的目录项,在摘要之外多出 rank、不透明 locator 与可选 metadata。— packages/skill/skill/src/index.ts
- SkillCatalogSnapshot
- SkillCatalogSnapshot 是一次目录观测,含排序后的摘要与 complete 标记,只有全部提供方稳定完成时才为真。— packages/skill/skill/src/index.ts
来源
- DeepSeek Harness 官方参考 - 技能· deepseek-ai
- packages/skill/skill/src/index.ts· deepseek-ai