1. 从零认识 knowledge-work-plugins它到底解决什么问题第一次看到knowledge-work-plugins这个仓库名很多人会以为是某个知识管理软件的插件合集或者某个笔记工具的扩展包。实际上它是 Anthropic 官方在 Claude Code 生态里放出的一个示例插件集合专门用来演示“知识工作”场景下如何通过插件机制扩展 Claude Code 的能力。所谓知识工作说白了就是写文档、做调研、整理会议纪要、生成报告、管理任务这类以信息处理为核心的日常工作而不是写代码本身。这个仓库的核心价值在于它把 Claude Code 的插件系统从“概念”变成了“可运行的参考实现”。你可以把它理解成一份带代码的说明书里面包含了 slash commands、skills、agents、hooks 等组件的实际写法每个插件都对应一个具体的知识工作场景。对于想给 Claude Code 写自定义插件的人来说这比读官方文档要直观得多因为你能直接看到文件怎么组织、命令怎么注册、参数怎么传递。适合读这篇内容的人有三类。第一类是已经在用 Claude Code、想把自己的工作流固化下来的开发者比如你每天都要生成周报、整理需求文档那就可以照着这个仓库写一个自己的插件。第二类是对 Claude Code 插件机制好奇、但还没动手的人这个仓库是最好的起点因为它的结构足够简单不会一上来就被复杂的工程配置劝退。第三类是团队里负责工具链建设的人你可以基于这个仓库的约定设计一套团队内部共享的插件规范。需要提前说明的是Claude Code 的插件系统和 VS Code 插件、Qt 插件完全是两回事。热搜里出现的available platform plugins are: eglfs, linuxfb, minimal那是 Qt 的平台插件iar plugins是 IAR 嵌入式开发环境的扩展跟这里说的 Claude Code 插件没有关系。knowledge-work-plugins里的 plugin 指的是 Claude Code 运行时加载的能力包通过 slash commands 和 skills 来触发运行在 Claude Code 的会话上下文里。2. 插件机制的整体设计与目录结构拆解2.1 为什么 Claude Code 要设计插件系统Claude Code 本身是一个命令行里的 AI 编程助手默认能力是读写文件、执行命令、理解代码库。但实际工作中很多任务是有固定套路的比如“把这次会议的录音转写整理成纪要”“根据 git log 生成 changelog”“把需求文档拆成任务列表”。如果每次都靠自然语言描述一遍既费 token 又不稳定。插件系统解决的就是这个问题把重复性的工作流封装成可复用的命令用/command-name的方式一键触发。这跟 shell 里的 alias、Makefile 里的 target 是同一个思路只不过执行体变成了 AI 驱动的流程。knowledge-work-plugins这个仓库就是官方给出的“标准答案”告诉你一个插件应该长什么样。2.2 仓库的目录组织逻辑打开这个仓库你会看到类似这样的结构基于常见实践整理具体以仓库实际内容为准knowledge-work-plugins/ ├── plugins/ │ ├── meeting-notes/ │ │ ├── plugin.json │ │ ├── commands/ │ │ │ └── summarize.md │ │ └── skills/ │ │ └── extract-actions.md │ ├── research-assistant/ │ │ ├── plugin.json │ │ └── commands/ │ │ └── deep-dive.md │ └── ... ├── README.md └── LICENSE每个插件是一个独立目录里面必须有plugin.json作为清单文件声明插件的名称、版本、描述、作者等信息。commands/目录下放 slash command 的定义通常是 Markdown 文件文件名就是命令名。skills/目录下放技能定义技能和命令的区别在于命令是用户主动触发的技能是 Claude 在对话中根据上下文自动调用的。这种“一个插件一个目录”的设计有个明显好处插件之间完全隔离你可以单独复制某个插件到自己的项目里不用担心依赖冲突。同时plugin.json作为清单文件让 Claude Code 在启动时能快速扫描并注册所有可用插件不需要执行任何代码。2.3 命令与技能的分工很多人会混淆 command 和 skill这里用一个生活化的类比来解释。Command 像是餐厅菜单上的菜名你点了才会做Skill 像是厨师的拿手技法顾客不一定会点名但厨师在需要的时候会自动用上。具体到knowledge-work-plugins里/summarize这样的命令是你手动输入的Claude 收到后按照 Markdown 文件里定义的流程执行。而extract-actions这样的技能是当你在对话里说“帮我看看这段会议记录有什么待办”时Claude 判断需要用到这个技能自动加载并执行。命令的定义文件里通常包含 frontmatter 元数据描述、参数说明和正文提示词技能的定义文件则更侧重于触发条件和执行逻辑。注意命令名和技能名不要用中文也不要用空格建议用短横线连接的小写英文。Claude Code 在解析 slash command 时对大小写敏感/Summarize和/summarize可能被当成两个不同的命令。3. 核心组件详解与实操要点3.1 plugin.json 清单文件的字段含义plugin.json是整个插件的入口Claude Code 启动时会读取这个文件来决定是否加载插件。一个典型的清单文件包含以下字段{ name: meeting-notes, version: 1.0.0, description: 把会议记录整理成结构化纪要和待办列表, author: your-name, commands: [summarize], skills: [extract-actions] }name字段是插件的唯一标识建议用短横线命名不要跟其他插件重名。version遵循语义化版本规范方便后续更新。description会显示在插件列表里写清楚这个插件干什么用方便别人判断要不要启用。commands和skills数组声明了这个插件包含哪些命令和技能Claude Code 会根据这个列表去对应目录加载文件。这里有个容易踩的坑commands数组里的名字必须和commands/目录下的文件名去掉.md后缀完全一致否则命令注册会失败但 Claude Code 不一定会给出明确的报错可能只是命令不生效。我建议每次改完清单文件后用/help命令确认一下命令是否出现在列表里。3.2 slash command 定义文件的写法命令定义文件是 Markdown 格式顶部用 YAML frontmatter 声明元数据正文是给 Claude 的提示词。以summarize.md为例--- description: 把会议记录整理成结构化纪要 argument-hint: [会议记录文件路径] --- 请读取 $ARGUMENTS 指定的文件按照以下结构整理成会议纪要 1. 会议主题与时间 2. 参会人员 3. 讨论要点按议题分组 4. 达成的决议 5. 待办事项包含负责人和截止时间 如果文件中没有明确提到负责人或截止时间标注为“待确认”不要自行编造。description会显示在命令列表里argument-hint提示用户这个命令需要什么参数。正文里的$ARGUMENTS是占位符会被用户输入的实际参数替换。这种设计让你可以写出带参数的命令比如/summarize meeting-2024-01-15.md。写提示词时有几个要点。第一明确输出结构用有序列表把期望的格式写清楚Claude 会严格按照这个结构输出。第二明确边界条件比如“没有提到就标注待确认”避免 Claude 自由发挥编造信息。第三控制长度提示词不是越长越好把关键约束写清楚就行太长的提示词反而会稀释重点。3.3 skill 定义文件的触发机制技能文件的结构和命令类似但重点在于触发条件。以extract-actions.md为例--- name: extract-actions description: 从对话或文档中提取待办事项 trigger: 当用户提到“待办”“action item”“下一步”等关键词时 --- 从当前上下文中提取所有待办事项每条包含 - 事项描述 - 负责人如有 - 截止时间如有 - 优先级高/中/低根据上下文判断 输出为 Markdown 表格。技能的关键在于trigger字段它告诉 Claude 什么情况下应该自动加载这个技能。触发条件写得越具体技能被正确调用的概率越高。如果写得太宽泛比如“当用户需要帮助时”那几乎每轮对话都会触发反而干扰正常交流。提示技能和命令可以配合使用。比如/summarize命令执行完后Claude 可以自动调用extract-actions技能从纪要里提取待办这样用户只需要输入一次命令就能拿到完整结果。3.4 参数传递与上下文管理Claude Code 在执行命令时会把当前会话的上下文一起传给插件。这意味着你的命令定义里可以直接引用之前对话的内容不需要用户重复粘贴。比如用户先粘贴了一段会议记录然后输入/summarize命令里的提示词可以直接说“请整理上文中的会议记录”Claude 能理解“上文”指的是什么。参数传递方面除了$ARGUMENTS占位符还可以用$1、$2这样的位置参数。如果你的命令需要多个参数建议在argument-hint里写清楚顺序比如[文件路径] [输出格式]。实测下来位置参数在参数数量固定时很好用但如果参数可选还是用$ARGUMENTS整体接收再在提示词里解析更灵活。上下文管理有个需要注意的地方Claude Code 的会话上下文有长度限制如果你的命令要处理很长的文档建议在提示词里明确要求“分段处理”或者“只关注前 N 个要点”避免上下文溢出导致命令执行中断。4. 完整实操流程从克隆仓库到跑通第一个插件4.1 环境准备与仓库获取在开始之前你需要确认本地已经装好了 Claude Code。安装方式根据操作系统不同有所差异macOS 和 Linux 通常用包管理器或者官方脚本Windows 11 建议在 WSL2 环境下运行因为 Claude Code 的很多命令依赖 Unix 工具链。安装完成后在终端输入claude能看到欢迎信息说明环境就绪。获取knowledge-work-plugins仓库的方式很简单用 git 克隆到本地任意目录即可。如果你只是想参考写法不打算直接运行也可以直接在网页上浏览文件。但建议克隆下来因为后面要实际加载插件本地有文件才能配置。git clone 仓库地址 knowledge-work-plugins cd knowledge-work-plugins克隆完成后先看一眼 README里面通常会说明这个仓库的用途和基本用法。然后浏览plugins/目录挑一个你感兴趣的插件作为练手对象。我建议从meeting-notes开始因为会议纪要这个场景足够通用容易验证效果。4.2 配置 Claude Code 加载插件Claude Code 加载插件的配置方式有几种常见的是在项目根目录放一个.claude/目录里面用配置文件声明插件路径。具体配置项的名称可能随版本变化建议以你本地 Claude Code 版本的文档为准。基于常见实践配置大概长这样{ plugins: [ /absolute/path/to/knowledge-work-plugins/plugins/meeting-notes ] }路径建议用绝对路径相对路径在不同工作目录下容易出问题。配置完成后重启 Claude Code输入/help查看命令列表如果能看到summarize说明插件加载成功。如果命令没出现按以下顺序排查第一检查plugin.json里的commands数组是否和文件名一致第二检查配置文件里的路径是否正确可以用ls确认目录存在第三检查 Claude Code 的版本是否支持插件功能太老的版本可能没有这个能力。4.3 跑通第一个命令并验证输出准备一份测试用的会议记录随便写几段对话包含讨论内容和一些待办事项。然后在 Claude Code 里输入/summarize test-meeting.mdClaude 会读取文件按照命令定义里的结构输出纪要。第一次跑的时候重点观察三件事输出结构是否符合预期、待办事项是否被正确提取、有没有编造不存在的信息。如果输出结构不对回去改命令定义里的提示词如果编造信息在提示词里加强“不要编造”的约束。实测下来Claude 对结构化输出的遵循度很高只要你把格式写清楚基本不会跑偏。但边界条件需要反复打磨比如“没有负责人就标注待确认”这条如果不写Claude 可能会自己猜一个名字填进去。这类约束是插件质量的关键也是knowledge-work-plugins里每个示例都值得细读的原因。4.4 改造插件适配自己的场景跑通官方示例后下一步就是改成自己的场景。比如你不在开会但每天要整理工作日志那就可以复制meeting-notes目录改名为daily-log然后修改plugin.json里的名称和描述再调整命令定义里的提示词结构。改造时有个技巧不要一次性大改先改提示词里的输出结构跑一遍看效果再改触发条件再改参数。每次只改一个变量这样出问题的时候容易定位。我见过有人一次性把命令名、参数、提示词全改了结果命令不生效排查了半天发现是清单文件里的命令名忘了同步更新。5. 常见问题与排查技巧实录5.1 命令不生效的排查路径命令不生效是最常见的问题表现是输入/summarize后 Claude 没有按预期执行或者提示“未知命令”。排查按以下顺序进行排查项检查方法常见原因插件是否加载输入/help看命令列表配置文件路径错误命令名是否匹配对比plugin.json和文件名大小写不一致、拼写错误文件格式是否正确检查 frontmatter 语法YAML 缩进错误、缺少分隔符版本是否支持查看 Claude Code 版本旧版本不支持插件YAML frontmatter 的语法错误特别隐蔽比如冒号后面少了个空格或者用了 Tab 缩进。建议用支持 YAML 语法高亮的编辑器写这些文件能提前发现大部分格式问题。5.2 技能被过度触发或从不触发技能触发问题分两种。一种是过度触发表现为 Claude 在无关对话里也调用技能这通常是trigger字段写得太宽泛。解决办法是把触发条件收窄比如从“当用户提到任务时”改成“当用户明确说‘提取待办’或‘action item’时”。另一种是从不触发原因是触发条件太窄或者关键词不匹配。可以在技能定义里多列几个同义词比如“待办、todo、action item、下一步、跟进事项”都列上。实测下来触发条件里包含用户可能说的原话比抽象描述更有效。5.3 输出格式不稳定的处理有时候同样的命令两次执行输出格式不一样。这通常是因为提示词里的格式约束不够明确。解决办法是用 Markdown 代码块把期望的输出模板写出来让 Claude 照着填。比如请按以下模板输出 ## 会议主题 [填写主题] ## 待办事项 | 事项 | 负责人 | 截止时间 | |------|--------|----------| | [填写] | [填写] | [填写] |模板越具体输出越稳定。另外在提示词末尾加一句“严格按照上述模板输出不要添加额外章节”能进一步减少自由发挥。5.4 插件之间的冲突处理如果你同时加载了多个插件可能会出现命令名冲突。比如两个插件都定义了summarize命令Claude Code 的行为可能是后者覆盖前者也可能是报错取决于版本。避免冲突的方法是在命令名前加插件前缀比如meeting-summarize、research-summarize。技能冲突相对少见因为技能是自动触发的Claude 会根据上下文选择。但如果两个技能的触发条件高度重叠可能会出现调用不稳定。这时候需要调整触发条件让它们各有侧重。注意插件目录不要嵌套太深Claude Code 扫描插件时可能不会递归查找。建议所有插件放在同一层级每个插件一个独立目录。6. 插件开发的经验心得与扩展思路写插件这件事最核心的不是技术而是对工作流的理解。你得先想清楚自己每天重复做的事情是什么哪些步骤是固定的哪些是需要判断的。固定的部分写成提示词模板需要判断的部分留给 Claude。knowledge-work-plugins里的每个示例都是这个思路的产物它们不追求功能大而全而是把一个具体场景做透。我自己的习惯是每当发现自己在对话里重复输入类似的提示词超过三次就考虑把它固化成一个命令。命令的提示词不用一次写完美先跑起来用几次之后根据实际输出调整。这个过程跟写代码时的重构很像先让它工作再让它优雅。扩展方面插件可以和 hooks 结合在特定事件发生时自动执行。比如每次 Claude 完成一个任务后自动调用一个技能把结果追加到日志文件。也可以和 agents 结合让插件在后台执行耗时任务。这些高级用法在knowledge-work-plugins里可能没有全部覆盖但理解了基础机制后看官方文档就能自己摸索。最后分享一个实用技巧把你写的插件放到团队共享的仓库里让同事也能用。插件定义文件是纯文本合并冲突很好解决而且通过 git 管理版本谁改了什么一目了然。我们团队现在有十几个内部插件从生成周报到整理客户反馈基本都是照着knowledge-work-plugins的结构改出来的维护成本很低。
底层原理实战项目避坑指南)
