1. 从knowledge-work-plugins这个命名说起它到底想解决什么问题第一次看到knowledge-work-plugins这个仓库名我的直觉是这不是又一个工具集合而是一套面向知识工作者的能力扩展框架。知识工作knowledge work这个词本身就划定了边界——它不处理图像渲染、不搞游戏引擎、不做嵌入式驱动它瞄准的是写文档、做调研、整理会议纪要、维护知识库、跑数据分析、写代码注释这类以信息和文本为核心载体的活儿。而 plugins 这个词在 Claude Code 和 Claude Cowork 的语境下指的是一套可插拔的能力包。你可以把它理解成给一个通用助手装上不同的专业工具箱装上财务插件它就懂报表口径装上法务插件它就懂合同条款的常见风险点装上研发插件它就知道你们的代码规范和提交习惯。这个仓库的核心价值我认为有三层第一层是复用把团队里反复用到的提示词、slash commands、上下文文件、脚本封装成插件避免每个人从零写 prompt。第二层是约束通过插件把我们团队做事的方式固化下来新人接入后天然就按规范走而不是靠口头传达。第三层是组合不同插件可以叠加比如会议纪要插件 项目周报插件 术语表插件组合起来就能把一次会议直接转成符合团队格式的周报草稿。适合读这篇的人有三类一是刚开始接触 Claude Code、想搞清楚 plugins 和 slash commands 到底怎么落地的人二是团队里负责把 AI 用起来的那个人需要一套可复制的组织方式三是已经用过一段时间、但感觉每次都在重复写提示词、想系统化沉淀的人。我下面讲的东西一部分来自这个仓库本身的组织思路一部分来自我在实际把类似插件体系跑起来时踩过的坑。凡是原文没写、我基于常见实践补出来的部分我会明确标出来。2. 拆开一个 knowledge-work plugin 的骨架它由哪几块拼成2.1 插件不是一个文件而是一个约定好的目录结构很多人第一次接触 plugins会以为它就是丢一个 markdown 进去。实际不是。一个能被称为 plugin 的东西通常包含这么几类资产资产类型作用典型文件命令定义定义 slash command 的入口和参数commands/*.md或commands/*.toml提示词模板命令背后真正执行的指令正文内嵌在命令文件里或独立模板上下文文件给模型提供领域知识、术语、规范context/、knowledge/下的 md配置清单声明插件名、版本、依赖、触发方式plugin.json/manifest类文件辅助脚本需要确定性执行的部分如格式化、校验scripts/*.sh、*.py这个结构的意义在于把不确定的生成和确定的处理分开。模型负责理解和生成脚本负责那些必须精确的事情比如把日期格式统一成 ISO、把 JSON 校验一遍、把文件按命名规范重命名。我见过太多人把所有逻辑都塞进 prompt结果模型偶尔发挥一下输出就不符合规范了。2.2 slash command 是插件的用户界面slash commands斜杠命令是这套体系里最直观的部分。你在对话里敲/后面跟一个命令名就触发对应插件的逻辑。它的设计哲学是把高频操作变成肌肉记忆。举个我实际用过的例子团队里每周要写周报格式固定为本周完成 / 下周计划 / 风险与阻塞三段。以前每个人写法五花八门后来我们做了一个/weekly命令它做三件事读取本周的 git 提交记录和会议纪要文件按固定三段式结构组织输出成 markdown直接贴进周报系统。命令定义大致长这样这是基于常见实践的示例不是仓库原文--- name: weekly description: 生成本周周报草稿 --- 请阅读 context/team-glossary.md 了解团队术语 然后基于以下材料生成本周周报严格使用三段式结构 - 本周完成 - 下周计划 - 风险与阻塞 材料 $ARGUMENTS这里有个关键点$ARGUMENTS是参数占位符。你可以/weekly 本周主要在做插件体系把补充信息传进去。这个机制让命令既有固定骨架又能接受临时输入。2.3 为什么用 markdown 而不是纯代码来定义命令这是很多人会问的问题。我的理解是命令的本质是给模型的指令而不是给机器的代码。用 markdown 写好处是非工程背景的同事也能改改完直接生效不用编译指令本身可读review 的时候一眼能看出这个命令让模型干什么可以自然嵌入示例、反例、格式要求这些都是纯代码不好表达的。代价是缺乏强类型校验容易写出歧义指令。所以我的经验是命令文件里凡是涉及必须精确的部分都要用脚本兜底别指望模型每次都听话。3. 把插件真正跑起来从零到可用的完整链路3.1 环境准备里最容易被忽略的两件事假设你已经装好了 Claude Code安装过程这里不展开热词里那一堆claude code安装ubuntu安装claude code说明这块资料已经很多了接下来要接插件体系有两件事新手几乎必踩第一件插件目录的位置。插件不是随便放哪都能被识别。通常有一个约定的插件根目录比如用户级的~/.claude/plugins/或项目级的.claude/plugins/。放错位置命令敲出来就是unknown command。我的建议是项目相关的插件放项目级个人通用工具放用户级这样换项目时不会互相污染。第二件命令名冲突。如果你装了两个插件都定义了/summary后加载的会覆盖先加载的或者直接报冲突。解决办法是给命令加前缀比如/fin-summary、/dev-summary。这个坑我在团队里见过不止一次两个人各自做了个/report合并后其中一个直接失效排查了半天。提示装完插件后先用/help或命令列表确认它真的被加载了别急着写业务逻辑。加载失败时优先检查目录位置和清单文件格式而不是怀疑命令内容写错了。3.2 一个最小可用插件的搭建步骤我按实际操作的顺序列一遍你可以直接照着做建目录在插件根目录下新建my-first-plugin/。写清单创建plugin.json至少包含name、version、description三个字段。版本号建议从0.1.0起方便后续迭代。建命令目录commands/在里面放你的第一个命令文件hello.md。写命令正文定义这个命令让模型做什么包含输入说明、输出格式、约束条件。加一个上下文文件context/glossary.md放团队术语让模型理解你们的黑话。测试在对话里敲/hello看输出是否符合预期。迭代根据实际输出调整指令把模型总是做错的地方改成更明确的约束或者干脆用脚本处理。这套流程看起来简单但第 4 步和第 7 步是真正花时间的地方。写命令不是一次成型而是跑一遍、看哪里不对、补一句约束的循环。3.3 命令参数怎么设计才不容易翻车参数设计有个反直觉的经验参数越少越好能自动获取的绝不让人手输。比如一个生成会议纪要的命令如果设计成/minutes 会议主题 参会人 时间 讨论内容那基本没人愿意用因为输入成本太高。更好的设计是/minutes让它自己去读当前目录下的会议记录文件或者读剪贴板内容。参数只保留那些模型无法自己知道的信息。如果确实需要参数用位置参数还是命名参数我的建议是单个可选补充信息用$ARGUMENTS整体接收让模型自己解析多个结构化参数用命名参数如--date、--author并在命令文件里写清楚每个参数的含义和格式。4. 插件体系里那些文档不会写的实战经验4.1 上下文文件要薄不要厚新手容易犯的错是把所有能想到的领域知识都塞进context/结果上下文文件几千行模型每次都要读一遍既慢又容易抓不住重点。我的做法是分层glossary.md只放术语对照控制在几十条以内style-guide.md放写作规范用要/不要的短句不用长篇解释具体业务知识按主题拆成多个文件命令里按需引用而不是全量加载。这背后的逻辑是上下文是注意力预算你给得越多模型对每一条的关注就越稀释。宁可让命令精确引用一个小文件也不要让它面对一个巨型知识库。4.2 用脚本处理确定性用模型处理理解性这条经验我反复强调。举个具体场景插件要生成一份带编号的清单编号必须连续、不能跳号。如果你让模型自己编号它偶尔会从 1 跳到 3。正确做法是让模型输出内容条目然后用一个脚本统一加编号。判断标准很简单这件事有没有唯一正确答案有就用脚本没有才交给模型。日期格式化、文件重命名、JSON 校验、链接检查这些都属于有唯一答案全部脚本化。4.3 命令的失败模式要提前想好一个健壮的命令必须考虑输入缺失、输入格式错误、依赖文件不存在这三种情况。我通常会在命令正文开头写一段前置检查在执行前请先确认 - 如果用户没有提供材料先询问不要凭空生成 - 如果引用的 context 文件不存在明确告知用户缺哪个文件 - 如果输入格式不符合预期指出问题所在不要强行处理。这段看起来是废话但实测下来能显著减少模型一本正经地胡说八道的情况。明确告诉模型什么时候该停下来问比告诉它要做什么同样重要。4.4 版本管理和团队协作的坑插件一旦多人用就会遇到版本问题。我的建议是每个插件独立版本号改动命令逻辑就升 minor 版本在plugin.json里写清楚changelog或至少写description的变更团队共享的插件放一个独立仓库用 git 管理别放在个人目录里靠拷贝传播。我见过最混乱的情况是三个人各自本地改了同一个命令谁也不知道谁的版本是最新的最后合并时冲突一堆。插件是团队资产就该按团队资产的方式管理。5. 从单个插件到插件组合知识工作的真正威力5.1 组合优于堆砌单个插件解决单点问题但知识工作的价值往往在串联。比如一个完整的内容生产链路可能是/research插件搜集和整理资料输出结构化笔记/outline插件基于笔记生成文章大纲/draft插件按大纲写初稿套用团队写作规范/review插件按检查清单审阅标出问题点。这四个插件各自独立但组合起来就是一条流水线。关键在于它们之间的数据格式要统一——前一个的输出能直接作为后一个的输入。所以我在设计插件时会刻意让输出格式标准化比如都用 markdown、都用固定的标题层级。5.2 什么该做成插件什么不该不是所有东西都值得做成插件。我的判断标准是三条高频一周用不到一次的操作做成插件是浪费有固定套路每次做法都不同的任务插件帮不上忙有明确输入输出输入输出模糊的任务插件反而增加负担。反过来那些每次都要重复交代背景格式要求特别多新人总是做错的任务就是插件的最佳候选。插件的本质是把隐性经验变成显性流程。5.3 插件体系的维护成本这一点很少有人提但很现实插件是有维护成本的。模型能力在变、团队规范在变、业务在变插件如果没人维护半年后就会变成没人敢用的祖传代码。我的做法是给每个插件指定一个 owner并在插件描述里写清楚最后更新时间和负责人。定期比如每季度review 一遍把没人用的插件归档掉。插件数量不是越多越好能持续用起来的才有价值。6. 我在实际使用中总结的几条硬经验先说一条最实在的别一上来就追求大而全的插件体系。我最初的想法是做一个万能知识工作插件把所有命令都塞进去结果维护不动最后拆成了五个小插件反而好用。插件体系的正确演进路径是先解决一个具体痛点跑顺了再扩展。第二条是关于命令命名的。命令名要短、要好记、要有区分度。/w比/weekly-report-generator好用得多但前提是团队里没有别的w开头的命令。我一般会维护一个命令清单新增命令前先看一眼有没有冲突。第三条是关于测试的。插件改完之后一定要用真实场景跑一遍而不是用构造的假数据。假数据往往太干净掩盖了真实输入里的各种脏情况——格式不统一、有错别字、中英文混排。真实数据跑一遍你才知道命令的鲁棒性到底如何。第四条也是我觉得最重要的一条插件的价值不在自动化而在标准化。很多人做插件是为了省事但省事只是副产品。真正的价值是让团队里每个人产出的东西质量一致、格式一致、口径一致。当你发现新人第一周就能产出符合团队标准的文档时这套体系才算真正跑通了。最后分享一个我常用的小技巧给每个插件写一个examples/目录放几个输入-输出的真实样例。这比任何文档都管用因为模型可以直接参考样例人也能一眼看懂这个插件到底干什么。样例要包含正常情况和边界情况两类后者尤其重要——它定义了插件在异常输入下的行为边界。