1. 从“knowledge-work-plugins”这个仓库名说起第一次看到knowledge-work-plugins这个名字我脑子里冒出来的第一个念头是这大概率不是一个普通的工具库而是一套“给知识工作者用的插件集合”。事实也确实如此。这个仓库的核心定位是围绕 Claude Code 和 Claude Cowork 这类 AI 编程/协作客户端提供一批可以直接挂载的插件plugins和斜杠命令slash commands把日常重复性的知识工作——比如整理会议纪要、生成周报、批量重命名文件、格式化文档、做代码审查清单——变成一条命令就能触发的工作流。如果你已经在用 Claude Code但还停留在“打开终端、敲一句话、等它回你”的阶段那你其实只用了它三成的能力。knowledge-work-plugins这类插件体系真正解决的问题是把“每次都要重新描述一遍的提示词”固化成可复用、可分享、可版本管理的命令。这就像你以前每次做菜都要现查菜谱现在直接把菜谱贴在灶台边上喊一声“做红烧肉”就自动执行。这篇文章适合三类人看第一类是完全没接触过 Claude Code 插件、想知道这东西到底能干嘛的新手第二类是已经装了 Claude Code、但不知道怎么把自己的常用操作沉淀成插件的进阶用户第三类是想给团队搭一套统一知识工作流的负责人。我会从插件到底是什么、目录结构怎么设计、斜杠命令怎么写、怎么调试、怎么避坑这几个角度把这件事讲透。需要先说明一点knowledge-work-plugins本身是一个仓库名不同团队、不同版本的具体内容会有差异。下面我讲的结构和写法是基于 Claude Code 插件体系的通用实践以及我在实际搭建类似插件集时踩过的坑总结出来的。你照着做能跑通一套属于自己的知识工作插件集。2. Claude Code 的插件机制到底是怎么运转的2.1 插件不是“扩展程序”而是“提示词脚本配置”的打包很多人一听“插件”脑子里想的是浏览器扩展那种带 UI、带后台进程的东西。Claude Code 的插件不是这个逻辑。它更像是一个约定好目录结构的文件夹里面装着几类东西斜杠命令定义一个 Markdown 文件里面写清楚命令名、参数、以及触发后要执行的提示词模板。辅助脚本可以是 shell、Python、Node 脚本用来做文件处理、数据抓取、格式转换这类 AI 不擅长或不该做的事。配置文件声明这个插件叫什么、有哪些命令、依赖什么环境变量。模板与资源比如周报模板、代码审查清单、文档骨架。当你输入/weekly-report这样的命令时Claude Code 会去插件目录里找到对应的定义把模板和你的输入拼成一段完整的提示词再交给模型处理。如果命令里绑定了脚本它会先跑脚本拿到结果再把结果塞进提示词。这个机制的关键价值在于确定性。你手敲提示词每次措辞都不一样输出质量忽高忽低而插件里的提示词是写死的、经过调试的输出就稳定得多。2.2 为什么用 Markdown 而不是 JSON 来定义命令这是很多人第一次接触时会疑惑的点。用 Markdown 定义命令好处有三个第一可读性极强。你打开一个.md文件一眼就能看懂这个命令是干嘛的、需要什么参数、输出什么格式。JSON 写提示词光是转义引号就能把人逼疯。第二天然支持长文本。提示词模板往往很长Markdown 的段落、列表、代码块结构正好和提示词的写法契合。第三方便版本管理和协作。Git diff 里看 Markdown 的改动比看 JSON 的改动清楚太多。团队里谁改了哪句提示词一目了然。我自己的习惯是每个命令一个.md文件文件名就是命令名文件头部用一小段 YAML front matter 声明元信息比如描述、参数列表正文就是提示词模板。这样既保留了结构又不失灵活。2.3 插件目录的典型布局一个能跑起来的插件集目录结构大概长这样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里通常声明插件集名称、版本、命令列表、以及每个命令对应的文件路径。commands/目录是核心scripts/和templates/是支撑。提示目录名不要用中文也不要用空格。Claude Code 在解析路径时对特殊字符的处理并不总是友好用纯英文小写加连字符最稳。3. 斜杠命令的设计从“能用”到“好用”的分水岭3.1 命令粒度一个命令只做一件事我见过最糟糕的插件设计是一个命令叫/do-everything里面塞了二十个分支逻辑。这种命令写起来爽用起来灾难——你永远不知道它这次会走哪条路。正确的做法是一个命令对应一个明确的任务。比如/weekly-report根据本周的 git 提交记录和任务清单生成周报。/meeting-notes把一段会议录音转写文本整理成结构化纪要。/code-review对指定文件做一轮代码审查输出问题清单。每个命令的输入、输出、边界都清清楚楚。用户想干不同的事就敲不同的命令。这符合 Unix 的“做一件事并做好”的哲学。3.2 参数设计让命令能接受外部输入一个只能输出固定内容的命令价值有限。真正好用的命令要能接受参数。在 Markdown 定义里参数通常用占位符表示比如{{file}}、{{date}}、{{topic}}。举个例子/weekly-report的定义可能是这样--- name: weekly-report description: 生成本周工作周报 args: - name: range description: 时间范围如 last-week 或 2024-01-01..2024-01-07 default: last-week --- 请根据以下 git 提交记录生成一份结构化的周报。 时间范围{{range}} 提交记录 {{git_log}} 要求 1. 按项目分组 2. 每条提交用一句话概括 3. 最后给出下周计划建议用户敲/weekly-report rangelast-weekClaude Code 就会把{{range}}替换掉同时执行绑定的脚本拿到{{git_log}}拼成完整提示词。这里有个细节参数要有默认值。不是每次用户都想指定范围给个合理的默认值能大幅降低使用门槛。3.3 提示词模板的写法把“隐含要求”显式化新手写提示词模板最容易犯的错是“我以为模型懂”。比如你写“整理一下会议纪要”模型可能给你输出一段流水账也可能输出一个表格全看它心情。好的模板会把要求拆到不能再拆请把下面的会议记录整理成纪要严格按以下结构输出 ## 会议主题 一句话概括 ## 参会人 列出所有出现的人名 ## 讨论要点 每条不超过两句话按重要性排序 ## 待办事项 格式负责人 - 事项 - 截止时间 ## 遗留问题 没有结论的议题 会议记录原文 {{transcript}}这样写输出质量立刻稳定。我自己的经验是模板里每多一句明确要求输出就少一次返工。3.4 命令命名动词开头短而具体命令名是用户每天要敲的东西命名要讲究用动词开头/generate-report比/report-generator好。尽量短/weekly比/generate-weekly-report好但别短到看不懂。避免歧义/review太泛/code-review更明确。用连字符分隔单词别用下划线或驼峰。我一般会先在纸上列一遍所有命令名然后假装自己是用户闭着眼睛敲一遍看会不会敲错、会不会记混。记混的命令名趁早改。4. 把脚本接进插件AI 不擅长的活交给代码4.1 什么该交给脚本什么该交给模型这是插件设计里最关键的判断。我的原则是任务类型交给谁原因读取 git 日志脚本确定性操作模型做反而慢且易错统计代码行数脚本纯计算模型不擅长精确计数总结提交内容模型需要语义理解格式化输出脚本规则明确模型做容易跑偏判断代码质量模型需要上下文推理文件重命名脚本涉及文件系统操作模型不该直接碰一句话总结确定性的、涉及文件系统和精确计算的交给脚本需要理解、归纳、生成的交给模型。4.2 脚本与命令的绑定方式在命令定义里可以通过 front matter 声明要执行的脚本--- name: weekly-report scripts: - name: git_log command: bash scripts/collect_git_log.sh {{range}} output: stdout ---Claude Code 会先跑collect_git_log.sh把 stdout 的内容作为{{git_log}}变量注入提示词。脚本执行失败时命令会中止并报错不会把空内容喂给模型。这里有个坑脚本的输出要有明确边界。如果脚本输出几千行 git 日志提示词会被撑爆。我的做法是在脚本里就做好过滤和截断比如只取最近 50 条提交每条只保留标题行。4.3 脚本的健壮性错误处理不能省脚本跑在用户机器上环境千差万别。你本地能跑的脚本换台机器可能就挂。几个必须做的防护#!/usr/bin/env bash set -euo pipefail # 检查依赖命令是否存在 if ! command -v git /dev/null; then echo 错误未找到 git 命令 2 exit 1 fi # 检查是否在 git 仓库内 if ! git rev-parse --is-inside-work-tree /dev/null; then echo 错误当前目录不是 git 仓库 2 exit 1 fi # 正常逻辑 git log --oneline --since1 week ago | head -50set -euo pipefail这三件套是 shell 脚本的基本功遇到错误退出、未定义变量报错、管道中任一环节失败就失败。少了这个脚本出错时会静默继续最后给你一个莫名其妙的输出。注意脚本里的错误信息要写到 stderr2不要写到 stdout。stdout 是给模型看的stderr 是给用户看的。混在一起模型会把错误信息当成正常内容处理。5. 调试插件那些文档里不会写的排查思路5.1 命令不生效先查这三处插件装好了敲命令没反应别急着怀疑人生。按这个顺序查第一查命令文件是否被正确加载。很多插件体系要求命令文件放在特定目录且文件名和命令名严格对应。/weekly-report对应的文件必须是weekly-report.md差一个字符都不行。第二查 front matter 格式。YAML front matter 对缩进极其敏感。用空格不用 Tab冒号后面要有空格列表项缩进要一致。我见过太多次因为一个 Tab 导致整个命令失效的案例。第三查命令是否被其他插件覆盖。如果你装了多个插件集命令名冲突时后加载的会覆盖先加载的。给命令加个前缀比如/kw-weekly-report能避免这类问题。5.2 输出质量不稳定从模板找原因同一个命令有时输出很好有时一塌糊涂。这通常不是模型的问题而是模板的问题。几个常见原因模板里有歧义表述。比如“简洁一点”什么叫简洁改成“每条不超过 30 字”就明确了。输入内容格式不固定。脚本输出的格式如果随环境变化模型就得猜输出自然不稳。缺少示例。在模板里给一个输出示例模型会照着模仿稳定性大幅提升。我的习惯是每次输出不理想不急着改提示词先把这次的输入和输出存下来攒够五个案例再一起分析。往往能发现是某一类输入触发了问题。5.3 脚本报错但看不到错误信息这是最让人抓狂的情况。命令执行了但结果不对又不知道脚本哪里出错。原因是脚本的 stderr 被吞了。解决办法是在命令定义里显式声明要捕获 stderr或者在脚本里把关键步骤的日志写到文件exec 2 /tmp/kw-plugin-debug.log set -xset -x会打印每条执行的命令配合日志文件能快速定位问题。调试完记得去掉不然日志会越来越大。6. 团队协作场景下的插件管理6.1 插件集要进版本控制knowledge-work-plugins这类仓库本质上是团队知识资产。它应该像代码一样进 Git有 commit、有 PR、有 review。我见过有团队把插件放在共享网盘里结果版本混乱A 改了一版B 又覆盖回去最后没人知道线上跑的是哪版。进 Git 之后每次改动都有记录出问题能回滚新人能看历史。6.2 命令的向后兼容团队用起来之后改命令要谨慎。你今天把/weekly-report的参数从range改成period明天所有人的脚本就都挂了。几个原则新增参数给默认值不破坏老用法。废弃参数保留一段时间在文档里标注 deprecated给团队迁移时间。重大变更升版本号在 README 里写清楚迁移步骤。6.3 插件文档怎么写才有人看团队插件的 README不要写成 API 手册。没人看。要写成“场景 命令 示例”的形式## 生成周报 每周五下午敲 /weekly-report 默认统计最近 7 天的提交。想指定范围 /weekly-report range2024-01-01..2024-01-07 输出会直接贴到你的剪贴板粘到周报文档里就行。用户关心的是“我什么时候用、怎么用、用完得到什么”不是“这个命令有几个参数、参数类型是什么”。7. 我踩过的几个坑和对应的解法7.1 提示词太长导致截断早期我写命令恨不得把所有要求都塞进模板结果提示词超过模型上下文限制后半段被截断输出缺斤少两。解法是分层核心要求放模板细节要求放模板引用的子文件。比如主模板里写“按 templates/report.md 的结构输出”具体结构定义在子文件里。这样主模板保持精简细节按需加载。7.2 脚本路径用相对路径导致找不到文件脚本里写./scripts/foo.sh在插件根目录跑没问题换个目录就挂。解法是用脚本自身位置推导绝对路径SCRIPT_DIR$(cd $(dirname ${BASH_SOURCE[0]}) pwd) source $SCRIPT_DIR/common.sh这样无论从哪调用路径都对。7.3 命令名和系统命令冲突我有个命令叫/ls结果和系统ls冲突敲下去行为诡异。解法是给所有自定义命令加统一前缀比如/kw-。虽然多敲几个字符但避免了所有冲突。7.4 输出格式在不同终端下不一致同样的命令在 iTerm 里输出正常在 VS Code 终端里就乱码。原因是终端对 Unicode 和颜色的支持不同。解法是输出纯文本不带颜色和特殊字符。插件输出是给模型和用户看的不是给终端炫技的。需要强调就用 Markdown 的加粗和列表别用 ANSI 转义码。8. 从零搭一套自己的知识工作插件集8.1 先列场景再写命令别一上来就写代码。先拿张纸列出你每天重复做的知识工作每天早上要看昨天的提交写日报每周要整理会议纪要每次代码合并前要做一轮自查每月要汇总项目进展列完之后按频率排序先做最高频的那几个。低频的等有精力再说。8.2 最小可用版本一个命令跑通第一个命令不要追求完美。就做一个最简单的输入一段文本输出一个固定格式的结果。跑通之后再逐步加脚本、加参数、加模板。我搭第一版的时候就一个/summarize命令把一段文字总结成三句话。跑通那一刻整个插件体系的运作逻辑就清楚了后面加什么都快。8.3 逐步沉淀把临时提示词变成命令日常用 Claude Code 时如果发现某段提示词你反复用立刻把它抽成命令。别想着“等有空再整理”等你有空的时候那段提示词早忘了。我的做法是在插件目录里放一个drafts/文件夹随手把好用的提示词扔进去周末统一整理成正式命令。这样既不打断工作流又能持续沉淀。8.4 定期清理删掉没人用的命令插件集用久了会臃肿。每季度过一遍命令列表看哪些三个月没人用过直接删。留着只会让新人在命令列表里迷路。删之前可以在 README 里记一笔“已废弃命令”万一有人还在用能查到去哪找替代方案。9. 关于插件生态的一点个人观察knowledge-work-plugins这类仓库的出现反映了一个趋势AI 工具的使用正在从“对话式”走向“命令式”。对话式适合探索命令式适合重复。知识工作里真正耗时的恰恰是那些重复的部分。我自己的体会是搭插件集这件事投入产出比在前期不明显但一旦跨过某个临界点效率提升是断崖式的。以前写周报要半小时现在敲一条命令改改就发。省下来的时间够我多读几篇论文。另一个观察是插件集的质量最终取决于你对“自己工作流”的理解深度。你越清楚自己每天在重复什么、哪些环节可以固化插件就越好用。工具是表象对工作的拆解才是内核。如果你刚开始别贪多。先做一个命令用一周感受一下。觉得值再往下走。这个领域没有标准答案适合自己的节奏最重要。