dsh skill 不是插件：它是给模型的可加载 Markdown 指令集，由本地提供方按 rank 扫描六个根目录发现，用 dsh plugin add 装不进去。本文讲清六个根目录的优先级、SKILL.md 写法与两个调用开关。
本文转自 DSH Plugin Hub 插件市场
DeepSeek Harness 的 skill 和 plugin 不是一回事：skill 是给模型的可加载 Markdown 指令集，plugin 是用代码扩展 DSH 的包，dsh plugin add 装不了 skill——skill 靠本地提供方扫描目录发现。 这篇按「先分清区别 → 再放对目录 → 最后写对文件」的顺序讲完。
DeepSeek Harness 里 skill 和 plugin 的区别：指令集与代码扩展包
skill 是给模型的可加载指令集（Markdown），plugin 是代码扩展包；前者由本地提供方扫目录发现、经会话目录与 skill 工具按需加载，后者用加载器挂进 profile 的插件树（来源）。 三条判断标准：
- 看它是什么 — 一个
SKILL.md或 Markdown 说明就是 skill；一个带apply(ctx)的 npm / GitHub 包才是 plugin。预期：判断完就知道该走「放目录」还是「走安装命令」。 - skill 不走安装命令 — 把文件放进下文的六个根目录之一即可。预期：
dsh plugin add对 skill 无效；反过来，插件也不会因为放进 skill 目录就被加载。 - 看模型拿到什么 — 会话目录只带排序后的
name与description，正文、路径、来源、提供方都不进目录。预期：模型先读描述决定要不要加载，加载时才拿到正文；用户也可以用/name直接调用。
skill 补的是「教模型怎么做」，插件补的是「工具箱」（命令、记忆、界面）。要给 DSH 加这类能力，走插件的安装链路，见《DSH plugin 是什么》与 DSH Plugin Hub 的插件市场。
DeepSeek Harness skill 放在哪个目录：六个根目录与 rank 优先级
本地提供方按 rank 扫描六个根目录，rank 越小越优先：项目 .dsh/skills（100）→ 项目 .agents/skills（200）→ Config.customSkillDirs（300）→ <dshHome>/skills（400）→ <agentsHome>/skills（500）→ 随包目录（600）（来源）。
| 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 时使用该目录 |
落位时按这个顺序判断：
- 只给当前项目用 — 放到
<项目根>/.dsh/skills，rank 最小、优先级最高。预期：只有在这个项目里开会话才看得到它。 - 项目内多个 agent 工具共享 — 放到
<项目根>/.agents/skills。预期：同样是项目级，但排在.dsh/skills之后。 - 项目根怎么算 — 包含
.git的最近祖先目录就是项目根，找不到时用当前 cwd。预期：在仓库子目录里放 skill 不会被发现，因为它不在根的直属位置。 - 想放一个自己的目录 — 写进
Config.customSkillDirs（rank 300）。预期：项目级与用户级之间多一层自定义根，适合集中放团队共用的 skill。 - 全局给自己用 —
<dshHome>/skills或<agentsHome>/skills（rank 400 / 500）；dshHome默认取$DSH_HOME或~/.dsh，agentsHome默认取$DSH_AGENTS_HOME或~/.agents。预期：任何项目里都能看到这些 skill。 - 重名怎么裁 — 同一层内先比 rank，再比提供方顺序与本地顺序；跨层时更近的层直接胜出。预期：两个目录下同名 skill 不会被合并，只会有一个赢家。
DeepSeek Harness skill 怎么写：SKILL.md 与两个调用开关
一个 skill 要么是目录包 <name>/SKILL.md、要么是扁平文件 <name>.md，名称必须 kebab-case，description 是模型看到的唯一路由信息；两个调用开关 user-invocable 与 disable-model-invocation 省略时都默认为 true（来源）。 四步写完：
- 建文件 — 二选一：目录包
<name>/SKILL.md，或扁平文件<name>.md。预期：**/SKILL.md这种嵌套递归写法不被支持，文件必须落在根目录的直属位置。 - 起一个合规的名字 — 名称要匹配
^[a-z0-9]+(?:-[a-z0-9]+)*$，例如release-notes-writer。预期：不合规的名字不会被收录。 写 frontmatter —
name必填，description是模型唯一能看到的路由信息，可选whenToUse补充指引：--- name: release-notes-writer description: 需要把一段变更整理成发布说明时使用；输入是提交范围，输出是固定结构的发布信息。 --- 正文写清楚步骤、命令与验收标准——它只在模型加载这个 skill 时才被读。预期：描述上限由消费方的
catalogDescriptionMaxLength控制，默认 500。- 决定谁能调用 — 默认两个开关都是 true：模型可自动加载，用户可
/name调用。预期：把disable-model-invocation设为 true 后模型目录里不再出现它，只剩人工调用；两个都设为 false，就只有受信的ctx.skills.get()调用方拿得到。
改正文不用重启：注册表不缓存完整定义，每次加载都会重新读当前正文，所以只改正文不会触发目录变更消息。
DeepSeek Harness skill 的注意事项与局限
- 发现只在现有根目录的直属层：嵌套递归的
**/SKILL.md不受支持，用户 DSH 根目录还会跳过自己的.system子目录。 - 没有内置系统 skill：本地提供方不合成内置 skill，随包 skill 要靠配置的 bundled 根目录或专用提供方提供；随包徽章 skill 默认是禁用状态，启用它等于显式选择加入。
description决定生死：它是模型看到的唯一路由信息，写得含糊模型就不会加载，正文再详细也没用。- 调用策略会被二次校验：
skill工具在加载前后都按模型调用策略检查，两个开关都为 false 的 skill 不会出现在模型目录里。 - 重名不是合并：同一层内同名 skill 只保留一个赢家（rank → 提供方顺序 → 本地顺序），跨层由更近的层直接胜出。
skill 负责「教模型怎么做」，插件负责补齐工具链能力。插件相关开关、日志路径、镜像源这些配置都收敛在 DSH Plugin Hub（dsh-plugin.org）的设置页里，装插件也走它的插件市场，不必手改配置文件。
常见问题
DSH skill 和 plugin 有什么区别？skill 能用 dsh plugin add 安装吗？
DeepSeek Harness 的 skill 是给模型的可加载 Markdown 指令集，plugin 是代码扩展包（按 apply(ctx) 挂载），两者的发现机制完全不同。dsh plugin add 装的是插件、装不了 skill——skill 由本地提供方扫描目录发现，再通过会话目录与 skill 工具按需加载。
DeepSeek Harness 的 skill 放在哪个目录？项目目录和用户目录谁优先？
DeepSeek Harness 的本地 skill 按 rank 扫描六个根目录：项目 /.dsh/skills（100）→ /.agents/skills（200）→ Config.customSkillDirs（300）→ /skills（400）→ /skills（500）→ 配置的随包目录（600）。rank 越小越优先，同一个层里重名先比 rank、再比提供方顺序。
DeepSeek Harness 的项目根目录怎么算？skill 放进子目录里还能被发现吗？
DeepSeek Harness 把包含 .git 的最近祖先目录当作项目根，找不到时就用当前 cwd，所以项目 skill 要放在项目根的 .dsh/skills 或 .agents/skills 下。嵌套递归的 **/SKILL.md 不受支持——skill 必须正好落在根目录的直属位置，或者写成扁平的 .md。
DeepSeek Harness 的 SKILL.md 该怎么写？description 模型会看到吗？
DeepSeek Harness 的 SKILL.md 用 YAML frontmatter 写 name 和 description：name 必须是 kebab-case，description 是模型在会话目录里看到的唯一路由信息，正文和绝对路径都不会进目录。所以「什么时候该用它」要写进 description，模型才知道要不要加载。
DeepSeek Harness 的 skill 不想让模型自动调用、只想我用 /name 手动触发，怎么做？
DeepSeek Harness 用两个 frontmatter 开关控制调用：user-invocable 管人工侧、disable-model-invocation 管模型侧，省略时都默认为 true。把 disable-model-invocation 设为 true，模型目录里就不再出现它，但你仍然可以用 /name 手动调用；两个都设为 false，就只有受信的 ctx.skills.get() 调用方拿得到。
本文转自 DSH Plugin Hub 插件市场，版权归属 DSH Plugin Hub 插件市场。
分类：插件开发
原文地址：https://dsh-plugin.org/zh/tutorials/dsh-skills-install
来源：skill 子系统参考（官方文档）、skill 包组 README（官方仓库）、dshplugin/dsh-plugin-hub
