先不要从目录名称开始，而要从 Skill 的责任边界 开始。DeepSeek Harness 的 Skill Provider 会合并不同层级的候选目录，并按项目、用户、自定义和共享来源参与发现；官方实现还区分目录发现、目录快照和按需加载。可先核对 官方 Skills 子系统文档。

截至 2026 年 8 月 18 日，官方配置目录确认的本地文件系统来源包括项目根、用户根、共享 Agent 根和自定义目录。默认目录细节、客户端展示方式和监听实现会随开发预览版本变化，不能只看一篇旧教程。DeepSeek Harness 官方仓库也明确提示当前仍处于开发预览阶段，存在兼容性变化。(官方项目仓库)

关于 Provider 的字段、目录入口和可配置行为，应同时对照官方配置目录；如果当前版本的配置文件与工具源码存在差异，以你实际安装版本的实现和启动日志为准。

单项目开发者：让 Skill 跟着仓库走

如果 Skill 里写了项目目录、构建命令、测试框架、分支规则或发布前检查，它就不应该放在个人全局目录。

项目级存放有三个直接收益：

• ✅ 可复制：新成员拉取仓库后，能得到同一套开发约束。
• ✅ 可审查：Skill 内容可以进入代码评审、变更记录和回退流程。
• ✅ 可绑定版本：旧分支继续使用旧规则，不会被个人目录的新版本突然覆盖。

官方本地 Provider 的项目发现会以 Git 根目录作为项目边界；项目目录通常应围绕仓库根组织，而不是依赖当前终端所在的某个子目录。官方 Skills 文档对项目根解析、项目来源优先级和 SKILL.md 结构有明确说明。

建议的仓库结构可以是：

your-project/
├── .dsh/
│   └── skills/
│       └── release-check/
│           └── SKILL.md
├── src/
└── package.json

但不要把本地凭据、个人绝对路径、临时端口、私有证书或未经审查的脚本写进 Skill。SKILL.md 不是普通说明文档，它会影响 Agent 何时调用工具、执行哪些步骤以及如何处理失败。

多项目个人用户：全局只放真正通用的能力

你同时维护多个仓库时，全局目录确实更省维护。比如统一的代码审查格式、通用的变更说明模板、与具体项目无关的日志分析流程，都可以放在用户级目录或由 DSH_HOME 指向的用户 Skill 根。

但“能在两个项目使用”不等于“应该全局使用”。放入全局前，至少检查四件事：

1. 是否引用了固定仓库路径？
2. 是否默认某个项目一定使用某个构建工具？
3. 是否会调用只在一个项目存在的内部命令？
4. 是否包含一个项目的凭据、域名、数据库表名或部署权限？

只要有一项回答为“是”，就回退到项目级。

全局方案的优势是更新集中。缺点也很具体：一次修改会扩散到所有项目；旧项目可能突然遵循新规则；同名 Skill 可能出现覆盖；你排查问题时还要判断到底是项目目录还是用户目录提供了最终版本。官方实现会把不同 Provider 的候选合并到注册表，并按层级、优先级和同名规则决定最终候选，因此“文件存在”不代表它就是当前会话使用的那一份。

⚠️ 经验：如果一个全局 Skill 需要在正文里写“进入某某仓库后执行”，它通常已经不是全局 Skill，而是项目流程的伪装。

Skills 的隐性成本不在复制文件，而在变更责任。

项目级 Skill 的责任人通常很清楚：仓库维护者负责内容，评审者负责风险，分支版本负责回退。全局 Skill 则容易变成“某台 Mac 上有人改过，但没人知道什么时候改的”。当多个项目共用一个可写目录时，问题会进一步扩大：

• 更新责任模糊：谁批准了新命令？谁验证了旧项目？
• 故障定位变慢：同一个任务在不同项目中表现不同，可能只是目录优先级不同。
• 版本漂移：开发机、云端 Mac、CI 执行池各自保留不同副本。
• 权限扩大：一个 Skill 既能读取普通项目，也能接触敏感仓库。
• 监听不一致：文件已经修改，但当前会话仍使用旧目录快照。

官方 Skills 设计区分“发现摘要”和“完整内容加载”。目录列表可以先进入会话，完整 Skill 内容则在调用时重新读取；因此你既要验证候选是否出现，也要验证按需加载时拿到的内容是否正确。相关发现和加载规则可参考 官方 Skills 工具说明。

小型团队：采用项目级加只读共享源

小型团队最实用的不是“所有人共享一个全局目录”，而是双层方案：

• 共享源：维护团队通用 Skill，使用版本控制，默认只读。
• 项目目录：保存项目实际批准的版本，或保存指向已批准版本的引用。
• 项目负责人：决定当前仓库何时升级。
• 平台负责人：维护共享源、发布记录和回退版本。

例如，团队可以维护：

team-skills/
├── coding-review/
│   └── SKILL.md
├── ci-diagnosis/
│   └── SKILL.md
└── versions/
    ├── approved-2026-08/
    └── approved-2026-07/

项目接入时，不要直接跟随共享源的最新内容。应记录批准版本、同步提交和验证结果。这样升级失败时，你能在不改动其他仓库的情况下回退。

多个项目当然可以共用同一个 Skill，但共用的应该是版本化内容，不是一个所有项目都能写入的目录。共享 Skill 还必须经过最小权限审查，特别是包含脚本、文件操作和网络访问时。

