架構(gòu))
CLAUDE.md 治理指南解析 mattpocock/skills 的 Agent Skill 倉庫組織與分發(fā)架構(gòu)【免費(fèi)下載鏈接】skillsSkills for Real Engineers. Straight from my .agents directory.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/skills13/skills導(dǎo)讀CLAUDE.md是skills13/skills即 Matt Pocock 開源的 Skills for Real Engineers 技能倉庫中寫給 Agent 的倉庫憲法它定義了skills/目錄的 bucket 分層、promoted 技能的注冊(cè)規(guī)則、Claude Code 插件與 skills.sh 的雙通道分發(fā)方式、docs 鏡像頁面、技能調(diào)用模型以及全倉庫統(tǒng)一的寫作規(guī)范。本文以該文件為主體結(jié)合倉庫內(nèi)的安裝腳本、插件清單、ADR 決策記錄與調(diào)用約定文檔逐條還原這套治理規(guī)則的實(shí)現(xiàn)細(xì)節(jié)幫助你理解如何組織、維護(hù)并分發(fā)一套可被 Claude Code、Codex 等 Agent 調(diào)用的技能集合。讀完后你將掌握該倉庫從目錄設(shè)計(jì)到發(fā)布驗(yàn)證的完整閉環(huán)。一、這份 CLAUDE.md 是什么CLAUDE.md與倉庫根目錄的 AGENTS.md 內(nèi)容完全一致AGENTS.md 是指向 CLAUDE.md 的符號(hào)鏈接是一份面向 Claude Code 的維護(hù)者/貢獻(xiàn)者指南。它不講解某個(gè)具體技能怎么用而是規(guī)定了技能如何分桶存放哪些技能被推廣promoted并隨插件發(fā)布每個(gè)技能的元數(shù)據(jù)必須出現(xiàn)在哪些清單中文檔頁面與源碼目錄如何鏡像同步技能調(diào)用模型用戶觸發(fā)還是模型觸發(fā)如何聲明本地開發(fā)時(shí)如何把技能鏈接進(jìn)各 Agent 的工作目錄全倉庫 prose 的統(tǒng)一寫作約束。與 README.md面向最終用戶的安裝與使用說明不同CLAUDE.md 面向的是下一個(gè)接手這個(gè)倉庫的 Agent 或維護(hù)者其每條規(guī)則都有對(duì)應(yīng)的倉庫結(jié)構(gòu)、腳本或清單作為支撐。二、skills/ 目錄的 bucket 分層CLAUDE.md 首先定義了skills/下的五個(gè) bucket 文件夾Bucket定位是否 promotedengineering/日常代碼工作是productivity/日常非代碼工作流工具是misc/保留但很少使用不推廣否in-progress/測試版故意公開征求意見不隨插件發(fā)布否deprecated/不再使用否這條規(guī)則的執(zhí)行體現(xiàn)在兩處插件清單.claude-plugin/plugin.json 的skills數(shù)組精確列出 24 個(gè) promoted 技能全部來自engineering/與productivity/兩個(gè)目錄misc/、in-progress/、deprecated/下的技能一個(gè)都沒有出現(xiàn)在數(shù)組中。本地鏈接腳本scripts/link-skills.sh 用find $REPO/skills -name SKILL.md -not -path */node_modules/* -not -path */deprecated/*收集技能deprecated/被顯式排除。從源碼結(jié)構(gòu)看promoted 的定義是以插件發(fā)布集合為基準(zhǔn)的plugin.json 里有什么什么才算對(duì)外發(fā)布。三、雙注冊(cè)機(jī)制README.md 引用 plugin.json 數(shù)組CLAUDE.md 規(guī)定每個(gè) promoted 技能必須同時(shí)出現(xiàn)在兩處頂層 README.md技能名必須鏈接到其SKILL.md。查看 README.md 的 Reference 部分engineering與productivity兩組分別按 User-invoked 與 Model-invoked 分組列出每個(gè)技能名都指向skills/bucket/skill-name/SKILL.md。.claude-plugin/plugin.json 的 skills 數(shù)組Claude Code 插件只發(fā)布 promoted 集合。同時(shí)每個(gè) bucket 目錄內(nèi)還有一個(gè) README.md以一句話描述列出該 bucket 內(nèi)所有技能。規(guī)則還區(qū)分了兩種分組風(fēng)格promoted 桶engineering/、productivity/的 README 與頂層 README 一樣按User-invoked / Model-invoked分組非 promoted 桶misc/、in-progress/的 README 使用平鋪列表。關(guān)于插件清單的維護(hù)CLAUDE.md 給了明確的操作改動(dòng)任一 manifestplugin.json 或 marketplace.json后運(yùn)行claude plugin validate . --strict進(jìn)行嚴(yán)格校驗(yàn)。ADR 記錄見下節(jié)確認(rèn)這一校驗(yàn)已端到端通過。四、發(fā)行架構(gòu)官方 marketplace 插件 skills.sh 雙通道CLAUDE.md 指明安裝命令必須逐字拷貝自 .agents/install-block.md這是全倉庫唯一的安裝文案來源single source of truth。該文件定義了兩種互斥的安裝路線路線一Claude Code 官方插件訂閱式claude plugins install mattpocock-skills或會(huì)話內(nèi)執(zhí)行/plugin install mattpocock-skillsmattpocock-skills已收錄進(jìn) Claude Code 官方 marketplace配置名claude-plugins-official無需先添加 marketplace且官方市場的自動(dòng)更新默認(rèn)開啟因此更新自動(dòng)到達(dá)是真實(shí)承諾而非預(yù)期。這種方式安裝的是受管、只讀、隨發(fā)布更新的整體包。路線二skills.sh可編輯拷貝npx skillslatest add mattpocock/skills單技能形式npx skillslatest add mattpocock/skills --skillname npx skillslatest update name這種方式把技能作為普通文件寫進(jìn)你的項(xiàng)目歸你所有、可自由編輯想要更新時(shí)手動(dòng)執(zhí)行npx skills update。安裝器允許你選擇要安裝的技能因此 README 特別提醒務(wù)必把setup-matt-pocock-skills也選上它是每個(gè)倉庫只跑一次的一鍵配置技能。兩種路線被明確標(biāo)注為互斥插件是訂閱式只讀包skills.sh 是自持副本兩者都裝會(huì)讓每個(gè)技能出現(xiàn)兩份所以文案統(tǒng)一說二選一。底層決策記錄為什么是 Claude 插件而不是 Codex 插件倉庫在 .agents/adr/0002-ship-as-a-claude-code-plugin.md 用 ADR 記錄了發(fā)行架構(gòu)決策。核心約束是兩種生態(tài)的 manifest 對(duì)skills字段的選擇能力不同Claude Code 的plugin.json接受顯式路徑數(shù)組因此可以把 promoted 技能逐個(gè)列出、零歧義排除其余Codex 的plugin.json只接受單個(gè)路徑字符串且安裝時(shí)會(huì)丟棄符號(hào)鏈接導(dǎo)致指向./skills/會(huì)誤帶 deprecated 等桶和符號(hào)鏈接扁平目錄安裝后為空兩條退路都被否決。因此決策是現(xiàn)在發(fā)布 Claude Code 原生插件Codex 仍走 skills.sh等待 Codex 支持?jǐn)?shù)組/include-list 或保留符號(hào)鏈接后再評(píng)估。此外 ADR 還記錄了兩個(gè)不變式每個(gè) promoted 技能必須進(jìn)入plugin.json的 skills 數(shù)組plugin.json的version必須與 package.json 的版本同步遞增。值得注意的是.claude-plugin/marketplace.json讓本倉庫自身成為一個(gè)單插件 marketplace這是官方收錄之前的回退方案不作為文檔化的安裝路徑官方列表直接讀取plugin.json不依賴 marketplace.json。五、docs 鏡像頁面與四段式模板CLAUDE.md 規(guī)定engineering/與productivity/下的每個(gè)技能還必須在docs/bucket/skill-name.md擁有人類可讀的文檔頁docs 目錄樹與skills/下的兩個(gè) promoted 桶一一鏡像當(dāng)前倉庫中docs/engineering/有 18 個(gè)頁面、docs/productivity/有 7 個(gè)頁面與兩桶技能一一對(duì)應(yīng)。非 promoted 桶misc/、in-progress/、deprecated/沒有文檔頁。即使發(fā)布 URL 統(tǒng)一為https://aihero.dev/skills-skill-namedocs 路徑也僅是倉庫內(nèi)的組織方式。文檔模板與編寫指引位于 .agents/writing-docs.md一個(gè)完成的頁面必須攜帶四個(gè)小節(jié)What it does它做什么When to reach for it何時(shí)使用Common questions常見問題Its working if如何判斷生效觸發(fā)同步的條件是當(dāng)你在engineering/或productivity/中新增、重命名或改變某個(gè)技能行為時(shí)必須按 writing-docs.md 創(chuàng)建或重新同步其文檔頁。六、調(diào)用模型user-invoked 與 model-invoked每個(gè)SKILL.md要么是用戶觸發(fā)user-invoked要么是模型觸發(fā)model-invoked聲明的細(xì)節(jié)在 .agents/invocation.md 中User-invoked只有人類輸入其名稱才能觸發(fā)。聲明方式是在 SKILL.md frontmatter 中設(shè)disable-model-invocation: trueClaude Code并在agents/openai.yaml中設(shè)policy.allow_implicit_invocation: falseCodex。其description面向人類瀏覽斜杠命令需去掉Use when the user says…這類觸發(fā)器文案。Model-invoked模型或用戶都能觸發(fā)是默認(rèn)形態(tài)省略上述字段即可。其description面向模型保留豐富的觸發(fā)器措辭Use when the user wants…, mentions…以利于自動(dòng)調(diào)用生效。判斷是否保持 model-invoked 的測試是模型是否真的會(huì)自主地有用到這個(gè)技能兩類技能之間存在一條嚴(yán)格不變式用戶觸發(fā)技能絕不能被模型或其他技能調(diào)用包括通過 Skill tool 指名調(diào)用而用戶觸發(fā)技能可以調(diào)用模型觸發(fā)技能但永遠(yuǎn)無法觸達(dá)另一個(gè)用戶觸發(fā)技能。當(dāng)某步驟的前置條件是用戶觸發(fā)技能例如setup-matt-pocock-skills時(shí)文案必須寫成對(duì)人類下指令tell the user to run /setup-matt-pocock-skills而不是 Skill tool 調(diào)用。此外invocation.md 還給出了技能間依賴表達(dá)的約定對(duì)模型觸發(fā)技能使用顯式指令Call the Skill tool with grilling一次調(diào)用只帶一個(gè)技能名而非跨目錄文件鏈接或裸的/skill式提及跨技能共享的參考文檔歸擁有它的技能所有其他技能通過調(diào)用 Skill tool 獲取。七、ask-matt 路由器skills/engineering/ask-matt/SKILL.md 是一個(gè)特殊的用戶觸發(fā)技能它的職責(zé)是充當(dāng)路由器把每個(gè)用戶可觸達(dá)的技能及它們之間的關(guān)系映射出來。CLAUDE.md 特別強(qiáng)調(diào)每當(dāng)新增、重命名、移除或改變某個(gè)用戶可觸達(dá)技能在流程中的位置時(shí)必須重讀ask-matt的 SKILL.md 并更新它讓地圖保持準(zhǔn)確。一個(gè)它從未提及的新技能或一個(gè)它仍路由到的過時(shí)技能都是一個(gè)說謊的路由器。從 README 的描述看ask-matt的用途是詢問哪個(gè)技能或流程適合你的處境是所有用戶觸發(fā)技能的入口索引。它的同步觸發(fā)條件與 docs 頁面一致是倉庫維護(hù)流程中唯一一個(gè)需要行為同步的技能。八、本地鏈接腳本scripts/link-skills.shCLAUDE.md 說明要把每個(gè)技能重新鏈接進(jìn)本地各 Agent 的技能目錄運(yùn)行scripts/link-skills.sh腳本實(shí)現(xiàn)于 scripts/link-skills.sh要點(diǎn)如下目標(biāo)目錄為~/.claude/skillsClaude Code與~/.agents/skillsCodex 及其他兼容 Agent Skills 標(biāo)準(zhǔn)的 harness每條記錄都是指向本倉庫的符號(hào)鏈接因此git pull即可保持已安裝技能更新無需重新拷貝腳本開頭聲明這是僅限維護(hù)者的開發(fā)用腳本不是受支持的安裝器不接受改造請(qǐng)求它在倉庫內(nèi)find收集全部SKILL.md排除node_modules與deprecated/若目標(biāo)目錄本身是指向本倉庫的符號(hào)鏈接會(huì)檢測并拒絕執(zhí)行避免把每條符號(hào)鏈接寫回倉庫自身的skills/樹造成污染對(duì)已存在的普通文件目標(biāo)會(huì)先移除再重新ln -sfn建立鏈接。配套的 scripts/list-skills.sh 則簡單列出倉庫內(nèi)所有SKILL.md的排序路徑用于快速核對(duì)技能全集。九、寫作約束全倉庫禁用 em-dashCLAUDE.md 的最后一條規(guī)則看似風(fēng)格問題實(shí)則是一條可強(qiáng)制執(zhí)行的約束本倉庫所有 proseSKILL.md、docs、README.md、CHANGELOG.md、ADR、changesets、代碼注釋中不得出現(xiàn) em-dash—。當(dāng)句子需要它時(shí)改用逗號(hào)、冒號(hào)、句號(hào)、括號(hào)或連詞重寫絕不做盲目字符替換。這條規(guī)則的動(dòng)機(jī)是消除不同寫作風(fēng)格帶來的歧義同時(shí)它也出現(xiàn)在.changeset/中的變更記錄里如remove-em-dashes-repo-wide.md說明它確實(shí)是倉庫演進(jìn)過程中被嚴(yán)格執(zhí)行的規(guī)范而不是一句建議。從工程角度看這屬于用統(tǒng)一文體降低 Agent 解析成本的治理手段文檔作為 Agent 的上下文其標(biāo)點(diǎn)風(fēng)格一致性同樣影響理解質(zhì)量。十、維護(hù)工作流清單綜合 CLAUDE.md 與倉庫實(shí)現(xiàn)維護(hù)一個(gè)技能或整個(gè)倉庫的標(biāo)準(zhǔn)流程可以歸納為新增技能放入engineering/或productivity/promoted或在in-progress/中先行征求意見注冊(cè)在頂層 README.md 與其 bucket 的README.md中添加條目技能名鏈接到 SKILL.md并加入 .claude-plugin/plugin.json 的skills數(shù)組聲明調(diào)用模型按 .agents/invocation.md 配置SKILL.mdfrontmatter 與agents/openai.yaml兩類 harness 的聲明必須同步同步文檔頁按 .agents/writing-docs.md 在docs/bucket/skill-name.md創(chuàng)建或重寫四段式頁面更新路由器重讀 ask-matt 的 SKILL.md 并更新技能地圖校驗(yàn)插件清單改動(dòng) manifest 后運(yùn)行claude plugin validate . --strict并保持 plugin.json 的 version 與 package.json 同步本地重鏈接運(yùn)行scripts/link-skills.sh更新~/.claude/skills與~/.agents/skills下的符號(hào)鏈接檢查寫作規(guī)范確認(rèn)新 prose 中無 em-dash。總結(jié)CLAUDE.md用極短的篇幅把一個(gè)Agent 技能倉庫該有的工程紀(jì)律全部落地目錄分層決定發(fā)布邊界雙注冊(cè)機(jī)制保證 README 與插件清單不漂移install-block 單一來源統(tǒng)一了安裝文案ADR 記錄發(fā)行架構(gòu)的取舍invocation 約定劃清人機(jī)調(diào)用邊界ask-matt 路由器保持技能地圖不撒謊link-skills.sh 讓本地開發(fā)與 git pull 同步零成本。如果你正在維護(hù)自己的技能集合這份文件本身就是一份可復(fù)用的治理模板先定 bucket 與 promoted 邊界再定 manifest 校驗(yàn)與文檔同步流程最后用一條全倉庫文體約束收尾。【免費(fèi)下載鏈接】skillsSkills for Real Engineers. Straight from my .agents directory.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/skills13/skills創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 CLAUDE.md 治理指南：解析 mattpocock/skills 的 Agent Skill 倉庫組織與分發(fā)架構(gòu)
CLAUDE.md 治理指南解析 mattpocock/skills 的 Agent Skill 倉庫組織與分發(fā)架構(gòu)【免費(fèi)下載鏈接】skillsSkills for Real Engineers. Straight from my .agents directory.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/skills13/skills導(dǎo)讀CLAUDE.md是skills13/skills即 Matt Pocock 開源的 Skills for Real Engineers 技能倉庫中寫給 Agent 的倉庫憲法它定義了skills/目錄的 bucket 分層、promoted 技能的注冊(cè)規(guī)則、Claude Code 插件與 skills.sh 的雙通道分發(fā)方式、docs 鏡像頁面、技能調(diào)用模型以及全倉庫統(tǒng)一的寫作規(guī)范。本文以該文件為主體結(jié)合倉庫內(nèi)的安裝腳本、插件清單、ADR 決策記錄與調(diào)用約定文檔逐條還原這套治理規(guī)則的實(shí)現(xiàn)細(xì)節(jié)幫助你理解如何組織、維護(hù)并分發(fā)一套可被 Claude Code、Codex 等 Agent 調(diào)用的技能集合。讀完后你將掌握該倉庫從目錄設(shè)計(jì)到發(fā)布驗(yàn)證的完整閉環(huán)。一、這份 CLAUDE.md 是什么CLAUDE.md與倉庫根目錄的 AGENTS.md 內(nèi)容完全一致AGENTS.md 是指向 CLAUDE.md 的符號(hào)鏈接是一份面向 Claude Code 的維護(hù)者/貢獻(xiàn)者指南。它不講解某個(gè)具體技能怎么用而是規(guī)定了技能如何分桶存放哪些技能被推廣promoted并隨插件發(fā)布每個(gè)技能的元數(shù)據(jù)必須出現(xiàn)在哪些清單中文檔頁面與源碼目錄如何鏡像同步技能調(diào)用模型用戶觸發(fā)還是模型觸發(fā)如何聲明本地開發(fā)時(shí)如何把技能鏈接進(jìn)各 Agent 的工作目錄全倉庫 prose 的統(tǒng)一寫作約束。與 README.md面向最終用戶的安裝與使用說明不同CLAUDE.md 面向的是下一個(gè)接手這個(gè)倉庫的 Agent 或維護(hù)者其每條規(guī)則都有對(duì)應(yīng)的倉庫結(jié)構(gòu)、腳本或清單作為支撐。二、skills/ 目錄的 bucket 分層CLAUDE.md 首先定義了skills/下的五個(gè) bucket 文件夾Bucket定位是否 promotedengineering/日常代碼工作是productivity/日常非代碼工作流工具是misc/保留但很少使用不推廣否in-progress/測試版故意公開征求意見不隨插件發(fā)布否deprecated/不再使用否這條規(guī)則的執(zhí)行體現(xiàn)在兩處插件清單.claude-plugin/plugin.json 的skills數(shù)組精確列出 24 個(gè) promoted 技能全部來自engineering/與productivity/兩個(gè)目錄misc/、in-progress/、deprecated/下的技能一個(gè)都沒有出現(xiàn)在數(shù)組中。本地鏈接腳本scripts/link-skills.sh 用find $REPO/skills -name SKILL.md -not -path */node_modules/* -not -path */deprecated/*收集技能deprecated/被顯式排除。從源碼結(jié)構(gòu)看promoted 的定義是以插件發(fā)布集合為基準(zhǔn)的plugin.json 里有什么什么才算對(duì)外發(fā)布。三、雙注冊(cè)機(jī)制README.md 引用 plugin.json 數(shù)組CLAUDE.md 規(guī)定每個(gè) promoted 技能必須同時(shí)出現(xiàn)在兩處頂層 README.md技能名必須鏈接到其SKILL.md。查看 README.md 的 Reference 部分engineering與productivity兩組分別按 User-invoked 與 Model-invoked 分組列出每個(gè)技能名都指向skills/bucket/skill-name/SKILL.md。.claude-plugin/plugin.json 的 skills 數(shù)組Claude Code 插件只發(fā)布 promoted 集合。同時(shí)每個(gè) bucket 目錄內(nèi)還有一個(gè) README.md以一句話描述列出該 bucket 內(nèi)所有技能。規(guī)則還區(qū)分了兩種分組風(fēng)格promoted 桶engineering/、productivity/的 README 與頂層 README 一樣按User-invoked / Model-invoked分組非 promoted 桶misc/、in-progress/的 README 使用平鋪列表。關(guān)于插件清單的維護(hù)CLAUDE.md 給了明確的操作改動(dòng)任一 manifestplugin.json 或 marketplace.json后運(yùn)行claude plugin validate . --strict進(jìn)行嚴(yán)格校驗(yàn)。ADR 記錄見下節(jié)確認(rèn)這一校驗(yàn)已端到端通過。四、發(fā)行架構(gòu)官方 marketplace 插件 skills.sh 雙通道CLAUDE.md 指明安裝命令必須逐字拷貝自 .agents/install-block.md這是全倉庫唯一的安裝文案來源single source of truth。該文件定義了兩種互斥的安裝路線路線一Claude Code 官方插件訂閱式claude plugins install mattpocock-skills或會(huì)話內(nèi)執(zhí)行/plugin install mattpocock-skillsmattpocock-skills已收錄進(jìn) Claude Code 官方 marketplace配置名claude-plugins-official無需先添加 marketplace且官方市場的自動(dòng)更新默認(rèn)開啟因此更新自動(dòng)到達(dá)是真實(shí)承諾而非預(yù)期。這種方式安裝的是受管、只讀、隨發(fā)布更新的整體包。路線二skills.sh可編輯拷貝npx skillslatest add mattpocock/skills單技能形式npx skillslatest add mattpocock/skills --skillname npx skillslatest update name這種方式把技能作為普通文件寫進(jìn)你的項(xiàng)目歸你所有、可自由編輯想要更新時(shí)手動(dòng)執(zhí)行npx skills update。安裝器允許你選擇要安裝的技能因此 README 特別提醒務(wù)必把setup-matt-pocock-skills也選上它是每個(gè)倉庫只跑一次的一鍵配置技能。兩種路線被明確標(biāo)注為互斥插件是訂閱式只讀包skills.sh 是自持副本兩者都裝會(huì)讓每個(gè)技能出現(xiàn)兩份所以文案統(tǒng)一說二選一。底層決策記錄為什么是 Claude 插件而不是 Codex 插件倉庫在 .agents/adr/0002-ship-as-a-claude-code-plugin.md 用 ADR 記錄了發(fā)行架構(gòu)決策。核心約束是兩種生態(tài)的 manifest 對(duì)skills字段的選擇能力不同Claude Code 的plugin.json接受顯式路徑數(shù)組因此可以把 promoted 技能逐個(gè)列出、零歧義排除其余Codex 的plugin.json只接受單個(gè)路徑字符串且安裝時(shí)會(huì)丟棄符號(hào)鏈接導(dǎo)致指向./skills/會(huì)誤帶 deprecated 等桶和符號(hào)鏈接扁平目錄安裝后為空兩條退路都被否決。因此決策是現(xiàn)在發(fā)布 Claude Code 原生插件Codex 仍走 skills.sh等待 Codex 支持?jǐn)?shù)組/include-list 或保留符號(hào)鏈接后再評(píng)估。此外 ADR 還記錄了兩個(gè)不變式每個(gè) promoted 技能必須進(jìn)入plugin.json的 skills 數(shù)組plugin.json的version必須與 package.json 的版本同步遞增。值得注意的是.claude-plugin/marketplace.json讓本倉庫自身成為一個(gè)單插件 marketplace這是官方收錄之前的回退方案不作為文檔化的安裝路徑官方列表直接讀取plugin.json不依賴 marketplace.json。五、docs 鏡像頁面與四段式模板CLAUDE.md 規(guī)定engineering/與productivity/下的每個(gè)技能還必須在docs/bucket/skill-name.md擁有人類可讀的文檔頁docs 目錄樹與skills/下的兩個(gè) promoted 桶一一鏡像當(dāng)前倉庫中docs/engineering/有 18 個(gè)頁面、docs/productivity/有 7 個(gè)頁面與兩桶技能一一對(duì)應(yīng)。非 promoted 桶misc/、in-progress/、deprecated/沒有文檔頁。即使發(fā)布 URL 統(tǒng)一為https://aihero.dev/skills-skill-namedocs 路徑也僅是倉庫內(nèi)的組織方式。文檔模板與編寫指引位于 .agents/writing-docs.md一個(gè)完成的頁面必須攜帶四個(gè)小節(jié)What it does它做什么When to reach for it何時(shí)使用Common questions常見問題Its working if如何判斷生效觸發(fā)同步的條件是當(dāng)你在engineering/或productivity/中新增、重命名或改變某個(gè)技能行為時(shí)必須按 writing-docs.md 創(chuàng)建或重新同步其文檔頁。六、調(diào)用模型user-invoked 與 model-invoked每個(gè)SKILL.md要么是用戶觸發(fā)user-invoked要么是模型觸發(fā)model-invoked聲明的細(xì)節(jié)在 .agents/invocation.md 中User-invoked只有人類輸入其名稱才能觸發(fā)。聲明方式是在 SKILL.md frontmatter 中設(shè)disable-model-invocation: trueClaude Code并在agents/openai.yaml中設(shè)policy.allow_implicit_invocation: falseCodex。其description面向人類瀏覽斜杠命令需去掉Use when the user says…這類觸發(fā)器文案。Model-invoked模型或用戶都能觸發(fā)是默認(rèn)形態(tài)省略上述字段即可。其description面向模型保留豐富的觸發(fā)器措辭Use when the user wants…, mentions…以利于自動(dòng)調(diào)用生效。判斷是否保持 model-invoked 的測試是模型是否真的會(huì)自主地有用到這個(gè)技能兩類技能之間存在一條嚴(yán)格不變式用戶觸發(fā)技能絕不能被模型或其他技能調(diào)用包括通過 Skill tool 指名調(diào)用而用戶觸發(fā)技能可以調(diào)用模型觸發(fā)技能但永遠(yuǎn)無法觸達(dá)另一個(gè)用戶觸發(fā)技能。當(dāng)某步驟的前置條件是用戶觸發(fā)技能例如setup-matt-pocock-skills時(shí)文案必須寫成對(duì)人類下指令tell the user to run /setup-matt-pocock-skills而不是 Skill tool 調(diào)用。此外invocation.md 還給出了技能間依賴表達(dá)的約定對(duì)模型觸發(fā)技能使用顯式指令Call the Skill tool with grilling一次調(diào)用只帶一個(gè)技能名而非跨目錄文件鏈接或裸的/skill式提及跨技能共享的參考文檔歸擁有它的技能所有其他技能通過調(diào)用 Skill tool 獲取。七、ask-matt 路由器skills/engineering/ask-matt/SKILL.md 是一個(gè)特殊的用戶觸發(fā)技能它的職責(zé)是充當(dāng)路由器把每個(gè)用戶可觸達(dá)的技能及它們之間的關(guān)系映射出來。CLAUDE.md 特別強(qiáng)調(diào)每當(dāng)新增、重命名、移除或改變某個(gè)用戶可觸達(dá)技能在流程中的位置時(shí)必須重讀ask-matt的 SKILL.md 并更新它讓地圖保持準(zhǔn)確。一個(gè)它從未提及的新技能或一個(gè)它仍路由到的過時(shí)技能都是一個(gè)說謊的路由器。從 README 的描述看ask-matt的用途是詢問哪個(gè)技能或流程適合你的處境是所有用戶觸發(fā)技能的入口索引。它的同步觸發(fā)條件與 docs 頁面一致是倉庫維護(hù)流程中唯一一個(gè)需要行為同步的技能。八、本地鏈接腳本scripts/link-skills.shCLAUDE.md 說明要把每個(gè)技能重新鏈接進(jìn)本地各 Agent 的技能目錄運(yùn)行scripts/link-skills.sh腳本實(shí)現(xiàn)于 scripts/link-skills.sh要點(diǎn)如下目標(biāo)目錄為~/.claude/skillsClaude Code與~/.agents/skillsCodex 及其他兼容 Agent Skills 標(biāo)準(zhǔn)的 harness每條記錄都是指向本倉庫的符號(hào)鏈接因此git pull即可保持已安裝技能更新無需重新拷貝腳本開頭聲明這是僅限維護(hù)者的開發(fā)用腳本不是受支持的安裝器不接受改造請(qǐng)求它在倉庫內(nèi)find收集全部SKILL.md排除node_modules與deprecated/若目標(biāo)目錄本身是指向本倉庫的符號(hào)鏈接會(huì)檢測并拒絕執(zhí)行避免把每條符號(hào)鏈接寫回倉庫自身的skills/樹造成污染對(duì)已存在的普通文件目標(biāo)會(huì)先移除再重新ln -sfn建立鏈接。配套的 scripts/list-skills.sh 則簡單列出倉庫內(nèi)所有SKILL.md的排序路徑用于快速核對(duì)技能全集。九、寫作約束全倉庫禁用 em-dashCLAUDE.md 的最后一條規(guī)則看似風(fēng)格問題實(shí)則是一條可強(qiáng)制執(zhí)行的約束本倉庫所有 proseSKILL.md、docs、README.md、CHANGELOG.md、ADR、changesets、代碼注釋中不得出現(xiàn) em-dash—。當(dāng)句子需要它時(shí)改用逗號(hào)、冒號(hào)、句號(hào)、括號(hào)或連詞重寫絕不做盲目字符替換。這條規(guī)則的動(dòng)機(jī)是消除不同寫作風(fēng)格帶來的歧義同時(shí)它也出現(xiàn)在.changeset/中的變更記錄里如remove-em-dashes-repo-wide.md說明它確實(shí)是倉庫演進(jìn)過程中被嚴(yán)格執(zhí)行的規(guī)范而不是一句建議。從工程角度看這屬于用統(tǒng)一文體降低 Agent 解析成本的治理手段文檔作為 Agent 的上下文其標(biāo)點(diǎn)風(fēng)格一致性同樣影響理解質(zhì)量。十、維護(hù)工作流清單綜合 CLAUDE.md 與倉庫實(shí)現(xiàn)維護(hù)一個(gè)技能或整個(gè)倉庫的標(biāo)準(zhǔn)流程可以歸納為新增技能放入engineering/或productivity/promoted或在in-progress/中先行征求意見注冊(cè)在頂層 README.md 與其 bucket 的README.md中添加條目技能名鏈接到 SKILL.md并加入 .claude-plugin/plugin.json 的skills數(shù)組聲明調(diào)用模型按 .agents/invocation.md 配置SKILL.mdfrontmatter 與agents/openai.yaml兩類 harness 的聲明必須同步同步文檔頁按 .agents/writing-docs.md 在docs/bucket/skill-name.md創(chuàng)建或重寫四段式頁面更新路由器重讀 ask-matt 的 SKILL.md 并更新技能地圖校驗(yàn)插件清單改動(dòng) manifest 后運(yùn)行claude plugin validate . --strict并保持 plugin.json 的 version 與 package.json 同步本地重鏈接運(yùn)行scripts/link-skills.sh更新~/.claude/skills與~/.agents/skills下的符號(hào)鏈接檢查寫作規(guī)范確認(rèn)新 prose 中無 em-dash。總結(jié)CLAUDE.md用極短的篇幅把一個(gè)Agent 技能倉庫該有的工程紀(jì)律全部落地目錄分層決定發(fā)布邊界雙注冊(cè)機(jī)制保證 README 與插件清單不漂移install-block 單一來源統(tǒng)一了安裝文案ADR 記錄發(fā)行架構(gòu)的取舍invocation 約定劃清人機(jī)調(diào)用邊界ask-matt 路由器保持技能地圖不撒謊link-skills.sh 讓本地開發(fā)與 git pull 同步零成本。如果你正在維護(hù)自己的技能集合這份文件本身就是一份可復(fù)用的治理模板先定 bucket 與 promoted 邊界再定 manifest 校驗(yàn)與文檔同步流程最后用一條全倉庫文體約束收尾。【免費(fèi)下載鏈接】skillsSkills for Real Engineers. Straight from my .agents directory.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/skills13/skills創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考