專案中的規範常常只適用一個倉庫，卻被放進全域目錄，結果其他專案也開始載入錯誤指令。
最快解法：專案專用 Skill 放項目級，個人通用 Skill 放使用者級；團隊共用則採用「項目級加只讀共享源」的雙層方案，不要長期共用可寫的全域 Skill。
這篇適合三類讀者：希望為單個倉庫加入專用開發流程的獨立開發者；需要在多個專案之間重用 Skills 的個人重度使用者；以及要統一 Skill 版本、控制變更責任的平台工程師。
先分清楚：Skill 是指令資產，不只是 Markdown 檔
DeepSeek Harness 目前把 Skill 視為可被 Agent 發現、列出並按需載入的指令資產。官方架構將 Skill 能力拆成 Provider Registry、本地檔案系統 Provider，以及面向模型的目錄與載入工具；完整內容通常由 SKILL.md 提供。你可以先查看官方 Skills 子系統說明，再決定目錄層級。
這個分類會直接影響維護方式：
- 版本耦合：建置、測試與部署規範若跟著程式碼版本變動，應與倉庫一起提交。
- 誤觸發成本：全域 Skill 可能在不相關的專案被模型看到，增加錯誤流程被採用的機會。
- 權限風險：Skill 內容可以影響 Agent 的工具使用與執行方向，不能把它當成普通說明文件隨意讓所有帳戶修改。
- 環境漂移：每台 Mac 的主目錄各自放一份副本，更新時間、內容版本與檔案權限很快會不一致。
- 路徑依賴：寫死內部工具、絕對路徑或某個倉庫名稱的 Skill，不適合放到多專案全域位置。
官方文件目前確認，本地 Provider 支援項目根、使用者根、共享 Agent 根與自訂目錄；專案根則由最近的 .git 位置判定，若找不到 Git 根目錄，才使用目前工作目錄。這表示「放在哪裡」同時決定了 Skill 的可見範圍與更新責任。(github.com)
單一專案與多專案使用者，應該怎樣分層？
單一專案：讓 Skill 跟著倉庫走
如果 Skill 只描述這個專案的建置流程、測試指令、資料夾規則、程式碼風格或發佈檢查，優先放在項目級目錄：
<projectRoot>/.dsh/skills/<skill-name>/SKILL.md
官方本地掃描優先序中，<projectRoot>/.dsh/skills 的排名高於 .agents/skills、自訂目錄及使用者目錄。相同名稱發生衝突時，項目級版本可以先勝出。(github.com)
這樣做的優點：
- Skill 與程式碼同一個 Git 變更集，容易審查。
- 新成員複製倉庫後，不需要依賴個人主目錄。
- CI、離線環境與臨時 Mac 比較容易重現。
- 可以隨分支回退，不必修改整台機器的全域狀態。
但不要把 API Token、SSH 私鑰、內部網域密碼或本機使用者路徑寫進 SKILL.md。Skill 可提交；憑據應放在環境變數、受控憑據系統或部署層。
多專案個人使用者：只把真正通用的能力放全域
使用者級通常位於：
$DSH_HOME/skills
如果沒有指定 DSH_HOME，官方配置目錄將預設使用 ~/.dsh；共享 Agent 根則預設使用 $DSH_AGENTS_HOME 或 ~/.agents。(github.com)
適合放全域的內容包括：
- 不依賴特定倉庫路徑的程式碼審查習慣。
- 通用的測試失敗分析流程。
- 多個專案都會使用的格式化或提交檢查原則。
- 不包含內部系統名稱、部署憑據與專案專屬命令的操作指南。
全域方案的代價也很具體。一次更新會影響所有專案；Skill 名稱或描述改變後，可能改變 Agent 的選擇結果；某個框架專用流程若誤放全域，會在另一個專案產生錯誤建議。因此，個人全域目錄應該是「低耦合、低權限、低變動」區域，而不是所有 Skills 的垃圾桶。
| 使用情境 | 建議位置 | 主要優點 | 主要代價 |
|---|---|---|---|
| 只服務一個倉庫 | .dsh/skills |
跟版本走，容易回退 | 其他專案不能直接使用 |
| 多個專案都適用 | $DSH_HOME/skills |
更新一次即可重用 | 版本漂移與誤觸發會擴散 |
| 團隊共用且需審批 | 只讀共享源 + 項目引用 | 有統一來源與回退點 | 需要建立同步流程 |
| 執行池或 CI | 鏡像、初始化或交付資產 | 重建後仍可恢復 | 需驗收發現與重啟行為 |
小型團隊為什麼更適合雙層方案？
團隊不應該要求每台 Mac 手工維護同一份全域 Skill。較穩定的做法是：
- 團隊通用 Skill 存放在版本化共享源。
- 由指定維護者審查
SKILL.md、附帶腳本與資源檔。 - 專案倉庫只引用、同步或鎖定已批准版本。
- 專案若需要特殊規則，放在自己的
.dsh/skills。 - 全域目錄保持只讀，或只允許平台帳戶更新。
官方文件說明，自訂目錄會排在專案根之後、使用者根之前；因此可以把受控共享源配置到 customSkillDirs，再由專案級 Skill 覆蓋真正的專案特例。(github.com)
團隊需要明確記錄三件事：
- 誰負責升級：是平台工程師、專案維護者，還是每位開發者自行決定。
- 如何回退：保留已批准版本的目錄或 Git Tag，不要只保留最新副本。
- 怎樣留下變更記錄：至少記下 Skill 名稱、版本、變更原因、驗證任務與批准者。
注意：如果共享源使用符號連結，驗收時不要只檢查連結本身。要同時檢查連結目標的擁有者、可寫權限、實際路徑是否跨越信任邊界，以及重啟後是否仍能被同一個執行帳戶讀取。
雲端或 CI 執行池，怎樣交付團隊 Skills？
遠端環境最常見的錯誤，是把 Skill 放在某位使用者的主目錄，卻沒有把該目錄納入鏡像、初始化腳本或持久化硬碟。當執行池重新建立，Agent 仍能啟動，但 Skill 目錄已經消失。
平台團隊應把 Skills 視為環境交付資產，而不是個人偏好設定。交付時至少要固定：
DSH_HOME的實際位置。customSkillDirs是否啟用。$DSH_AGENTS_HOME是否存在及由誰擁有。- Skill 目錄是否隨鏡像、啟動腳本或工作區同步。
- 重啟後是否仍能發現相同名稱與版本。
- 不同執行池是否意外共用可寫目錄。
官方配置支援 dshHome、agentsHome、customSkillDirs，亦提供 watch、輪詢模式、穩定等待時間、專案監聽上限與符號連結跟隨選項。這些設定不是裝飾；它們會決定新增或修改 Skill 後，現有工作階段何時看見變化。(github.com)
| 驗收項目 | 項目級 | 個人全域 | 遠端執行池 |
|---|---|---|---|
| 來源是否可版本化 | 倉庫提交 | 個人管理 | 鏡像或初始化資產 |
| 更新責任 | 專案維護者 | 個人 | 平台團隊 |
| 失效影響範圍 | 單一專案 | 多個專案 | 同一執行池或整個池群 |
| 重啟後恢復要求 | 重新複製倉庫 | 保留主目錄 | 必須重新交付並驗證 |
| 適合的權限 | 開發者可修改 | 個人可修改 | 執行帳戶只讀 |
| 建議回退方式 | Git Commit | 備份版本目錄 | 鎖定鏡像或資產版本 |
DeepSeek Harness 為什麼找不到新增的 Skill？
通常不是 SKILL.md 內容本身錯，而是發現範圍、根目錄或監聽狀態不符合預期。官方本地 Provider 支援兩種檔案形態：
<name>/SKILL.md
<name>.md
但不支援任意深度的遞迴 **/SKILL.md 發現。Skill 名稱亦需符合小寫 kebab-case 格式。(github.com)
你可以按以下順序排查：
- 先確認項目根：在含有
.git的專案內啟動，避免 Skill 放在另一個目錄。 - 檢查檔案形態：確認是
<name>/SKILL.md或<name>.md，不要多加未支援的巢狀層級。 - 檢查名稱：使用小寫英文字母、數字與連字號，避免空格、底線與大寫。
- 檢查根目錄設定：確認
DSH_HOME、DSH_AGENTS_HOME與customSkillDirs實際指向你交付的目錄。 - 檢查監聽設定：若新增目錄後沒有反映，確認
watch沒有被關閉；遠端檔案系統可測試 polling 模式。 - 重啟並重新驗證：先看目錄是否仍存在，再確認 Skill 是否出現在目錄清單，最後執行一次按需載入。
- 測試隔離：切換到另一個專案，確認專案專用 Skill 不會出現。
官方說明指出，檔案監聽會處理直接新增、移除與 Skill 入口變更；若監聽失敗，現有可讀候選仍可能保留，但觀察結果會被標記為不完整。這解釋了為什麼你有時能啟動 Agent，卻看不到剛新增的 Skill。(github.com)
第一個決策：按條件選擇 Skill 層級
使用下面的分支，不要先從路徑名稱出發：
- 若 Skill 只描述一個倉庫的建置、測試或部署規則，就選項目級。
- 若 Skill 不依賴專案路徑、內部工具與敏感資料，而且至少會被多個專案使用，就選使用者級。
- 若 Skill 由團隊共同維護，且需要版本審批與回退，就選只讀共享源加項目級引用。
- 若 Skill 會隨遠端執行池重建，就放入鏡像、初始化腳本或持久化交付資產，不要只放個人主目錄。
- 若不同專案的信任邊界不同，就不要讓它們長期共用可寫全域目錄。
- 若你必須使用符號連結，先驗證目標位置、所有者、權限、監聽與重啟恢復；任一項不清楚，就改用實體複製或只讀同步。
這套判斷也適用於「多個專案能不能共用同一個 DeepSeek Harness Skill」：可以，但前提是內容真正通用、來源受控、版本可追蹤，而且不會把一個專案的憑據、絕對路徑或高權限操作帶進其他專案。
第二個決策：完成一次完整驗收
建立一個不涉及正式憑據的測試 Skill，然後依次完成：
- 在項目級目錄建立
sample-skill/SKILL.md。 - 啟動 DeepSeek Harness，確認項目根判定正確。
- 在目錄清單中確認 Skill 名稱與描述出現。
- 執行一次模型按需載入，確認讀到的是完整內容而不是只有摘要。
- 修改
SKILL.md的描述或入口，觀察監聽是否觸發目錄更新。 - 修改正文但不改名稱，確認下一次載入讀取新內容。
- 重啟程序，確認目錄、來源與版本仍然一致。
- 切換到另一個測試專案，確認項目專用 Skill 不會污染其他工作區。
- 將同名 Skill 放入共享源，確認項目級版本是否按預期勝出。
- 移除項目級版本，確認回退到共享源或使用者級版本。
官方模型面向的目錄只會呈現 Skill 名稱與描述，正文由 skill 工具按需載入；因此「目錄中看得到」與「內容真的能載入」是兩個不同的驗收點。(github.com)
DeepSeek Harness 仍處於開發預覽階段，官方明確提醒可能出現相容性破壞變更。平台團隊不應只記錄「某台 Mac 現在能用」，還要把配置檔、Skill 版本、監聽設定與重啟後發現結果一併保存。(github.com)
如果你目前把 Skills 放在可寫的個人全域目錄，常見缺點是專案之間互相污染、版本變更無法審查，以及雲端 Mac 重建後缺少一致的恢復記錄。對需要短期測試、臨時執行池或跨地區交付的人來說，直接準備一台本機 Mac 往往又會增加環境安裝、權限整理與重建驗收成本。此時，租用 KVMNODE 的雲端 Mac，並在交付時把 Skills 目錄、版本、同步方式與重啟驗收一併納入，通常比單純把檔案複製到某個主目錄更容易控制。你可以先參考雲端 Mac 方案，再配合雲端 Mac 地區選擇確認執行池位置；若重點是交付後驗收，則應把目錄發現與恢復記錄列入遠端 Mac 環境規劃的簽收項目。