DeepSeek Harness 自定义 Skill 教程：从 SKILL.md 到可复用 Agent 工作流

发布日期：2026-10-14

DeepSeek Harness（dsh）的自定义 Skill，是一份放在本地目录中的可复用任务指令：它用 YAML frontmatter 描述自己，再用 Markdown 正文规定 Agent 如何完成一类工作。DeepSeek Harness 官方文档把 Skill 设计成独立于模型和工具的指令层，支持项目级、用户级和自定义目录发现；因此你可以把团队规范、代码审查流程或发布说明模板做成一个可重复调用的工作流。

先理解 Skill 和插件的区别

Skill 解决的是“任务应该按什么步骤完成”，插件解决的是“运行时增加什么能力”。Skill 本身不需要写 TypeScript，也不负责注册工具；它在被加载后以指令正文进入当前 Agent 上下文，可以要求 Agent 使用已有的文件、Shell、搜索或 MCP 工具。

官方仓库当前把 Skill 分成发现、目录和加载三个阶段：文件先被扫描并解析 frontmatter，名称和描述进入会话目录；当任务匹配或用户显式调用时，Harness 再加载完整正文。这样做的好处是，日常请求只承担简短目录信息，真正的大段指令在需要时才进入上下文。

第一步：选择放置位置

最适合跟项目一起提交的路径是项目根目录下的 .dsh/skills。如果希望与其他 Agent 工具共享，也可以使用项目根目录的 .agents/skills。个人常用 Skill 可以放在 ~/.dsh/skills 或 ~/.agents/skills；团队还可以通过 customSkillDirs 指定额外目录。

官方默认发现顺序按 rank 排列：项目 .dsh/skills 为 100，项目 .agents/skills 为 200，自定义目录为 300，用户 ~/.dsh/skills 为 400，用户 ~/.agents/skills 为 500。出现同名 Skill 时，优先级更高的来源会胜出，所以项目级 Skill 可以覆盖用户级同名版本。

第二步：创建一个最小可用 Skill

下面以“生成发布说明”为例。在项目根目录执行：

mkdir -p .dsh/skills/release-note
touch .dsh/skills/release-note/SKILL.md

release-note 使用 kebab-case，目录名与 frontmatter 中的 name 保持一致。把以下内容写入 SKILL.md：

---
name: release-note
description: 根据 Git diff 生成面向用户的中文版本说明，包含变化、影响和升级提示
whenToUse: 当用户要求整理 changelog、版本说明或发布公告时使用
---

# 发布说明工作流

1. 先读取当前分支相对上一个版本的 Git diff。
2. 按“新增功能、修复问题、兼容性变化、升级动作”整理内容。
3. 删除内部实现细节、临时分支名和凭据。
4. 对不确定的影响标记“待维护者确认”，不要自行推断。
5. 输出一版 300 字以内的中文发布说明，并附一份变更文件清单。

官方格式要求 frontmatter 至少包含 name 和 description。whenToUse 是可选字段，适合补充触发条件，但会话目录主要展示名称和描述，因此描述应当能独立说明这个 Skill 解决什么问题。

第三步：让 Harness 发现它

使用官方 npm 入口启动 Web 端：

npx @deepseek-ai/dsh web

进入项目工作区后，先让 Agent 完成一次简单请求，例如“查看当前仓库有哪些可用 Skill”。如果文件格式正确，release-note 会出现在会话目录中。官方本地提供方会监视这些根目录，新增、改名或删除 Skill 通常会在下一次模型步骤刷新目录；只修改正文时，后续加载会读取最新内容。

如果目录没有出现，按这个顺序检查：当前工作目录是否位于包含 .git 的项目根下；文件是否正好是 .dsh/skills/release-note/SKILL.md；name 是否只包含小写字母、数字和连字符；frontmatter 是否同时写了 name 与 description。官方实现不递归扫描嵌套目录，因此 .dsh/skills/team/release-note/SKILL.md 不会被自动发现。

两种调用方式：自动匹配与显式调用

当用户任务与 Skill 的 description 匹配时，Agent 可以先调用 skill 工具加载完整正文。也可以在用户消息中显式输入 /release-note，让 Harness 把该 Skill 的指令直接注入当前步骤。显式调用适合你希望每次都执行固定流程的场景，例如：

/release-note
请根据本次提交生成 v0.3.0 发布说明，重点说明 API 兼容性变化。

如果 Skill 只想让用户手动调用、不想让模型自动加载，可以在 frontmatter 中加入：

disable-model-invocation: true

反过来，如果 Skill 只供模型使用、不出现在用户的 /name 命令中，可以设置：

user-invocable: false

这两个开关分别控制模型目录和用户命令目录，不能用来替代权限系统。涉及文件删除、命令执行或外部发布时，仍应依靠 Harness 的审批和沙箱策略。

把 Skill 写得稳定，关键是五件事

第一，先写输入和输出，再写步骤。比如明确“输入是 Git diff，输出是 300 字以内的中文说明”，Agent 更容易保持结果稳定。

第二，把必须执行的检查写成编号步骤，把可选建议放到最后，避免所有内容都被模型当成硬性约束。

第三，不要把长篇背景资料全部塞进 SKILL.md。官方加载结果会把正文作为工具历史保留，过长的 Skill 会持续占用后续上下文；可以把模板、示例和参考资料拆到同目录资源中，只在正文里说明相对路径。

第四，给危险动作加人工确认。例如“准备执行发布命令前，先展示命令和目标环境，等待用户确认”。Skill 是指令，不是安全边界，不能代替审批。

第五，用真实任务回归。至少准备一个成功样例、一个缺少输入的样例和一个需要拒绝的样例，确认 Skill 不会把猜测写成事实。

常见问题

为什么写了 Skill 却没有出现在目录里？

最常见原因是路径多嵌套了一层、frontmatter 缺少 description，或 name 含有大写字母和下划线。官方发现器只扫描每个根目录的直属条目，并会跳过格式错误的文件。

修改正文后为什么旧回答没有变化？

Skill 正文不是历史消息的版本替换。官方文档说明，后续加载会读取当前文件，但之前已经产生的工具结果不会被改写。因此修改后要重新发起一次调用，不能期待旧会话自动重算。

Skill 能不能直接增加一个新工具？

不能。Skill 可以指导 Agent 调用已有工具；要注册新的模型工具，需要按 DeepSeek Harness 的插件开发流程创建工具插件，再把调用方法写进 Skill。

截至 2026 年 10 月 14 日，DeepSeek Harness 的 Skill 机制已经覆盖项目、用户和自定义目录，并提供自动匹配与 /name 显式调用两条路径。真正值得投入时间的地方不是把 Skill 写得很长，而是把输入、步骤、输出和确认点写得足够明确，让同一套工作流在不同仓库里仍能稳定复用。