1. 从零认识 knowledge-work-plugins它到底解决什么问题第一次看到knowledge-work-plugins这个仓库名很多人会下意识以为它又是一个“插件市场”或者“插件合集”。但真正翻过它的目录结构、跑过几个 slash commands 之后你会发现它的定位要具体得多——它是一套面向知识工作场景的插件模板与参考实现专门用来给 Claude Code / Claude Cowork 这类命令行智能体扩展“可复用的工作流能力”。说白了Claude Code 本身是一个能力很强的通用智能体它能读文件、跑命令、改代码。但通用就意味着“什么都能干但什么都不专”。你每次让它帮你整理会议纪要、生成周报、做竞品调研都得重新描述一遍需求、重新约定输出格式。knowledge-work-plugins要解决的就是这个重复劳动问题把高频的知识工作流程固化成插件用 slash command 一键触发让智能体按照你预设的模板、步骤和输出规范去执行。这个仓库适合三类人看。第一类是日常用 Claude Code 处理非纯编码任务的知识工作者比如产品经理、运营、研究员、技术写作者你们的需求是“让 AI 按我的规矩干活”。第二类是想给自己团队做内部工具链的开发者你们需要一套可参考的插件骨架而不是从零设计目录结构和命令注册机制。第三类是对智能体扩展机制好奇的技术爱好者想搞清楚 slash command、plugin manifest、skill 这些东西到底怎么串起来。我自己的使用场景很典型每周要产出竞品动态简报、每月要整理项目复盘、时不时要处理一批格式混乱的原始素材。以前这些活儿要么手动做要么每次写一大段 prompt 让 Claude 现做输出质量忽高忽低。用了插件化思路之后同样的任务触发词固定、执行步骤固定、输出结构固定稳定性提升非常明显。下面我就把这套东西拆开讲透从设计思路到落地实操再到踩过的坑尽量让你看完就能自己动手做一个。2. 插件化设计的核心思路与方案选型2.1 为什么是“插件”而不是“更长的 prompt”很多人第一反应是我直接把要求写进CLAUDE.md或者系统提示词里不就行了为什么要搞插件这么重这个问题我认真对比过结论是两者解决的不是同一个层次的问题。写进CLAUDE.md的东西是全局常驻的它对所有会话生效。这带来两个麻烦一是上下文污染你为一个特定任务写的详细规范会占用每一次对话的 token哪怕这次根本用不到二是维护困难当你有十几个不同任务时CLAUDE.md会膨胀到没人愿意读。插件的思路是按需加载、按名触发。每个插件是一个独立目录里面有自己的命令定义、提示词模板、辅助脚本和资源文件。只有当用户输入对应的 slash command 时这套东西才会被激活。这就像操作系统里的“服务”和“常驻进程”的区别——不是所有功能都要一直开着。提示判断一个需求该不该做成插件我的标准是“这个任务我一个月内会重复做三次以上且每次的输出结构基本一致”。满足就值得插件化不满足就临时写 prompt 更划算。2.2 目录结构背后的设计哲学一个典型的 knowledge-work 插件目录大概长这样plugins/ weekly-report/ plugin.json # 插件元信息与命令注册 commands/ generate.md # slash command 定义 templates/ report.md # 输出模板 scripts/ collect.py # 辅助数据收集脚本 README.md这个结构不是随便定的每一层都有明确职责。plugin.json是入口声明这个插件叫什么、暴露哪些命令、依赖什么。commands/目录下每个 markdown 文件对应一个 slash command文件名就是命令名。templates/存放输出模板让智能体知道最终产物长什么样。scripts/放可选的辅助脚本处理那些“用自然语言描述不如直接跑代码”的环节。我特别想强调templates/这一层的价值。早期我做插件时把输出格式写在命令描述里结果智能体每次理解都有细微偏差。后来改成给一个真实的模板文件让它“照着填”输出一致性立刻上了一个台阶。这背后的原理是示例比描述更精确。你描述“用三级标题”它可能理解成###也可能理解成加粗你给一个真实模板它就没有歧义了。2.3 slash command 与 skill 的分工热词里频繁出现claude code skills和slash commands这两个概念容易混。我的理解是slash command 是用户主动触发的入口skill 是智能体可以自主调用的能力。slash command 是显式的你敲/weekly-report它就跑。skill 更像是给智能体装备的“工具箱”它在执行任务过程中判断需要某个能力时自己去调用。在 knowledge-work-plugins 的语境下大部分场景用 slash command 就够了因为知识工作往往是“人发起、AI 执行”的模式不需要 AI 自己决定要不要做周报。但有些复杂插件会两者结合。比如一个“竞品调研”插件用户敲/competitor-scan触发执行过程中智能体发现需要抓取网页就自主调用一个 web-fetch skill。这种组合让插件既有明确的触发点又有灵活的中间能力。2.4 方案选型自建 vs 复用现有插件动手之前先想清楚你是要自己写一个全新插件还是改造现有的我的建议是先抄再改。knowledge-work-plugins 仓库里已经有不少可直接用的参考实现你完全可以 clone 下来挑一个结构最接近你需求的改命令名、改模板、改脚本比从空目录开始快得多。判断标准很简单如果你的任务和现有插件有 60% 以上的流程重合就改造低于 40%就新建。改造的风险是容易残留无关逻辑新建的成本是要处理所有样板代码。我一般倾向于改造因为样板代码plugin.json 格式、命令注册方式才是最容易出错的部分流程逻辑反而是最好写的。3. 核心细节解析与实操要点3.1 plugin.json 的字段含义与常见坑plugin.json是整个插件的身份证字段不多但每个都关键。一个最小可用的配置大概是这样{ name: weekly-report, version: 1.0.0, description: 生成结构化周报, commands: [ { name: weekly-report, description: 根据本周记录生成周报, file: commands/generate.md } ] }这里最容易踩的坑是name字段。它必须和目录名、命令触发名保持一致的命名规范通常用 kebab-case短横线连接。我有一次用了下划线结果命令注册成功但触发时找不到排查了半天。另一个坑是version字段虽然看起来无关紧要但如果你后续要做插件更新和兼容性管理从一开始就规范写版本号能省很多事。description字段也值得认真写。它不只是给人看的智能体在某些场景下会读取它来判断插件用途。写得含糊可能导致智能体在需要时想不起来调用这个插件。3.2 命令定义文件怎么写才有效commands/generate.md这类文件是 slash command 的灵魂。它不是普通的说明文档而是给智能体看的执行指令。我总结了一个有效的命令定义应该包含四个部分第一部分是触发条件说明告诉智能体这个命令在什么情况下被使用。第二部分是执行步骤用有序列表列出每一步做什么。第三部分是输入约定说明用户可能提供哪些参数、参数缺失时怎么处理。第四部分是输出要求指向模板文件或直接描述格式。一个反面教材是我早期写的命令定义只有一句“帮我生成周报”。结果智能体每次执行都自由发挥有时列点有时写段落完全不可控。后来我改成明确的步骤先读取本周的日志文件再按模板填充最后检查是否有遗漏项。输出立刻稳定了。注意命令定义里不要写“尽量”“可以”这类模糊词。智能体对模糊指令的处理是概率性的你要的是确定性就得用“必须”“先……再……”这种强约束表达。3.3 模板文件的设计技巧模板文件决定了最终产物的“长相”。我的经验是模板要足够具体但留出填充位。太抽象智能体不知道填什么太死板又失去了灵活性。一个好的模板会明确标注哪些是固定结构、哪些是动态内容。比如## 本周完成 {{completed_items}} ## 下周计划 {{next_week_plan}} ## 风险与阻塞 {{risks}}用{{}}占位符是个好习惯它让智能体和人类都能一眼看出哪里需要替换。有些团队喜欢用 HTML 注释标注也行但占位符更直观。模板的另一个技巧是内置示例。在模板文件里放一段填好的样例智能体照着样例的风格去填输出质量会明显提升。这就像给学生一份范文比只给题目要求效果好得多。3.4 辅助脚本的边界在哪里scripts/目录里的脚本是可选增强项。什么时候该用脚本我的判断标准是当某个步骤用自然语言描述会很长、很啰嗦或者需要精确计算时就写成脚本。比如“统计本周 git commit 数量并按作者分组”用自然语言描述智能体也能做但每次都要跑一堆命令、解析输出慢且不稳定。写成一个 Python 脚本智能体直接调用几秒钟出结果。反过来“把结果整理成易读的段落”这种主观性强的活儿就交给智能体不要试图用脚本硬编码。脚本的接口设计也有讲究。我习惯让脚本接收明确的参数、输出结构化的 JSON而不是直接输出给人看的文本。这样智能体拿到 JSON 后可以灵活决定怎么呈现脚本和展示逻辑解耦。4. 实操过程与核心环节实现4.1 环境准备与插件目录初始化动手之前先把环境理清楚。你需要一个能跑 Claude Code 的终端环境以及一个用来存放插件的目录。我习惯在项目根目录下建一个plugins/文件夹所有自建插件都放里面方便统一管理。初始化一个插件目录我一般用脚本一把梭mkdir -p plugins/my-plugin/{commands,templates,scripts} touch plugins/my-plugin/plugin.json touch plugins/my-plugin/commands/main.md touch plugins/my-plugin/README.md目录建好后先写plugin.json把插件名、版本、命令列表填上。这一步不要偷懒字段填全后面调试会省心很多。我见过有人先写命令再补 manifest结果命令名和注册名对不上触发不了。4.2 编写第一个可用的 slash command假设我们要做一个“会议纪要整理”插件。命令定义文件commands/summarize.md我会这样写# 会议纪要整理命令 ## 触发场景 用户提供一段会议原始记录需要整理成结构化纪要时使用。 ## 执行步骤 1. 读取用户提供的原始记录文件或粘贴内容 2. 识别会议主题、参会人、时间 3. 提取讨论要点按主题归类 4. 提取明确的行动项标注负责人和截止时间 5. 按 templates/meeting.md 模板输出 ## 输入约定 - 如果用户提供了文件路径读取该文件 - 如果用户直接粘贴内容直接处理 - 如果内容为空提示用户提供记录 ## 输出要求 严格按 templates/meeting.md 的结构输出不要增删章节。这份定义的关键在于步骤明确、边界清晰。智能体拿到它基本不会跑偏。4.3 模板与命令的配合调试写完命令和模板别急着正式用先做几轮测试。我的调试流程是准备三份不同类型的输入一份结构清晰的、一份混乱的、一份信息不全的分别触发命令看输出是否符合预期。第一次跑大概率会有问题。常见的是模板占位符没被正确替换或者智能体自作主张加了额外章节。这时候不要改命令描述先检查模板是不是有歧义。我遇到过一次模板里写“## 行动项”智能体理解成“行动项”是个可选章节信息不全时就省略了。后来改成“## 行动项必须输出无内容时写‘无’”问题解决。调试时还有个技巧让智能体在输出末尾附上它的执行日志说明它读了哪些文件、做了哪些判断。这样出问题时你能快速定位是哪一步理解错了。4.4 参数传递与动态内容处理有些命令需要接收参数比如/weekly-report --week2024-W20。参数处理在命令定义里要写清楚。我的做法是在命令定义开头加一段参数解析说明## 参数 - week: 可选指定周次格式 YYYY-Www。缺省时使用当前周。 - format: 可选输出格式可选值 markdown/text。缺省 markdown。然后在执行步骤里引用这些参数。智能体会根据用户输入自动填充。这里要注意参数名要和用户实际输入的对齐别定义成weekNum结果用户敲的是--week。动态内容处理是另一个重点。如果插件需要读取外部数据比如从某个 API 拉取我倾向于写成脚本让命令定义里只写“调用 scripts/fetch.py 获取数据”而不是让智能体自己去发请求。这样更可控也更容易调试。4.5 插件的注册与生效验证插件写完后需要让 Claude Code 知道它的存在。具体注册方式取决于你的运行环境通常是在配置里指向插件目录或者把插件放到约定的扫描路径下。注册后重启会话敲/看命令列表里有没有你的插件。验证时我习惯做一个“冒烟测试”用最简单的输入触发一次确认命令能被识别、能跑通、能输出。冒烟测试过了再上真实数据。如果命令列表里看不到先检查plugin.json的 JSON 格式是否合法用jq校验一下再检查命令文件名和注册名是否一致。5. 常见问题与排查技巧实录5.1 命令触发不了怎么办这是最高频的问题。排查顺序我总结成一张表现象可能原因排查方法命令列表里没有plugin.json 格式错误用 jq 校验 JSON命令列表里有但敲了没反应命令名与文件名不一致对比 manifest 和实际文件名敲了有反应但报错命令定义文件路径错误检查 file 字段指向敲了执行但输出为空模板文件缺失或路径错检查模板引用路径我踩过最坑的一次是plugin.json里多了一个逗号JSON 解析失败但没有任何报错提示命令就是静默不出现。后来养成习惯每次改完 manifest 都跑一遍jq . plugin.json确认格式合法。5.2 输出格式不稳定的排查思路输出忽好忽坏通常不是智能体的问题而是你的指令有歧义。排查方法是把命令定义和模板文件当成“给一个新员工的说明书”让一个不了解背景的人读一遍看他能不能准确复现你要的格式。如果他读完还有疑问智能体也会有。常见的歧义来源有三个一是章节是否必须输出没写清二是列表和段落的选用没约定三是数字、日期格式没统一。我的做法是在模板里把所有格式细节都固定下来比如日期统一YYYY-MM-DD列表统一用-必须输出的空章节写“无”。5.3 插件之间冲突与优先级当你装了多个插件可能会出现命令名冲突或者行为干扰。我的经验是给命令名加前缀比如kw-weekly-report、kw-meeting-summary用kw表示 knowledge work 系列。这样既避免冲突又方便归类。如果两个插件都要读取同一份配置或数据要注意加载顺序。我一般把公共依赖抽成一个独立的“基础插件”其他插件声明依赖它。这样职责清晰也避免重复定义。5.4 性能与上下文占用的优化插件多了之后会话启动可能变慢或者上下文被占满。优化方向有两个一是精简命令定义去掉冗余描述只留必要指令二是把大段静态内容比如长模板放到文件里按需读取而不是塞进命令定义。我实测下来一个命令定义控制在 500 字以内比较合适超过这个长度就要考虑拆分或外置。模板文件可以长但只在触发时才读取不影响日常会话。5.5 版本管理与团队协作插件是要迭代的版本管理不能马虎。我的做法是每个插件独立版本号改动记录写在插件自己的CHANGELOG.md里。团队协作时插件目录纳入 git 管理但要注意把个人配置和敏感信息排除在外。如果多人共用一套插件建议约定一个 review 流程新增命令或修改模板要经过至少一人确认避免有人改坏了影响所有人。这个流程听起来重但比事后排查“为什么昨天还好好的今天就不对了”要省事得多。6. 从单插件到插件体系的演进思路6.1 什么时候该拆分插件一开始我什么都往一个插件里塞结果命令越来越多模板越来越杂维护成本飙升。后来我总结出一个拆分信号当两个命令的输入输出几乎没有交集时就该拆成两个插件。比如“周报生成”和“会议纪要”虽然都是文档处理但输入源、处理逻辑、输出结构完全不同放一起只会互相干扰。拆开后各自独立演进反而更清爽。6.2 公共能力的抽取与复用拆分之后会出现重复代码这时候就要抽公共层。常见的公共能力包括文件读取、日期处理、格式校验、模板渲染。我把这些抽成一个common插件或共享脚本库其他插件引用它。抽取的时机很重要。太早抽你还没看清哪些是真公共的容易抽错太晚抽重复代码已经到处都是改起来痛苦。我的经验是第三次重复时抽取——同样的逻辑写第三遍时就该动手了。6.3 插件体系的文档化插件多了之后最大的问题不是写而是“忘了自己写过什么”。我强制自己给每个插件写 README内容包括这个插件解决什么问题、有哪些命令、每个命令怎么用、依赖什么。然后在总目录放一个索引文件列出所有插件和一句话说明。这份文档的价值在几个月后体现得淋漓尽致。当你需要某个功能时翻一眼索引就知道有没有现成的不用重新造轮子。6.4 持续迭代的节奏把控插件不是写完就完事的。我的节奏是新插件先跑两周收集使用中的问题两周后做一次集中优化把高频问题修掉之后进入低频维护只在遇到具体问题时改。不要频繁改插件。每次改动都可能引入新问题而且频繁变更会让使用者无所适从。稳定比先进更重要尤其是团队共用的插件。7. 我个人的实操心得与几个关键提醒做了一段时间 knowledge-work-plugins最大的体会是插件的价值不在于技术多复杂而在于把“隐性经验”变成“显性流程”。你脑子里那套“周报该怎么写”的直觉通过插件固化下来就变成了团队可复用的资产。这个过程本身就是在做知识管理。几个具体的提醒。第一先手动跑通再插件化。如果你自己都没手动做过这个任务三遍以上别急着写插件你还没摸清流程里的坑。第二模板比指令重要。花在打磨模板上的时间回报远高于打磨命令描述。第三留好调试出口。命令定义里加一句“执行完成后附上简要执行说明”出问题时能省大量排查时间。还有一个容易被忽视的点插件的命名要面向未来。别用“临时”“测试”这种词一旦用起来就很难改。我见过一个团队把核心插件命名成test-plugin结果半年后全公司都在用这个名字改也不是不改也不是。最后分享一个小技巧。如果你不确定某个流程该不该插件化先用一个 markdown 文件把流程写下来手动执行几次。如果每次执行你都要翻这个文件说明它值得插件化如果你已经背下来了说明它已经内化成你的习惯插件化的收益就没那么大。这个判断方法帮我省了不少无用功。这套东西后续还能往几个方向扩展。一是接入更多数据源让插件能自动拉取信息而不是等用户提供二是做插件之间的编排让一个命令触发一串插件按顺序执行三是把插件配置外置让不同人用同一插件但走不同参数。这些我都还在摸索有新的体会再分享。
