1. 從“knowledge-work-plugins”這個倉庫名說起第一次看到knowledge-work-plugins這個名字我腦子里冒出來的第一個念頭是這大概率不是一個普通的工具庫而是一套“給知識工作者用的插件集合”。事實也確實如此。這個倉庫的核心定位是圍繞 Claude Code 和 Claude Cowork 這類 AI 編程/協(xié)作客戶端提供一批可以直接掛載的插件plugins和斜杠命令slash commands把日常重復(fù)性的知識工作——比如整理會議紀(jì)要、生成周報、批量重命名文件、格式化文檔、做代碼審查清單——變成一條命令就能觸發(fā)的工作流。如果你已經(jīng)在用 Claude Code但還停留在“打開終端、敲一句話、等它回你”的階段那你其實只用了它三成的能力。knowledge-work-plugins這類插件體系真正解決的問題是把“每次都要重新描述一遍的提示詞”固化成可復(fù)用、可分享、可版本管理的命令。這就像你以前每次做菜都要現(xiàn)查菜譜現(xiàn)在直接把菜譜貼在灶臺邊上喊一聲“做紅燒肉”就自動執(zhí)行。這篇文章適合三類人看第一類是完全沒接觸過 Claude Code 插件、想知道這東西到底能干嘛的新手第二類是已經(jīng)裝了 Claude Code、但不知道怎么把自己的常用操作沉淀成插件的進(jìn)階用戶第三類是想給團(tuán)隊搭一套統(tǒng)一知識工作流的負(fù)責(zé)人。我會從插件到底是什么、目錄結(jié)構(gòu)怎么設(shè)計、斜杠命令怎么寫、怎么調(diào)試、怎么避坑這幾個角度把這件事講透。需要先說明一點knowledge-work-plugins本身是一個倉庫名不同團(tuán)隊、不同版本的具體內(nèi)容會有差異。下面我講的結(jié)構(gòu)和寫法是基于 Claude Code 插件體系的通用實踐以及我在實際搭建類似插件集時踩過的坑總結(jié)出來的。你照著做能跑通一套屬于自己的知識工作插件集。2. Claude Code 的插件機(jī)制到底是怎么運(yùn)轉(zhuǎn)的2.1 插件不是“擴(kuò)展程序”而是“提示詞腳本配置”的打包很多人一聽“插件”腦子里想的是瀏覽器擴(kuò)展那種帶 UI、帶后臺進(jìn)程的東西。Claude Code 的插件不是這個邏輯。它更像是一個約定好目錄結(jié)構(gòu)的文件夾里面裝著幾類東西斜杠命令定義一個 Markdown 文件里面寫清楚命令名、參數(shù)、以及觸發(fā)后要執(zhí)行的提示詞模板。輔助腳本可以是 shell、Python、Node 腳本用來做文件處理、數(shù)據(jù)抓取、格式轉(zhuǎn)換這類 AI 不擅長或不該做的事。配置文件聲明這個插件叫什么、有哪些命令、依賴什么環(huán)境變量。模板與資源比如周報模板、代碼審查清單、文檔骨架。當(dāng)你輸入/weekly-report這樣的命令時Claude Code 會去插件目錄里找到對應(yīng)的定義把模板和你的輸入拼成一段完整的提示詞再交給模型處理。如果命令里綁定了腳本它會先跑腳本拿到結(jié)果再把結(jié)果塞進(jìn)提示詞。這個機(jī)制的關(guān)鍵價值在于確定性。你手敲提示詞每次措辭都不一樣輸出質(zhì)量忽高忽低而插件里的提示詞是寫死的、經(jīng)過調(diào)試的輸出就穩(wěn)定得多。2.2 為什么用 Markdown 而不是 JSON 來定義命令這是很多人第一次接觸時會疑惑的點。用 Markdown 定義命令好處有三個第一可讀性極強(qiáng)。你打開一個.md文件一眼就能看懂這個命令是干嘛的、需要什么參數(shù)、輸出什么格式。JSON 寫提示詞光是轉(zhuǎn)義引號就能把人逼瘋。第二天然支持長文本。提示詞模板往往很長Markdown 的段落、列表、代碼塊結(jié)構(gòu)正好和提示詞的寫法契合。第三方便版本管理和協(xié)作。Git diff 里看 Markdown 的改動比看 JSON 的改動清楚太多。團(tuán)隊里誰改了哪句提示詞一目了然。我自己的習(xí)慣是每個命令一個.md文件文件名就是命令名文件頭部用一小段 YAML front matter 聲明元信息比如描述、參數(shù)列表正文就是提示詞模板。這樣既保留了結(jié)構(gòu)又不失靈活。2.3 插件目錄的典型布局一個能跑起來的插件集目錄結(jié)構(gòu)大概長這樣knowledge-work-plugins/ ├── plugin.json # 插件集元信息 ├── commands/ # 斜杠命令定義 │ ├── weekly-report.md │ ├── meeting-notes.md │ └── code-review.md ├── scripts/ # 輔助腳本 │ ├── collect_git_log.sh │ └── format_markdown.py ├── templates/ # 輸出模板 │ ├── report.md │ └── review-checklist.md └── README.mdplugin.json里通常聲明插件集名稱、版本、命令列表、以及每個命令對應(yīng)的文件路徑。commands/目錄是核心scripts/和templates/是支撐。提示目錄名不要用中文也不要用空格。Claude Code 在解析路徑時對特殊字符的處理并不總是友好用純英文小寫加連字符最穩(wěn)。3. 斜杠命令的設(shè)計從“能用”到“好用”的分水嶺3.1 命令粒度一個命令只做一件事我見過最糟糕的插件設(shè)計是一個命令叫/do-everything里面塞了二十個分支邏輯。這種命令寫起來爽用起來災(zāi)難——你永遠(yuǎn)不知道它這次會走哪條路。正確的做法是一個命令對應(yīng)一個明確的任務(wù)。比如/weekly-report根據(jù)本周的 git 提交記錄和任務(wù)清單生成周報。/meeting-notes把一段會議錄音轉(zhuǎn)寫文本整理成結(jié)構(gòu)化紀(jì)要。/code-review對指定文件做一輪代碼審查輸出問題清單。每個命令的輸入、輸出、邊界都清清楚楚。用戶想干不同的事就敲不同的命令。這符合 Unix 的“做一件事并做好”的哲學(xué)。3.2 參數(shù)設(shè)計讓命令能接受外部輸入一個只能輸出固定內(nèi)容的命令價值有限。真正好用的命令要能接受參數(shù)。在 Markdown 定義里參數(shù)通常用占位符表示比如{{file}}、{{date}}、{{topic}}。舉個例子/weekly-report的定義可能是這樣--- name: weekly-report description: 生成本周工作周報 args: - name: range description: 時間范圍如 last-week 或 2024-01-01..2024-01-07 default: last-week --- 請根據(jù)以下 git 提交記錄生成一份結(jié)構(gòu)化的周報。 時間范圍{{range}} 提交記錄 {{git_log}} 要求 1. 按項目分組 2. 每條提交用一句話概括 3. 最后給出下周計劃建議用戶敲/weekly-report rangelast-weekClaude Code 就會把{{range}}替換掉同時執(zhí)行綁定的腳本拿到{{git_log}}拼成完整提示詞。這里有個細(xì)節(jié)參數(shù)要有默認(rèn)值。不是每次用戶都想指定范圍給個合理的默認(rèn)值能大幅降低使用門檻。3.3 提示詞模板的寫法把“隱含要求”顯式化新手寫提示詞模板最容易犯的錯是“我以為模型懂”。比如你寫“整理一下會議紀(jì)要”模型可能給你輸出一段流水賬也可能輸出一個表格全看它心情。好的模板會把要求拆到不能再拆請把下面的會議記錄整理成紀(jì)要嚴(yán)格按以下結(jié)構(gòu)輸出 ## 會議主題 一句話概括 ## 參會人 列出所有出現(xiàn)的人名 ## 討論要點 每條不超過兩句話按重要性排序 ## 待辦事項 格式負(fù)責(zé)人 - 事項 - 截止時間 ## 遺留問題 沒有結(jié)論的議題 會議記錄原文 {{transcript}}這樣寫輸出質(zhì)量立刻穩(wěn)定。我自己的經(jīng)驗是模板里每多一句明確要求輸出就少一次返工。3.4 命令命名動詞開頭短而具體命令名是用戶每天要敲的東西命名要講究用動詞開頭/generate-report比/report-generator好。盡量短/weekly比/generate-weekly-report好但別短到看不懂。避免歧義/review太泛/code-review更明確。用連字符分隔單詞別用下劃線或駝峰。我一般會先在紙上列一遍所有命令名然后假裝自己是用戶閉著眼睛敲一遍看會不會敲錯、會不會記混。記混的命令名趁早改。4. 把腳本接進(jìn)插件AI 不擅長的活交給代碼4.1 什么該交給腳本什么該交給模型這是插件設(shè)計里最關(guān)鍵的判斷。我的原則是任務(wù)類型交給誰原因讀取 git 日志腳本確定性操作模型做反而慢且易錯統(tǒng)計代碼行數(shù)腳本純計算模型不擅長精確計數(shù)總結(jié)提交內(nèi)容模型需要語義理解格式化輸出腳本規(guī)則明確模型做容易跑偏判斷代碼質(zhì)量模型需要上下文推理文件重命名腳本涉及文件系統(tǒng)操作模型不該直接碰一句話總結(jié)確定性的、涉及文件系統(tǒng)和精確計算的交給腳本需要理解、歸納、生成的交給模型。4.2 腳本與命令的綁定方式在命令定義里可以通過 front matter 聲明要執(zhí)行的腳本--- name: weekly-report scripts: - name: git_log command: bash scripts/collect_git_log.sh {{range}} output: stdout ---Claude Code 會先跑collect_git_log.sh把 stdout 的內(nèi)容作為{{git_log}}變量注入提示詞。腳本執(zhí)行失敗時命令會中止并報錯不會把空內(nèi)容喂給模型。這里有個坑腳本的輸出要有明確邊界。如果腳本輸出幾千行 git 日志提示詞會被撐爆。我的做法是在腳本里就做好過濾和截斷比如只取最近 50 條提交每條只保留標(biāo)題行。4.3 腳本的健壯性錯誤處理不能省腳本跑在用戶機(jī)器上環(huán)境千差萬別。你本地能跑的腳本換臺機(jī)器可能就掛。幾個必須做的防護(hù)#!/usr/bin/env bash set -euo pipefail # 檢查依賴命令是否存在 if ! command -v git /dev/null; then echo 錯誤未找到 git 命令 2 exit 1 fi # 檢查是否在 git 倉庫內(nèi) if ! git rev-parse --is-inside-work-tree /dev/null; then echo 錯誤當(dāng)前目錄不是 git 倉庫 2 exit 1 fi # 正常邏輯 git log --oneline --since1 week ago | head -50set -euo pipefail這三件套是 shell 腳本的基本功遇到錯誤退出、未定義變量報錯、管道中任一環(huán)節(jié)失敗就失敗。少了這個腳本出錯時會靜默繼續(xù)最后給你一個莫名其妙的輸出。注意腳本里的錯誤信息要寫到 stderr2不要寫到 stdout。stdout 是給模型看的stderr 是給用戶看的。混在一起模型會把錯誤信息當(dāng)成正常內(nèi)容處理。5. 調(diào)試插件那些文檔里不會寫的排查思路5.1 命令不生效先查這三處插件裝好了敲命令沒反應(yīng)別急著懷疑人生。按這個順序查第一查命令文件是否被正確加載。很多插件體系要求命令文件放在特定目錄且文件名和命令名嚴(yán)格對應(yīng)。/weekly-report對應(yīng)的文件必須是weekly-report.md差一個字符都不行。第二查 front matter 格式。YAML front matter 對縮進(jìn)極其敏感。用空格不用 Tab冒號后面要有空格列表項縮進(jìn)要一致。我見過太多次因為一個 Tab 導(dǎo)致整個命令失效的案例。第三查命令是否被其他插件覆蓋。如果你裝了多個插件集命令名沖突時后加載的會覆蓋先加載的。給命令加個前綴比如/kw-weekly-report能避免這類問題。5.2 輸出質(zhì)量不穩(wěn)定從模板找原因同一個命令有時輸出很好有時一塌糊涂。這通常不是模型的問題而是模板的問題。幾個常見原因模板里有歧義表述。比如“簡潔一點”什么叫簡潔改成“每條不超過 30 字”就明確了。輸入內(nèi)容格式不固定。腳本輸出的格式如果隨環(huán)境變化模型就得猜輸出自然不穩(wěn)。缺少示例。在模板里給一個輸出示例模型會照著模仿穩(wěn)定性大幅提升。我的習(xí)慣是每次輸出不理想不急著改提示詞先把這次的輸入和輸出存下來攢夠五個案例再一起分析。往往能發(fā)現(xiàn)是某一類輸入觸發(fā)了問題。5.3 腳本報錯但看不到錯誤信息這是最讓人抓狂的情況。命令執(zhí)行了但結(jié)果不對又不知道腳本哪里出錯。原因是腳本的 stderr 被吞了。解決辦法是在命令定義里顯式聲明要捕獲 stderr或者在腳本里把關(guān)鍵步驟的日志寫到文件exec 2 /tmp/kw-plugin-debug.log set -xset -x會打印每條執(zhí)行的命令配合日志文件能快速定位問題。調(diào)試完記得去掉不然日志會越來越大。6. 團(tuán)隊協(xié)作場景下的插件管理6.1 插件集要進(jìn)版本控制knowledge-work-plugins這類倉庫本質(zhì)上是團(tuán)隊知識資產(chǎn)。它應(yīng)該像代碼一樣進(jìn) Git有 commit、有 PR、有 review。我見過有團(tuán)隊把插件放在共享網(wǎng)盤里結(jié)果版本混亂A 改了一版B 又覆蓋回去最后沒人知道線上跑的是哪版。進(jìn) Git 之后每次改動都有記錄出問題能回滾新人能看歷史。6.2 命令的向后兼容團(tuán)隊用起來之后改命令要謹(jǐn)慎。你今天把/weekly-report的參數(shù)從range改成period明天所有人的腳本就都掛了。幾個原則新增參數(shù)給默認(rèn)值不破壞老用法。廢棄參數(shù)保留一段時間在文檔里標(biāo)注 deprecated給團(tuán)隊遷移時間。重大變更升版本號在 README 里寫清楚遷移步驟。6.3 插件文檔怎么寫才有人看團(tuán)隊插件的 README不要寫成 API 手冊。沒人看。要寫成“場景 命令 示例”的形式## 生成周報 每周五下午敲 /weekly-report 默認(rèn)統(tǒng)計最近 7 天的提交。想指定范圍 /weekly-report range2024-01-01..2024-01-07 輸出會直接貼到你的剪貼板粘到周報文檔里就行。用戶關(guān)心的是“我什么時候用、怎么用、用完得到什么”不是“這個命令有幾個參數(shù)、參數(shù)類型是什么”。7. 我踩過的幾個坑和對應(yīng)的解法7.1 提示詞太長導(dǎo)致截斷早期我寫命令恨不得把所有要求都塞進(jìn)模板結(jié)果提示詞超過模型上下文限制后半段被截斷輸出缺斤少兩。解法是分層核心要求放模板細(xì)節(jié)要求放模板引用的子文件。比如主模板里寫“按 templates/report.md 的結(jié)構(gòu)輸出”具體結(jié)構(gòu)定義在子文件里。這樣主模板保持精簡細(xì)節(jié)按需加載。7.2 腳本路徑用相對路徑導(dǎo)致找不到文件腳本里寫./scripts/foo.sh在插件根目錄跑沒問題換個目錄就掛。解法是用腳本自身位置推導(dǎo)絕對路徑SCRIPT_DIR$(cd $(dirname ${BASH_SOURCE[0]}) pwd) source $SCRIPT_DIR/common.sh這樣無論從哪調(diào)用路徑都對。7.3 命令名和系統(tǒng)命令沖突我有個命令叫/ls結(jié)果和系統(tǒng)ls沖突敲下去行為詭異。解法是給所有自定義命令加統(tǒng)一前綴比如/kw-。雖然多敲幾個字符但避免了所有沖突。7.4 輸出格式在不同終端下不一致同樣的命令在 iTerm 里輸出正常在 VS Code 終端里就亂碼。原因是終端對 Unicode 和顏色的支持不同。解法是輸出純文本不帶顏色和特殊字符。插件輸出是給模型和用戶看的不是給終端炫技的。需要強(qiáng)調(diào)就用 Markdown 的加粗和列表別用 ANSI 轉(zhuǎn)義碼。8. 從零搭一套自己的知識工作插件集8.1 先列場景再寫命令別一上來就寫代碼。先拿張紙列出你每天重復(fù)做的知識工作每天早上要看昨天的提交寫日報每周要整理會議紀(jì)要每次代碼合并前要做一輪自查每月要匯總項目進(jìn)展列完之后按頻率排序先做最高頻的那幾個。低頻的等有精力再說。8.2 最小可用版本一個命令跑通第一個命令不要追求完美。就做一個最簡單的輸入一段文本輸出一個固定格式的結(jié)果。跑通之后再逐步加腳本、加參數(shù)、加模板。我搭第一版的時候就一個/summarize命令把一段文字總結(jié)成三句話。跑通那一刻整個插件體系的運(yùn)作邏輯就清楚了后面加什么都快。8.3 逐步沉淀把臨時提示詞變成命令日常用 Claude Code 時如果發(fā)現(xiàn)某段提示詞你反復(fù)用立刻把它抽成命令。別想著“等有空再整理”等你有空的時候那段提示詞早忘了。我的做法是在插件目錄里放一個drafts/文件夾隨手把好用的提示詞扔進(jìn)去周末統(tǒng)一整理成正式命令。這樣既不打斷工作流又能持續(xù)沉淀。8.4 定期清理刪掉沒人用的命令插件集用久了會臃腫。每季度過一遍命令列表看哪些三個月沒人用過直接刪。留著只會讓新人在命令列表里迷路。刪之前可以在 README 里記一筆“已廢棄命令”萬一有人還在用能查到去哪找替代方案。9. 關(guān)于插件生態(tài)的一點個人觀察knowledge-work-plugins這類倉庫的出現(xiàn)反映了一個趨勢AI 工具的使用正在從“對話式”走向“命令式”。對話式適合探索命令式適合重復(fù)。知識工作里真正耗時的恰恰是那些重復(fù)的部分。我自己的體會是搭插件集這件事投入產(chǎn)出比在前期不明顯但一旦跨過某個臨界點效率提升是斷崖式的。以前寫周報要半小時現(xiàn)在敲一條命令改改就發(fā)。省下來的時間夠我多讀幾篇論文。另一個觀察是插件集的質(zhì)量最終取決于你對“自己工作流”的理解深度。你越清楚自己每天在重復(fù)什么、哪些環(huán)節(jié)可以固化插件就越好用。工具是表象對工作的拆解才是內(nèi)核。如果你剛開始別貪多。先做一個命令用一周感受一下。覺得值再往下走。這個領(lǐng)域沒有標(biāo)準(zhǔn)答案適合自己的節(jié)奏最重要。