远程环境不能依赖某个用户的主目录。个人主目录可能在重建、换账户、重启或更换执行池后消失。官方 Web UI 文档说明，DeepSeek Harness 需要先选择工作区，进程启动目录和实际工作区并不是同一个概念；这也是为什么远程交付时要把 Skill 目录和工作区一起验收。(官方 Web UI 使用指南)

平台团队建议按以下边界交付：

• 镜像层：放平台批准、所有项目都允许读取的基础 Skill。
• 初始化层：根据项目版本同步项目专用 Skill。
• 执行层：以只读方式挂载共享目录，避免 Agent 在运行中改写源文件。
• 会话层：启动后重新验证目录发现、Skill 摘要和按需加载。
• 恢复层：重启后重复验证，不能只检查文件是否还在。

这里有三个常见误区。

第一，文件同步成功，不等于 Skill 已经被发现。目录监听、目录快照和当前会话状态可能不同。第二，能列出 Skill，不等于完整内容加载成功；SKILL.md 的名称、描述和元数据仍要通过解析。第三，符号链接能减少重复副本，但也可能穿过项目边界，把一个低信任项目连接到高信任共享目录。

官方源码说明，本地 Provider 支持项目目录、用户目录、自定义目录以及可配置的共享或打包目录；同时还提供文件变化失效机制。监听行为、缺失目录处理和目录快照状态应按当前版本复核，不要把其他 Agent 工具的默认值直接套到 DeepSeek Harness。

平台团队按执行池固定 Skill 清单

如果你有多个远程执行池，建议为每个池建立清单：

skill-name: ci-diagnosis
source: team-skills
approved-version: 2026-08
writable: false
workspace-scope: project
restart-check: required

每次交付至少做 7 步：

1. 记录 Skill 来源、版本和提交标识。
2. 将共享 Skill 复制或挂载到约定目录。
3. 检查目录所有者、权限和符号链接目标。
4. 启动 DeepSeek Harness，选择正确工作区。
5. 列出 Skill，执行一次按需加载任务。
6. 修改或替换 Skill 后，验证监听或重新触发发现。
7. 重启执行池，再验证发现结果和项目隔离。

第 5 步和第 7 步不能省。很多“找不到新增 Skill”的问题，不是目录写错，而是会话仍保留旧目录视图，或者重启后初始化脚本没有重新交付。

先按下面的分支判断，不要直接反复重写 SKILL.md。

• 若只服务一个仓库，放入项目级目录；否则回退到用户级。
• 若不依赖仓库路径且多个项目都需要，放入用户级或只读共享源；否则回退到项目级。
• 若团队需要统一版本，共享源必须版本化；否则回退到项目目录复制。
• 若远程环境会重启或更换账户，纳入镜像、初始化或交付资产；否则不要依赖个人主目录。
• 若项目之间存在不同信任边界，禁止共用可写全局目录；否则回退到隔离目录。
• 若需要快速回滚，项目目录保留批准版本；否则不要直接追踪共享源最新内容。
• 若新增后当前会话不可见，重新触发目录发现或重启会话；不要仅确认文件时间戳。

官方本地发现优先级包括项目级来源、用户级来源、自定义来源和可选的打包来源。项目根通常由最近的 Git 根确定；没有 Git 根时，当前工作目录可能成为项目边界。Skill 目录支持目录式包和扁平 Markdown 文件，但不应假定任意深层嵌套都会被递归发现。

安全团队应把 Skill 当作会改变 Agent 行为的指令资产，而不是普通文档。

建议执行以下检查：

• 来源是否来自已审核的仓库或内部发布源？
• SKILL.md 是否包含隐藏的网络访问、删除文件或上传内容指令？
• 文件所有者是否为发布账户，而不是运行时账户？
• 运行时账户是否只有读取权限？
• 符号链接是否指向允许的目录？
• 同名 Skill 出现时，最终采用哪个层级？
• Skill 是否能在低权限项目中读取高权限路径？

符号链接并非天然不安全。它适合减少重复副本，但必须锁定目标、所有者和权限。跨信任边界时，优先使用经过批准的复制或只读挂载；如果必须使用符号链接，就在启动验收中解析真实路径，并记录目标变化。

DeepSeek Harness 的架构把 Skill Provider、目录加载器和面向模型的工具拆分开来，说明 Skill 本身已经是运行时能力链的一部分。安全审核不能只看文件扩展名，还要检查它会触发哪些工具、读取哪些目录以及是否能改变项目文件。

最终配置结论

你可以直接采用这套规则：

• 独立开发者、单项目：项目级。
• 个人、多项目、低敏感度：通用能力用户级，项目规则项目级。
• 小型团队：只读共享源加项目级批准版本。
• 平台团队：按执行池固定清单，纳入镜像、初始化或交付资产。
• 安全敏感团队：限制可写全局目录，谨慎使用符号链接，严格验证来源和权限。

不要让多个信任边界不同的项目长期共用一个可写全局 Skill。最稳妥的双层配置是：共享源负责统一，项目目录负责落地和回退。

如果你已经决定采用双层方案，下一步应把 Skill 目录、版本、账户权限和重启恢复记录一起纳入环境签收，而不是只验收 Mac 是否能启动。你可以继续查看 云端 Mac 交付验收方法，再根据项目的持续运行时间和并发需求选择 KVMNODE 的云端 Mac 方案。相比临时在个人 Mac 上手工复制，全局副本容易漂移，远程重建后也可能丢失；把 Skills 作为固定交付资产，通常更适合需要可回退、可复现和多人协作的 DeepSeek Harness 环境。