thatgfsj-dsh/dsh-plugin-skills / 0.2.1-rc.2/dsh-skill-authoring
dsh-skill-authoring
Verified在 DeepSeek Harness 中编写、组织、验证与排障 agent 技能(SKILL.md)。覆盖发现根目录与优先级、frontmatter 字段与校验规则、bundle 资源目录、模型/用户调用策略、目录描述长度上限,以及"写完为什么没被加载"的排查方法。当需要新建或修改 `~/.dsh/skills`、项目 `.dsh/skills`、`.agents/skills` 下的技能,或把某套流程/知识固化成可复用技能时使用。
编写 DSH 技能(SKILL.md)
事实来源:本机 0.2.1-rc.2 的 @deepseek-ai/dsh-skill、dsh-skill-filesystem、dsh-tool-skill 的 lib/index.js,以及官方 tag dsh-v0.2.1-rc.2 的 packages/skill/** 与 docs/subsystems/skills.md。技能的发现与格式在 0.2.0 → 0.2.1 之间没有变化(rank、正则、字段集、500 截断都逐字节一致),只有调用键名和 rank 600 的用法有更新,见下。
技能放哪里(发现是一层深,不递归)
| Rank | 来源 | 路径 |
|---|---|---|
| 100 | project-dsh | <projectRoot>/.dsh/skills |
| 200 | project-agents | <projectRoot>/.agents/skills |
| 300 | custom | 配置的 customSkillDirs |
| 400 | user-dsh | <dshHome>/skills(默认 ~/.dsh/skills,跳过 .system 子目录) |
| 500 | user-agents | <agentsHome>/skills(默认 ~/.agents/skills) |
| 600 | bundled | $DSH_BUNDLED_SKILL_DIR / 配置的 bundledSkillDir |
projectRoot= 最近的含.git的祖先目录;没有就用当前 cwd。- 只识别
<root>/<name>/SKILL.md和<root>/<name>.md两种形态。<root>/a/b/SKILL.md这种嵌套不会被发现,不要按"技能集合目录"来组织。 - 反过来要注意:扁平形态下,根目录里任何
*.md都是候选。把customSkillDirs指向一个仓库根,README.md也会被当成技能读一遍,然后因为缺 frontmatter 被丢弃并在日志里告警。 - 重名时:离得近的层赢;同一层里按 rank、提供方注册顺序、提供方内部顺序裁决。被遮蔽的定义没有 API 可查。
frontmatter(YAML,必须两个字段)
---
name: my-skill-name
description: 做什么 + 什么时候用(关键词要写全,模型只先看到这一行)
whenToUse: 可选的补充触发说明
# disable-model-invocation: true # 从模型目录与 loader 中排除
# user-invocable: false # 从面向用户的命令中排除
# metadata: {...} # 可选附加信息
---
正文……
已核实的校验规则:
name必须匹配/^[a-z0-9]+(?:-[a-z0-9]+)*$/(kebab-case,无大写、无下划线、无连续短横)。目录名与name保持一致最省事。name或description缺失、YAML frontmatter 畸形、名字非法、调用布尔值非法 → 整个技能被丢弃,只在日志里留一条skill file <path> ignored: ...警告。模型目录不会告诉你有东西坏了,也不会区分"不存在"和"写错了"。- 调用布尔值接受 YAML 布尔与大小写不敏感的
true/false、yes/no、on/off、1/0;拼错会整条丢弃,而不是静默按默认放行。 - 旧的驼峰键会被显式拒绝并整条丢弃:
disableModelInvocation/modelInvocable/userInvocable每个都会抛frontmatter field "<旧键>" is unsupported; use "<新键>"。从老文档抄配置时,这是最常见的"技能消失"原因。 disable-model-invocation: true与user-invocable: false是两个独立开关,默认都允许,四种组合:
| 组合 | 模型目录 / skill 工具 | 用户入口 |
|---|---|---|
| 省略两键(默认) | 包含 | 包含 |
disable-model-invocation: true | 排除 | 包含 |
user-invocable: false | 包含 | 排除 |
| 两者都设 | 排除 | 排除(只剩可信的 ctx.skills.get() 调用方看得见) |
"用户入口"指浏览器里的技能目录(按 userInvocable 过滤)和用户消息里的 /<name> 手势。两者与模型侧互不影响。
- 正文 = frontmatter 之后的全部内容(会
trim)。发现阶段会读取整份文件,但只保留 frontmatter 字段,正文被丢弃、不进入目录缓存;每次加载都重读当前文件,所以改正文不需要版本号或缓存失效。
目录描述会被截断
dsh-tool-skill 的 catalogDescriptionMaxLength 默认 500 字符,按空白归一化后的长度判断,超出部分截断(保留前 497 字符 + ...),不是丢弃技能。模型的初始技能目录只渲染 name + 截断后的 description,所以:
- 把"做什么 / 什么时候用"写在 description 的前半段,别把它当摘要写作。
- 触发词(同义词、用户可能用的中英文说法)要进去,否则模型不会来加载你。
技能里的资源
- 技能的 resource base 就是
SKILL.md所在目录。references/、scripts/、assets/是约定俗成的子目录,加载技能时会把 resource base 指给模型。 - 模型目录只由
name+ 空白归一化并截断后的description(以及disable-model-invocation造成的过滤)决定:只有改这几项才会改变模型看到的目录内容。纯正文、whenToUse、metadata、user-invocable的改动都不刷新目录,只影响下一次加载;references/等资源目录的改动同样不进目录。 - 因为 digest 用的是截断后的 description,改动落在 500 字符窗口之外时,模型目录不会刷新(但下一次加载会读到新正文/新 frontmatter)——把重要信息写在前面,也让改动更容易被模型感知。
- 发现是"目录 + 正文"分离的:目录缓存有上限(注册表
collectCacheMaxEntries默认 128),正文从不缓存。
写完之后怎么验证
- 看会话目录:新建一个会话(或让宿主刷新)后,技能应出现在可用技能列表里。实测:把技能写进
~/.dsh/skills/后,当前会话的技能目录立刻出现了它(watcher 生效)。 - 没出现就查日志:
skill file <path> ignored: ...会点名原因(缺字段 / 名字非法 / frontmatter 非法 / 调用布尔值非法)。 - 路径自检:确认是
<root>/<name>/SKILL.md或<root>/<name>.md,且<root>是上表里的某一层;~/.dsh/skills/.system/下的东西会被跳过。 - 有
skill工具时直接按名字加载一次,正文能返回即为可用。两种 API 的失败形态不同:skill工具对「名字非法 / 未知或已下线 / 不可被模型调用」三种情况都抛错;而注册表 APIctx.skills.get(name)对非法名字返回undefined、不报错。
内容写法
- 技能是可复用的工作流与判据,不是知识库倾倒。把"什么时候用哪一步、判断标准是什么、失败怎么查"写清楚;事实细节用相对路径指到资源文件或权威来源。
- 采用渐进式披露:
SKILL.md保持能一眼扫完的骨架 + 一张"需要什么读哪个文件"的表,细节放references/*.md。 - 硬结论标注来源与核实方式;外部资料(官方文档、第三方技能、博客)可能对应不同版本,写清它适用于哪个版本,别把某版行为当成永恒事实。
- 不要复制别人的技能内容当自己的:先核实,再写,冲突处明确写分歧。
从插件里注册技能(可选路径)
插件可以在内存里注册技能,不需要落盘:
export const inject = ['skills']
export function apply(ctx) {
// register 只收一个参数;source 与 content 必填(正文不是第二个参数)
ctx.skills.register({
name: 'my-skill', description: '...', whenToUse: '...',
source: 'runtime', content: '正文……',
})
// registerProvider 收的是工厂 (control) => provider,不是 provider 对象
ctx.skills.registerProvider(() => provider)
}
- 运行时注册的提供方标签是保留值
runtime。同名冲突的处理不同:运行时技能register()同层同名先到先得并记警告;提供方registerProvider()重名直接抛错(a skill provider named "…" is already registered)。 - 发行版里两种挂载方式都在用:
@deepseek-ai/dsh-agent-preset把技能放在包内skills/目录,由 **customSkillDirs(rank 300)**挂载(见本机dsh-web-app/presets/cordis.patch.yml里skill-filesystem的配置)。- 打包装备(packaged provider)则用 rank 600:
dsh-skill-office(providerdsh-office,7 个技能)、dsh-skill-badge(providerdsh-badge,缺省不挂载,需要显式 insert)、dsh-sandbox-windows-acl的 ACL 技能。0.2.1 起 rank 600 就是官方打包 skill provider 的标准 rank。
- 第三方
dsh-plugin-guide也是"一个 bundle 附带一套 SKILL.md + 资料"的形态。这是把知识随插件分发的常用做法。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |