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 --file=xxx --format=md，适合参数多、可选参数多的情况。 - 自然语言参数：
/cmd 把昨天的日志整理一下，适合参数本身就需要理解的情况。
第三种最灵活但也最不可控。我的经验是：能用前两种就别用第三种。自然语言参数看起来酷，但用户输入千奇百怪，你的提示词很难覆盖所有情况，最后就是各种边界 bug。
3.3 上下文注入的边界
这是整个插件机制里最微妙的部分。命令执行时，Claude Code 会往提示词里注入一些上下文，比如当前目录、最近的文件操作、会话历史片段。但注入多少、注入什么，是有边界的。
我实测发现，会话历史注入通常只覆盖最近若干轮，不是全部。所以如果你的命令依赖很久之前的对话内容，别指望它能自动拿到，得让用户显式提供。
注意：不要假设插件能访问任意文件。文件系统访问通常受工作目录限制，越界访问会直接失败。设计命令时要把这个约束考虑进去。
3.4 提示词模板的写法要点
写提示词模板有几个我总结的要点：
第一，明确输出格式。不要只说"整理一下"，要说"输出 Markdown 表格，三列：问题、原因、方案"。格式越明确，输出越稳定。
第二，给出示例。如果输出格式复杂，在提示词里塞一个示例，效果立竿见影。
第三，留出容错空间。比如"如果内容为空，返回'无内容可处理'"，避免模型自由发挥。
第四，控制长度。提示词不是越长越好，太长了模型反而抓不住重点。我一般控制在 200 字以内，复杂的拆成多个命令。
3.5 命令之间的组合
单个命令能力有限，真正的威力在于组合。我常用的模式是管道式组合：/extract提取内容，/summarize生成摘要，/format排版输出。每个命令只干一件事，串起来完成复杂任务。
这种设计的好处是每个命令都好维护、好测试、好复用。坏处是用户得记住多个命令。折中方案是再写一个"编排命令"，内部依次调用前几个，用户只需要记一个入口。
4. 实操过程：从零搭一个自己的知识工作插件
4.1 环境准备与目录初始化
先把基础环境确认好。你需要一个能跑 Claude Code 的终端环境，Windows、macOS、Linux 都行，我用的是 Ubuntu，Windows 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_ascii=False))然后在命令定义里引用它。具体引用语法各版本略有差异，核心思路是让命令执行时调用脚本，把结果拼进提示词。
提示：脚本一定要处理异常输入。我踩过的坑是脚本遇到空输入直接崩了，导致整个命令失败，用户体验极差。加个 try-except 成本很低，收益很高。
4.4 参数化与用户输入处理
让命令接受参数，才能应对不同场景。比如一个/report命令，支持指定输出格式：
--- description: 生成工作报告，支持 md 和 txt 两种格式 --- 请生成一份工作报告。 输出格式：{{format}} 报告主题：{{topic}} 如果 format 是 md，用 Markdown 标题和列表组织。 如果 format 是 txt，用纯文本加缩进组织。 如果 format 未指定，默认用 md。调用时/report --format=txt --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这个方向我觉得还有很大空间。现在的插件大多还是"单点工具"，未来如果能做到插件之间自动编排、根据上下文智能推荐命令，那才是真正把知识工作的自动化做透了。不过那是后话，眼下先把手上这几个命令打磨好，比什么都实在。
