★ FEATURED ARTICLE 1. 从零认识 knowledge-work-plugins它到底解决什么问题第一次看到knowledge-work-plugins这个仓库名的时候我下意识以为又是一个把常用提示词打包成模板的合集。真正翻完代码结构、跑通几个插件之后才发现它的定位比提示词模板要重得多——这是一套面向 Claude Cowork 与 Claude Code 的插件化能力扩展框架核心目标是把知识工作里那些高频、重复、有固定套路的任务封装成可复用、可组合、可版本管理的插件单元。说白了它想干的事情是让 AI 助手不再只是一个你问一句它答一句的对话框而是能像 IDE 装插件一样按需加载一整套工作流能力。你在 Claude Code 里敲一个 slash command背后触发的可能是一整套文件扫描、结构化提取、格式化输出的流水线而不是一段孤立的提示词。这个项目适合谁我梳理了三类人重度使用 Claude Code 的开发者每天在终端里跟 AI 协作写代码、改配置、做重构希望把重复操作固化成命令的人。知识工作者做研究、写报告、整理资料、做竞品分析需要 AI 按固定框架输出结构化内容的人。想自建 AI 工作流的团队希望把内部规范、模板、检查清单沉淀成插件让团队成员共享同一套AI 操作手册的人。它解决的问题很具体。以前我们用 Claude Code每次都要重新描述需求帮我按这个格式整理记得先检查这几个文件输出要用这个模板。这些上下文每次都要重复输入既费 token 又容易漏。knowledge-work-plugins把这些约定固化进插件一次配置长期复用。这就是它最核心的价值——把隐性的工作约定变成显性的、可执行的插件资产。我实测下来一个配置得当的插件能把原本需要五六轮对话才能完成的任务压缩到一条 slash command。这个效率提升不是线性的是数量级的。2. 插件机制的核心设计与选型逻辑2.1 为什么是插件而不是提示词库很多人第一反应是我搞一个提示词库不就行了把好用的 prompt 存起来用的时候复制粘贴。这个思路在小规模场景下没问题但一旦任务变复杂就会崩。提示词库的本质是文本片段它没有结构、没有依赖、没有执行逻辑。而插件不一样一个插件通常包含几个部分元数据描述这个插件干什么、什么时候触发、指令主体具体的 prompt 或工作流定义、资源文件模板、示例、参考数据、可选的脚本或工具调用。这四样东西组合起来才构成一个完整的能力单元。我举个具体对比。假设你要做一个周报生成任务维度提示词库方案插件方案触发方式手动复制粘贴slash command 一键触发上下文每次都要重新描述元数据自动注入模板管理散落在各处插件内统一管理版本控制靠文件名区分靠插件版本号团队共享靠口口相传靠仓库分发可组合性基本没有插件可互相调用这个对比很能说明问题。插件机制的本质是把提示词升级成了软件模块。它借鉴的是传统 IDE 插件系统的思路——VS Code 的插件能注册命令、能读文件、能调 APIknowledge-work-plugins里的插件同理只不过它的运行时是 Claude。2.2 Claude Cowork 与 Claude Code 的双端适配这个项目一个很聪明的设计是同时适配两个端Claude Cowork 和 Claude Code。Claude Code 是终端里的 CLI 工具面向开发者强调命令行交互、文件系统操作、代码理解。Claude Cowork 更偏向协作场景强调多人共享、任务编排。同一个插件框架要同时服务这两个端就必须做抽象层。我的理解是插件定义本身是端无关的——它描述的是做什么而不是在哪做。至于怎么触发怎么渲染结果交给各端的适配层处理。这种设计的好处是你写一次插件两个端都能用。坏处是某些端特有的能力比如 Code 端的文件写入在 Cowork 端可能用不了需要做能力检测。实际配置的时候我建议先明确你的主战场是哪个端。如果你主要在终端里干活就重点研究 Code 端的加载机制如果你更多是在协作场景里用就关注 Cowork 端的插件注册方式。两边都想要那就把插件写得尽量纯——只依赖最基础的指令能力不碰端特有的 API。2.3 slash commands 作为统一入口slash commands是这个项目里我最喜欢的设计。它把插件的触发方式统一成了/开头的命令跟 Slack、Discord 那套交互习惯一致学习成本极低。为什么用 slash command 而不是自然语言触发我踩过的坑告诉我自然语言触发看着美好实际很不稳定。你说帮我整理一下资料AI 可能触发整理插件也可能直接开始瞎聊。而/organize这种命令是确定性的敲下去就执行没有歧义。从工程角度看slash command 还带来几个好处可发现性敲/能列出所有可用命令、可组合性命令可以带参数、可脚本化命令可以被其他流程调用。这三点加起来就让插件系统从玩具变成了工具。我自己的习惯是把最常用的三五个插件绑定成短命令比如/rw代表周报、/cr代表代码审查、/sum代表摘要。敲起来快记得住。3. 插件目录结构与核心文件解析3.1 一个标准插件的骨架长什么样我拆过好几个插件结构大同小异。一个典型的插件目录大概是这样my-plugin/ ├── plugin.json # 插件元数据 ├── commands/ # slash command 定义 │ └── main.md ├── prompts/ # 指令主体 │ └── system.md ├── resources/ # 模板、示例、参考数据 │ ├── template.md │ └── examples/ └── README.md # 使用说明这个结构不是强制的但遵循它能让你的插件更容易被别人理解和复用。我强烈建议新手从这个骨架开始别一上来就搞花活。plugin.json是入口里面定义了插件名、版本、描述、作者、依赖、命令列表。这个文件相当于插件的身份证Claude 加载插件时第一件事就是读它。字段填得越清楚AI 越容易判断什么时候该用这个插件。commands/目录下每个.md文件对应一个 slash command。文件名就是命令名比如main.md对应/main。文件内容分两部分frontmatterYAML 格式的元数据和正文具体的指令。prompts/放的是可复用的指令片段。为什么要单独拆出来因为一个插件可能有多个命令它们共享一部分指令。拆出来之后改一处所有命令都生效避免重复维护。resources/是资源目录模板、示例、参考数据都放这。我见过有人把整个知识库塞进 resources结果插件加载慢得要死。我的建议是只放真正会被指令引用的资源大文件用外部链接。3.2 plugin.json 的关键字段与填写技巧plugin.json里几个字段值得单独说name插件唯一标识建议用 kebab-case别用中文和空格。version语义化版本改指令就升 minor改结构就升 major。description这是给 AI 看的不是给人看的。要写清楚这个插件在什么场景下用而不是这个插件很厉害。triggers触发关键词列表帮助 AI 判断何时激活。commands命令清单每个命令要有 name 和 description。我踩过的一个坑是 description 写得太泛。比如写帮助整理文档AI 根本不知道什么时候该用。改成当用户需要把散乱的会议记录整理成结构化纪要时使用命中率立刻上去了。description 的写法直接决定插件的触发准确率这一点怎么强调都不过分。还有一个细节version 字段别偷懒一直写 1.0.0。我见过一个插件改了十几版还是 1.0.0结果团队里有人用旧版有人用新版行为不一致排查了半天。版本号是协作的基础设施认真对待。3.3 commands 文件的 frontmatter 写法command 文件的 frontmatter 支持这些字段--- description: 生成结构化周报 arguments: - name: period description: 统计周期如 本周 上周 required: false default: 本周 allowed-tools: - Read - Write ---allowed-tools这个字段很关键。它限制了这条命令能调用哪些工具。为什么要限制因为安全。一个只读的摘要命令不应该有写文件的权限。最小权限原则在这里同样适用。arguments定义了命令参数支持默认值。这让命令从死命令变成了活命令。比如/report 上周和/report 本月走的是同一套逻辑只是参数不同。我实测下来参数设计要克制。一个命令超过三个参数用户就记不住了。宁可拆成多个命令也别搞一个参数巨多的万能命令。4. 从零写一个插件的完整实操4.1 环境准备与目录初始化动手之前先把环境理清楚。你需要一个可用的 Claude Code 或 Claude Cowork 环境插件存放目录通常在用户配置目录下的 plugins 文件夹一个趁手的编辑器我建议先在本地建一个独立的开发目录写完测试通过再放到正式插件目录。这样避免半成品污染正式环境。mkdir -p ~/plugin-dev/my-first-plugin/{commands,prompts,resources} cd ~/plugin-dev/my-first-plugin目录建好之后先写plugin.json。我习惯从最小可用版本开始字段先填必需的跑通之后再补全。{ name: my-first-plugin, version: 0.1.0, description: 当用户需要把零散笔记整理成结构化文档时使用, commands: [ { name: organize, description: 整理笔记为结构化文档 } ] }这个最小版本已经能跑了。别小看它很多人卡在想一次写完美结果一直没动手。先跑通再迭代。4.2 编写第一个 slash command在commands/organize.md里写命令定义--- description: 把零散笔记整理成结构化文档 arguments: - name: input description: 待整理的笔记内容或文件路径 required: true allowed-tools: - Read - Write --- 你是一个文档整理助手。请把用户提供的零散笔记整理成结构化文档。 整理规则 1. 先通读全部内容识别主题 2. 按主题分组每组一个小标题 3. 每组内部按逻辑顺序排列要点 4. 保留原始信息不要自行添加未提及的内容 5. 输出使用 Markdown 格式 如果用户提供的是文件路径先用 Read 工具读取内容。 整理完成后用 Write 工具保存到同目录下的 organized-{原文件名}。这个命令虽然简单但包含了几个关键要素明确的角色设定、清晰的规则、工具使用说明、输出格式约定。这四样齐了命令的稳定性就有保障。我特别想强调第 4 条规则保留原始信息不要自行添加。这是知识工作类插件的通用铁律。AI 很爱帮忙补充但在整理场景下补充就是污染。宁可输出干瘪也不要输出失真。4.3 参数传递与上下文注入参数传递是很多人卡住的地方。arguments里定义的参数在指令正文里怎么引用常见做法是用占位符比如{{input}}。但不同版本的 Claude Code 对占位符的支持不完全一致。我实测下来最稳的方式是在指令里用自然语言描述参数让 AI 自己从用户输入里提取。比如上面那个命令用户敲/organize 我的会议记录.mdAI 会自动把我的会议记录.md识别为 input 参数。这种软参数方式兼容性最好代价是偶尔会识别错。如果你追求确定性可以用显式占位符但要先确认你的 Claude Code 版本支持。我一般建议新手先用软参数跑通之后再考虑优化。上下文注入是另一个重点。插件运行时Claude 会自动把plugin.json的 description、command 的 description、以及当前对话历史一起注入。这意味着你的指令不需要重复描述背景AI 已经知道了。指令正文应该聚焦在怎么做而不是做什么。4.4 本地测试与调试方法写完插件怎么测我的流程是三步第一步语法检查。plugin.json用 JSON 校验工具过一遍command 文件的 frontmatter 用 YAML 校验工具过一遍。这一步能挡掉 80% 的低级错误。第二步加载测试。把插件放到插件目录重启 Claude Code敲/看命令有没有出现在列表里。没出现就是加载失败去看日志。第三步功能测试。用几个典型输入跑一遍看输出是否符合预期。我一般准备三个测试用例正常输入、边界输入超长或超短、异常输入格式不对。调试的时候最有用的一招是在指令里临时加一句先输出你的理解再执行。这样你能看到 AI 是怎么理解任务的定位问题特别快。测完记得删掉这句不然正式用的时候会多输出一段废话。5. 插件组合与工作流编排5.1 插件之间的调用关系单个插件能力有限真正的威力在于组合。knowledge-work-plugins支持插件之间互相调用这是它区别于普通提示词库的关键。组合方式有两种串行和并行。串行就是 A 的输出作为 B 的输入比如先摘要再翻译。并行就是 A 和 B 同时跑最后合并结果比如同时做竞品分析和用户调研。我做过一个串行工作流/extract提取文档要点 →/structure结构化整理 →/format套用模板输出。三个插件各司其职组合起来就是一条完整的文档处理流水线。每个插件单独看都很简单组合起来能力就很强。这里有个设计原则插件应该尽量无状态。也就是说插件不应该依赖上一次运行的结果。状态应该由调用方管理而不是插件自己记。这样插件才能被自由组合不会互相干扰。5.2 用 slash command 串起完整工作流串行工作流怎么落地最直接的方式是写一个编排命令在里面依次调用其他命令。--- description: 完整的文档处理流水线 allowed-tools: - Read - Write --- 按以下步骤处理用户提供的文档 1. 调用 /extract 提取核心要点 2. 把提取结果传给 /structure 做结构化整理 3. 把整理结果传给 /format 套用标准模板 4. 输出最终结果 每一步完成后简要说明这一步做了什么再进入下一步。这个编排命令本身不干活它只负责调度。这种调度与执行分离的设计让工作流很容易调整。想加一步就加一步想换顺序就换顺序不用改底层插件。我实测下来编排命令的步骤别超过五步。超过五步AI 容易在中途忘记前面的步骤或者把步骤顺序搞乱。如果确实需要更多步骤就拆成多个编排命令分阶段执行。5.3 参数在插件间的传递技巧参数传递是组合工作流里最容易出问题的地方。A 插件的输出格式B 插件不一定能直接吃。我的经验是在插件之间约定统一的数据格式。最通用的是 Markdown因为 AI 对 Markdown 的理解最稳。如果 A 输出的是 JSONB 可能解析不了但如果 A 输出的是 Markdown 列表B 基本都能处理。另一个技巧是显式声明输入输出格式。在每个插件的 description 里写清楚输入格式和输出格式编排的时候就能一眼看出能不能接上。这跟函数签名是一个道理接口清晰组合才顺。如果两个插件格式对不上中间加一个转换插件。别硬凑硬凑的结果就是输出质量断崖式下跌。6. 常见问题与排查技巧实录6.1 插件加载失败的排查路径插件加载失败是最常见的问题症状是敲/看不到命令。排查路径我整理成了一张表症状可能原因排查方法命令完全不出现plugin.json 格式错误用 JSON 校验工具检查部分命令不出现某个 command 文件 frontmatter 错误逐个检查 YAML命令出现但执行报错指令正文有语法问题看错误日志定位行号命令执行但结果不对description 写得太泛重写 description加载慢resources 目录太大精简资源文件我踩过最坑的一次是 plugin.json 里多了一个逗号JSON 解析失败但错误提示很隐晦找了半小时。从那以后我养成了习惯改完 plugin.json 立刻用校验工具过一遍别等加载失败再回头找。还有一个隐蔽的坑是文件编码。Windows 下编辑的文件可能是 GBK 编码Claude 读的时候会乱码。统一用 UTF-8这个没得商量。6.2 命令触发不准确的调优方法命令触发不准确表现为该触发的时候不触发不该触发的时候乱触发。这是 description 的问题。调优方法我总结了三步第一步看日志。Claude Code 通常会记录命令匹配的过程看它为什么没选中你的命令。第二步改 description。把泛泛的描述改成具体的场景描述。比如整理文档改成当用户提供会议记录、访谈笔记、零散想法需要整理成结构化文档时使用。第三步加 triggers。在 plugin.json 里加触发关键词帮助 AI 匹配。关键词要选那些用户真的会说的词别选你自己造的词。我实测下来description 里包含当……时使用这个句式触发准确率明显更高。因为这句话直接告诉 AI 使用场景比形容词管用得多。6.3 输出质量不稳定的应对策略同样的命令有时候输出很好有时候一塌糊涂。这种不稳定是 AI 应用的固有特性但可以通过一些手段缓解。手段一加约束。在指令里明确不要做什么比要做什么更有效。比如不要添加原文没有的信息不要改变原文的语气。手段二给示例。在 resources 里放一两个输入输出示例指令里引用它们。AI 看到具体例子输出会稳定很多。手段三分步执行。把一个大任务拆成几个小步骤每步单独输出。步骤越小AI 越不容易跑偏。手段四加自检。在指令最后加一句输出前检查是否满足以下条件……。让 AI 自己过一遍检查清单能挡掉不少低级错误。我用这四招组合下来输出稳定性提升很明显。尤其是给示例这一招效果立竿见影。一个具体的例子胜过十句抽象的描述。6.4 权限与安全配置要点插件能调工具就意味着有权限风险。一个配置不当的插件可能删掉你的文件或者把敏感内容发到不该发的地方。我的安全配置原则有三条最小权限。每个命令的allowed-tools只列真正需要的工具。只读的命令绝不给 Write 权限。敏感操作二次确认。涉及删除、覆盖、发送的操作在指令里加一句执行前先向用户确认。敏感信息过滤。如果插件会处理可能含敏感信息的文档在指令里加过滤规则比如输出时忽略所有邮箱地址和电话号码。提示插件开发阶段建议先在测试目录里跑别直接对着正式文件操作。我见过有人测试删除命令结果把工作目录清空了血的教训。7. 插件工程化的进阶实践7.1 版本管理与团队协作插件一旦进入团队使用版本管理就成了刚需。我的做法是每个插件独立版本号遵循语义化版本用 Git 管理插件仓库每次改动写清楚 commit message重大改动前打 tag方便回滚在 README 里维护 changelog团队协作的关键是约定大于配置。插件命名规范、目录结构、description 写法这些都要提前约定好。不然十个人写出十种风格维护起来就是灾难。我还建议给插件写测试用例。不是自动化测试就是一组输入-期望输出的样例。每次改完插件手动跑一遍样例确认没退化。这个习惯能挡掉大部分回归问题。7.2 性能优化与加载速度插件多了之后加载速度会变慢。优化方向有几个精简 resources。大文件移到外部插件里只放引用。我见过一个插件把 50MB 的 PDF 塞进 resources加载要十几秒。延迟加载。不是所有命令都需要在启动时加载。把低频命令拆成独立插件按需加载。合并小插件。功能相近的小插件合并成一个减少加载次数。但别合并过头一个插件塞太多功能维护会变难。我实测下来单个插件的 resources 控制在 1MB 以内加载速度基本无感。超过 10MB就能明显感觉到卡顿。7.3 从个人插件到团队资产个人用的插件和团队用的插件要求完全不一样。个人用自己看得懂就行团队用别人得看得懂、用得对、改得动。从个人插件升级到团队资产要补这几样东西完整的 README这个插件干什么、怎么用、有什么限制输入输出示例让新人一眼看懂效果常见问题把踩过的坑写下来维护者信息出问题找谁我见过太多作者离职后没人敢动的插件就是因为缺这些文档。插件是资产资产就要有资产的管理方式。8. 我个人的一些实操体会写插件这件事我最大的体会是克制。新手容易犯的错是贪多一个插件想解决所有问题结果指令写了三千字AI 反而抓不住重点。我现在写插件单个命令的指令正文控制在 500 字以内超过就拆。第二个体会是迭代。没有一次写对的插件。我的习惯是先写个能跑的版本用一周记录哪里不顺手然后改。改个三五轮插件才真正好用。别指望一次成型。第三个体会是场景驱动。别为了写插件而写插件。我见过有人把每天喝水提醒也做成插件这就本末倒置了。插件的价值在于处理高频、重复、有固定套路的任务。低频任务直接对话就行。最后分享一个小技巧给插件起名的时候用动词开头。organize-notes比notes-organizer好因为动词直接说明了这个插件做什么。敲命令的时候/organize也比/notes更直观。这个细节看着小但用起来差别很大。插件系统这东西入门门槛不高但用好需要时间。我的建议是先从一个小插件开始跑通全流程再逐步扩展。别一上来就设计一个大而全的框架那样大概率会烂尾。小步快跑持续迭代这才是插件工程化的正确姿势。
阅读完成 · 觉得有帮助？
