1. 从零认识 knowledge-work-plugins它到底解决什么问题第一次看到knowledge-work-plugins这个仓库名的时候我下意识以为又是一个把文档塞进向量库然后问答的套壳项目。真正把代码拉下来跑通之后才发现它的定位比我想的要务实得多——这是一套面向Claude Cowork / Claude Code生态的插件集合核心目标是把知识工作里那些高频、重复、有固定套路的动作封装成可以直接用斜杠命令slash commands触发的模块。说白了它想干的事情是你每天在终端里跟 Claude Code 打交道写代码、整理资料、做调研、生成报告很多操作其实是重复的。与其每次重新描述一遍需求不如把这些流程固化成插件用/xxx一条命令唤起。这就是knowledge-work-plugins存在的意义。我把它拆开看大致能分成三层理解最外层是插件清单每个插件是一个独立目录里面有元数据描述、命令定义、可能的辅助脚本。中间层是 slash commands这是用户真正接触的界面输入/之后能看到可用命令列表选中即执行。最内层是知识工作逻辑命令背后封装的是具体的提示词模板、上下文注入规则、以及和本地文件系统的交互方式。适合谁来参考三类人最值得看。第一类是重度使用 Claude Code 的开发者想把自己的工作流沉淀下来第二类是团队里负责工具链建设的人想给同事统一一套命令规范第三类是对插件机制好奇的技术爱好者想搞清楚一个 slash command 从定义到执行到底经历了什么。提示这个仓库的很多设计假设你已经在用 Claude Code 或 Claude Cowork 的 CLI 环境。如果你还没装建议先把基础环境跑起来否则看插件定义会有点悬空。我实测下来最大的感受是它不是一个开箱即用的产品而是一个脚手架式的参考实现。你得根据自己的场景去改、去加、去删。这一点很关键后面讲实操的时候会反复提到。2. 插件机制的整体设计与选型思路2.1 为什么用插件而不是写脚本很多人第一反应是我直接写个 bash 脚本不就行了为什么要搞插件这个问题我一开始也纠结过。后来想明白了两者的差别在于上下文感知能力。普通脚本是哑的它只能按固定参数执行固定逻辑。而插件运行在 Claude Code 的会话上下文里它能拿到当前对话的历史、当前工作目录的状态、甚至你刚才提到的文件。这意味着同一个命令在不同上下文里可以有不同的行为。举个我自己的例子。我有个整理会议纪要的命令如果只是脚本它只能处理我明确传进去的文件。但做成插件之后我可以直接说把刚才讨论的那几个点整理一下它能从会话历史里把相关内容捞出来。这个差别是质的。2.2 目录结构背后的考量一个典型的插件目录大概长这样knowledge-work-plugins/ ├── plugin-a/ │ ├── manifest.json # 插件元数据 │ ├── commands/ # 命令定义 │ │ ├── cmd1.md │ │ └── cmd2.md │ └── scripts/ # 辅助脚本可选 └── plugin-b/ └── ...这个结构不是随便定的。manifest.json负责声明我是谁、我叫什么、我依赖什么命令定义用 Markdown 而不是 JSON是因为提示词本身就是内容用 Markdown 写可读性最好改起来也直观。我踩过一个坑一开始我把命令逻辑写得太复杂塞了一堆条件分支进 Markdown。结果发现维护起来极其痛苦因为 Markdown 不是编程语言你没法调试。后来学乖了复杂逻辑一律下沉到 scripts 里Markdown 只负责描述意图和参数。这个原则我强烈建议你一开始就遵守。2.3 命令命名与发现机制slash command 的命名有个隐性的约定动词开头语义明确。比如/summarize、/extract、/refactor而不是/thing1、/helper。原因很简单当你有几十个命令的时候输入/之后列表会很长好的命名能让你一眼找到。发现机制上Claude Code 会扫描插件目录下的commands/文件夹把每个.md文件注册成一个命令。文件名就是命令名文件内容就是提示词模板。这个设计非常轻量加一个命令就是加一个文件不需要改任何配置。设计选择替代方案为什么选它Markdown 定义命令JSON / YAML提示词可读性优先便于非程序员修改目录即插件单一配置文件隔离性好插件之间互不干扰文件名即命令名显式注册表零配置加文件即生效逻辑下沉脚本全写在提示词里可调试、可测试、可复用2.4 与 Claude Code 生态的耦合点这里要说清楚一个事knowledge-work-plugins不是独立运行的它寄生在 Claude Code 的插件系统之上。所以它的能力边界本质上受限于 Claude Code 暴露了哪些接口。目前我观察到的主要耦合点有三个一是命令注册接口决定插件怎么被加载二是上下文注入接口决定插件能拿到多少会话信息三是文件系统访问权限决定插件能读写哪些路径。这三点里权限那块最容易出问题后面排查章节会细讲。3. 核心细节解析一个命令从定义到执行3.1 命令定义文件的最小结构一个能跑起来的最小命令定义其实就几行--- description: 把选中的内容整理成结构化摘要 --- 请把以下内容整理成摘要要求 1. 提取三个核心观点 2. 每个观点配一句话说明 3. 最后给出一句总结 内容 {{input}}---之间是 frontmatter用来声明命令的元信息最重要的是description它会显示在命令列表里。{{input}}是占位符执行时会被替换成用户传入的内容或者选中的上下文。我建议你每个命令都写清楚 description哪怕你觉得没必要。因为当命令多起来之后你自己都会忘记某个命令是干嘛的。description 就是你的备忘录。3.2 参数传递的几种方式参数传递这块我摸索出三种模式各有适用场景位置参数/cmd arg1 arg2简单直接适合参数少且固定的情况。命名参数/cmd --filexxx --formatmd适合参数多、可选参数多的情况。自然语言参数/cmd 把昨天的日志整理一下适合参数本身就需要理解的情况。第三种最灵活但也最不可控。我的经验是能用前两种就别用第三种。自然语言参数看起来酷但用户输入千奇百怪你的提示词很难覆盖所有情况最后就是各种边界 bug。3.3 上下文注入的边界这是整个插件机制里最微妙的部分。命令执行时Claude Code 会往提示词里注入一些上下文比如当前目录、最近的文件操作、会话历史片段。但注入多少、注入什么是有边界的。我实测发现会话历史注入通常只覆盖最近若干轮不是全部。所以如果你的命令依赖很久之前的对话内容别指望它能自动拿到得让用户显式提供。注意不要假设插件能访问任意文件。文件系统访问通常受工作目录限制越界访问会直接失败。设计命令时要把这个约束考虑进去。3.4 提示词模板的写法要点写提示词模板有几个我总结的要点第一明确输出格式。不要只说整理一下要说输出 Markdown 表格三列问题、原因、方案。格式越明确输出越稳定。第二给出示例。如果输出格式复杂在提示词里塞一个示例效果立竿见影。第三留出容错空间。比如如果内容为空返回无内容可处理避免模型自由发挥。第四控制长度。提示词不是越长越好太长了模型反而抓不住重点。我一般控制在 200 字以内复杂的拆成多个命令。3.5 命令之间的组合单个命令能力有限真正的威力在于组合。我常用的模式是管道式组合/extract提取内容/summarize生成摘要/format排版输出。每个命令只干一件事串起来完成复杂任务。这种设计的好处是每个命令都好维护、好测试、好复用。坏处是用户得记住多个命令。折中方案是再写一个编排命令内部依次调用前几个用户只需要记一个入口。4. 实操过程从零搭一个自己的知识工作插件4.1 环境准备与目录初始化先把基础环境确认好。你需要一个能跑 Claude Code 的终端环境Windows、macOS、Linux 都行我用的是 UbuntuWindows 11 下也测过基本一致。第一步找到 Claude Code 的插件目录。不同版本位置可能不同常见的是用户主目录下的配置文件夹里。你可以先跑一次 Claude Code然后在会话里问它插件目录在哪这是最省事的办法。第二步创建你的插件目录mkdir -p ~/.claude/plugins/my-knowledge-plugin/commands cd ~/.claude/plugins/my-knowledge-plugin第三步写一个最小的manifest.json{ name: my-knowledge-plugin, version: 0.1.0, description: 我的知识工作插件集合 }字段不用多先跑通再说。我见过有人一上来就写一大堆元数据结果一个命令都没跑起来纯属浪费时间。4.2 写第一个可用的 slash command我们来写一个真正有用的命令把一段杂乱笔记整理成待办清单。在commands/下创建todo.md--- description: 把杂乱笔记整理成结构化待办清单 --- 你是一个任务整理助手。请把下面的笔记整理成待办清单。 要求 1. 每条待办以 - [ ] 开头 2. 按优先级排序紧急的在前 3. 如果笔记里有明确的时间标注在条目末尾 4. 如果某条内容无法判断是否为任务单独列在待确认区域 笔记内容 {{input}}保存之后重启 Claude Code 会话输入/应该就能看到todo这个命令了。我实测这个命令在整理会议记录、随手记的灵感时特别好用。原来一堆乱七八糟的文字一条命令下去就变成清晰的清单。4.3 加入脚本处理复杂逻辑有些逻辑提示词搞不定比如统计字数、解析特定格式的文件。这时候就上脚本。在插件目录下建scripts/写一个 Python 脚本#!/usr/bin/env python3 import sys import json def count_stats(text): lines text.split(\n) chars len(text) words len(text.split()) return { lines: len(lines), chars: chars, words: words } if __name__ __main__: text sys.stdin.read() print(json.dumps(count_stats(text), ensure_asciiFalse))然后在命令定义里引用它。具体引用语法各版本略有差异核心思路是让命令执行时调用脚本把结果拼进提示词。提示脚本一定要处理异常输入。我踩过的坑是脚本遇到空输入直接崩了导致整个命令失败用户体验极差。加个 try-except 成本很低收益很高。4.4 参数化与用户输入处理让命令接受参数才能应对不同场景。比如一个/report命令支持指定输出格式--- description: 生成工作报告支持 md 和 txt 两种格式 --- 请生成一份工作报告。 输出格式{{format}} 报告主题{{topic}} 如果 format 是 md用 Markdown 标题和列表组织。 如果 format 是 txt用纯文本加缩进组织。 如果 format 未指定默认用 md。调用时/report --formattxt --topic周报。参数解析由 Claude Code 负责你只需要在提示词里用占位符接住。这里有个细节占位符名字要和参数名一致否则接不到值。我一开始把{{format}}写成{{fmt}}调了半天才发现是名字对不上。4.5 调试与验证方法调试插件最直接的办法是看命令实际展开后的提示词。Claude Code 一般有 verbose 模式或者日志输出打开之后你能看到占位符被替换成了什么。我的调试流程是这样的先用最简单的输入跑一遍确认命令能被识别。再逐步加复杂度每加一点测一次。遇到输出不符合预期先检查提示词展开结果再检查提示词本身。千万别一上来就写一个巨复杂的命令然后指望它一次跑通。分步验证能省你大量时间。调试阶段检查项常见问题命令识别/列表里有没有文件名、目录位置、manifest 格式参数传递占位符是否被替换参数名拼写、传参语法逻辑执行输出是否符合预期提示词描述不清、脚本报错边界处理空输入、超长输入缺少容错、长度限制5. 常见问题与排查技巧实录5.1 命令不显示在列表里这是最高频的问题。我遇到过至少五次原因各不相同目录位置错了插件没放在 Claude Code 扫描的路径下。解决办法是确认插件根目录别自己猜。manifest 格式错误JSON 少个逗号、多个括号都会导致整个插件被跳过。用python -m json.tool manifest.json验证一下。命令文件扩展名不对必须是.md写成.txt不会被识别。需要重启会话有些版本不会热加载加完命令得重开会话。排查顺序建议从外到内先确认目录再确认 manifest最后确认命令文件。5.2 命令执行报权限错误文件系统权限是另一个大坑。插件想读写的文件如果不在允许范围内会直接报错。我的处理原则是插件只操作工作目录内的文件。需要访问外部文件时让用户先复制进来或者显式授权。不要试图绕过权限限制那既不安全也不稳定。如果确实需要访问特定目录看看 Claude Code 有没有配置项可以扩展允许范围。有的话在配置里加没有的话就调整你的方案。5.3 输出格式不稳定同一个命令有时候输出 Markdown 表格有时候输出列表这是提示词不够明确导致的。解决办法有三个层次加格式示例在提示词里直接给一个输出样例效果最明显。加格式约束明确说必须用表格不要用列表。后处理如果模型实在不听话用脚本对输出做一次格式化。我一般先用第一招不行再上第二招第三招是最后手段因为增加了一层处理就多了一个故障点。5.4 命令之间互相干扰插件多了之后可能出现命令名冲突。两个插件都定义了/summarize谁生效就不一定了。避免办法是加前缀。比如kw-summarize、dev-summarize用前缀区分领域。虽然输入麻烦一点但能避免很多诡异问题。5.5 性能问题有些命令跑起来特别慢通常是两个原因一是提示词太长模型处理慢二是脚本里有阻塞操作。提示词优化就是精简把不必要的内容删掉。脚本优化就是检查有没有网络请求、大文件读取这类耗时操作能异步就异步能缓存就缓存。注意不要在一个命令里塞太多任务。我见过有人写一个命令让它同时做提取、翻译、总结、排版结果又慢又不稳定。拆成四个命令串起来用体验好得多。5.6 常见问题速查表现象可能原因快速排查命令不显示目录/manifest/扩展名逐层检查重启会话权限报错越界访问文件限制在工作目录内格式不稳提示词不明确加示例、加约束命令冲突命名重复加领域前缀执行慢提示词长/脚本阻塞精简、异步、缓存参数接不到占位符名不匹配核对参数名拼写6. 进阶玩法把插件用出体系感6.1 按工作场景组织插件当你有十几个命令之后按场景分组会比按功能分组更好用。比如写作场景/outline、/draft、/polish调研场景/collect、/compare、/conclude开发场景/review、/refactor、/test每个场景一组命令用户按场景记忆认知负担小很多。6.2 命令的版本管理插件是要迭代的命令定义改了之后怎么知道哪个版本好用我的做法是在 manifest 里记版本号在命令文件里记变更日志。简单但有效。如果团队协作把插件目录纳入 Git 管理每次改动走 PR这样谁改了什么一目了然。6.3 与团队共享插件团队共享插件最大的障碍不是技术是习惯统一。你写的命令别人不一定用因为不符合他们的习惯。我的经验是先小范围试点找两三个同事一起用收集反馈改几轮之后再推广。一上来就全员推大概率是推不动的。6.4 持续迭代的思路插件体系不是一次设计完的是长出来的。我现在的做法是每次发现自己重复描述同一个需求超过三次就把它做成命令。这样插件库会自然生长每个命令都是真实需求的沉淀不会出现为了做插件而做插件的情况。这个思路我觉得比一开始就规划一个大而全的插件体系要靠谱得多。真实需求驱动比拍脑袋设计强。7. 我踩过的坑和一些实在的建议聊几个具体的坑都是真金白银换来的。第一个坑是过度设计。我一开始想做一个万能知识工作插件把所有能想到的功能都塞进去。结果做了两周一个能用的命令都没有。后来砍到只做三个最常用的一天就跑通了。先做减法再做加法这个顺序不能反。第二个坑是忽视错误处理。插件跑在真实环境里输入什么都有可能。空输入、超长输入、特殊字符、编码问题每一个都能让你的命令崩掉。我现在写任何命令第一件事就是想如果输入是空的会怎样。第三个坑是不写文档。命令多了之后我自己都忘了某个命令的参数是什么。后来强制自己每个命令都写 description 和示例情况才好起来。文档不是给别人看的首先是给自己看的。第四个坑是忽略用户反馈。插件好不好用用户说了算。我早期做的几个命令自己觉得设计得很优雅结果同事根本不用因为不符合他们的操作习惯。后来我改成先问需求再做命中率高多了。最后分享一个我一直在用的小技巧给每个命令配一个最小可用示例。就是在命令定义的最后附上一行调用示例。这样无论是自己还是别人看到命令就知道怎么用不用去翻文档。这个习惯帮我省了很多解释的时间。knowledge-work-plugins这个方向我觉得还有很大空间。现在的插件大多还是单点工具未来如果能做到插件之间自动编排、根据上下文智能推荐命令那才是真正把知识工作的自动化做透了。不过那是后话眼下先把手上这几个命令打磨好比什么都实在。