1. 从knowledge-work-plugins这个名字说起它到底在解决什么问题第一次看到knowledge-work-plugins这个仓库名很多人会下意识地把它归类成又一个插件合集。但如果你真的在 Claude Code 或 Claude Cowork 里干过几天活就会明白这个名字背后藏着一个很具体的痛点知识工作者的重复劳动没有被工具化。什么叫知识工作的重复劳动举几个我自己天天遇到的场景。每周要写周报格式固定但每次都要重新翻聊天记录、翻提交历史、翻会议纪要然后手动拼成一段话。每次做竞品调研都要打开十几个网页复制粘贴到文档里再手动整理成对比表格。每次 review 一份 PR都要重复检查同样的几类问题命名规范、边界条件、错误处理、测试覆盖。这些事情单看都不难但架不住天天做、反复做累积起来就是巨大的时间黑洞。knowledge-work-plugins这个项目本质上就是把这些高频、低创造性、有固定套路的知识工作流程封装成 Claude Code 可以调用的插件。它不是一个具体的软件产品而是一套插件集合 组织规范让你可以把我平时怎么干活这件事变成Claude 帮我怎么干活。这里要先厘清一个概念因为热词里混进了不少容易混淆的东西。Claude Code 是 Anthropic 推出的命令行 AI 编程助手它本身是一个 CLI 工具能读写文件、执行命令、调用工具。而plugins插件是 Claude Code 的扩展机制允许你往这个 CLI 里注入自定义的能力——比如自定义的 slash commands斜杠命令、自定义的 skills技能、自定义的 hooks钩子。knowledge-work-plugins就是一批围绕知识工作这个场景写好的插件。它适合谁我的判断是三类人。第一类是每天用 Claude Code 但只会用默认功能的开发者他们不知道还能自己定义命令白白浪费了工具的扩展性。第二类是非技术背景但愿意折腾工具的知识工作者比如产品经理、运营、研究员他们需要的是把流程固化下来而不是写代码。第三类是团队里负责工具链建设的人他们需要一套可复制、可分发的插件组织方式让整个团队用同一套工作流。提示如果你还没装 Claude Code先别急着看插件。插件是建立在 CLI 之上的CLI 没跑通插件无从谈起。安装和基础配置是前置条件。我见过太多人一上来就想搞插件结果连 Claude Code 的基本交互都没摸熟最后卡在权限配置、路径问题上白白消耗热情。所以这篇文章的节奏是先把 Claude Code 的插件机制讲透再讲knowledge-work-plugins这类项目怎么组织最后给你一套可以照着抄的实操路径。2. Claude Code 的插件机制slash commands、skills 和 hooks 到底怎么分工要理解knowledge-work-plugins必须先理解 Claude Code 的扩展体系。很多人把 slash commands、skills、hooks 混为一谈觉得都是让 Claude 多干点事但它们的职责边界其实非常清晰用错了地方就会很别扭。2.1 slash commands把一段固定指令变成一条命令slash commands 是最直观的扩展方式。你在 Claude Code 里输入/开头的命令它就会执行你预定义的一段 prompt。比如你可以定义一个/weekly-report输入之后 Claude 就自动去读你指定的目录、汇总本周的提交记录、按你规定的格式输出周报。它的本质是prompt 模板 参数占位。你在一个 markdown 文件里写好指令Claude Code 读取这个文件把用户输入的参数填进去然后当作普通对话发给模型。所以 slash commands 的能力上限取决于你 prompt 写得好不好以及模型能不能访问到它需要的数据。我自己的经验是slash commands 最适合**输入明确、输出格式固定**的任务。比如/review-pr 1234拉取指定 PR按检查清单逐条 review/summarize-meeting ./notes/2024-06-01.md把会议纪要压缩成决策项和待办/gen-changelog v1.2.0..v1.3.0根据 commit 区间生成 changelog这些任务的共同点是你每次做的时候脑子里的套路是一样的只是数据在变。这种就特别适合做成 slash command。2.2 skills让 Claude 在特定场景下自动知道该怎么做skills 和 slash commands 最大的区别是触发方式。slash command 是你主动敲命令触发的skill 是 Claude 在判断当前任务需要这个能力时自动加载的。一个 skill 通常包含三部分一段描述告诉 Claude 这个 skill 是干什么的、什么时候该用、一份指令具体怎么做、可能还有配套的脚本或资源文件。当你在对话里提到相关任务时Claude 会读取 skill 的描述判断是否需要加载然后按 skill 里的指令执行。举个例子你可以写一个代码审查skill描述里写当用户要求 review 代码、检查 PR、或者提到代码质量时使用。之后你只要说帮我看看这段代码有没有问题Claude 就可能自动加载这个 skill按你预设的检查清单来审。这里有个坑我要提前说skill 的自动触发依赖描述的准确性。描述写得太宽泛Claude 会在不相关的场景乱加载写得太窄又永远触发不了。我的做法是描述里明确写当用户……时使用把触发条件写具体同时避免用代码文件这种过于通用的词。2.3 hooks在特定事件点插入自动化动作hooks 是更底层的机制。它不是在对话层面工作而是在 Claude Code 的生命周期事件上挂钩子。比如工具调用之前文件写入之后会话结束时这些时间点你可以让 Claude Code 执行一段 shell 命令或脚本。hooks 的典型用途是强制约束和自动记录。比如你可以配一个 hook在每次文件写入后自动跑一遍格式化工具或者配一个 hook在会话结束时把本次对话的摘要追加到日志文件里。hooks 和前面两者的关系我打个比方slash commands 和 skills 是Claude 主动做的事hooks 是系统在特定时刻自动做的事。前者需要模型参与决策后者是确定性的自动化。扩展类型触发方式适合场景是否需要模型判断slash commands用户主动输入/xxx固定格式的重复任务是执行 promptskillsClaude 根据描述自动加载需要知道怎么做的场景是判断是否加载hooks生命周期事件触发强制约束、自动记录否确定性执行理解了这三者的分工再看knowledge-work-plugins这类项目你就会发现它的组织逻辑用 slash commands 承载用户主动发起的工作流用 skills 承载需要 Claude 自己判断的知识用 hooks 承载必须强制执行的规定动作。3. knowledge-work-plugins 的目录组织一个插件仓库该怎么摆光知道机制不够真正动手的时候第一个卡住人的问题是文件放哪、怎么命名、怎么让 Claude Code 认出来。这部分官方文档写得比较散我按自己的实践整理一遍。3.1 插件的存放位置与加载优先级Claude Code 识别插件有几个位置优先级从高到低大致是项目级项目根目录下的.claude/目录只对当前项目生效用户级用户主目录下的~/.claude/目录对你所有项目生效插件市场/仓库通过配置引入的外部插件集合knowledge-work-plugins这种仓库通常是以插件集合的形式存在你需要把它克隆到本地然后在配置里指向它或者把里面的内容复制到你的.claude/目录。我的建议是通用型插件放用户级项目专属插件放项目级。比如周报生成这种你每个项目都要用的放~/.claude/commands/而这个项目的 API 规范检查这种只对当前项目有意义的放项目里的.claude/commands/。注意项目级配置会覆盖用户级同名配置。如果你发现自己的命令没生效先检查是不是被项目里的同名文件覆盖了。3.2 slash command 文件的标准结构一个 slash command 就是一个 markdown 文件放在commands/目录下文件名就是命令名。比如commands/weekly-report.md对应/weekly-report。文件内容分两部分frontmatter元信息和正文prompt。frontmatter 用 YAML 格式写在文件开头用---包裹。常见的字段包括--- description: 生成本周工作周报 argument-hint: [周起始日期] allowed-tools: Read, Grep, Bash(git log:*) --- 请根据以下步骤生成本周周报 1. 读取 $ARGUMENTS 指定日期范围内的 git 提交记录 2. 按完成事项 / 进行中 / 阻塞项三类归纳 3. 输出格式要求每类用无序列表阻塞项需标注原因这里几个字段值得展开说。description是给用户看的输入/时会显示。argument-hint提示参数格式。allowed-tools是最关键的——它限制了这条命令能调用哪些工具是权限控制的第一道闸门。我踩过的坑一开始不写allowed-tools结果命令能调用任意工具包括写文件、执行任意命令这在团队协作里是隐患。后来我养成习惯每条命令都显式声明它需要的最小工具集。比如只是读文件汇总就只给Read和Grep绝不给Bash。3.3 skill 的组织方式与渐进式加载skill 的结构比 command 复杂一点。一个 skill 是一个目录目录里有SKILL.md作为入口还可以带脚本、模板、参考文档。skills/ code-review/ SKILL.md checklist.md scripts/ lint.shSKILL.md的 frontmatter 里name和description是必填的。description 决定了 Claude 什么时候加载这个 skill所以它必须写得既准确又有区分度。skill 的一个重要特性是渐进式加载Claude 先只读 description判断需要时才读 SKILL.md 正文正文里如果引用了其他文件再按需读取。这个设计的好处是节省上下文——你不需要把所有细节都塞进 description正文可以写得很详细。我的经验是SKILL.md 正文控制在 500 行以内超出的部分拆成独立文件在正文里用相对路径引用。这样 Claude 只在真正需要时才读那些细节文件不会一上来就吃掉大量 token。3.4 一个可复用的目录模板把上面这些拼起来一个knowledge-work-plugins风格的仓库我推荐这样组织knowledge-work-plugins/ commands/ weekly-report.md review-pr.md summarize-meeting.md skills/ code-review/ SKILL.md checklist.md research/ SKILL.md templates/ comparison-table.md hooks/ format-on-write.sh README.md这个结构的好处是职责清晰commands 是用户主动触发的skills 是自动加载的hooks 是系统级的。新人接手时看一眼目录就知道每类东西放哪。4. 从零写一个知识工作插件以周报生成为例的完整实操理论讲够了来点能直接抄的。我拿周报生成这个最典型的知识工作场景走一遍从设计到落地的完整流程。选它是因为它足够简单又足够有代表性——几乎每个知识工作者都要写周报而且每个人的周报套路都不一样。4.1 先想清楚这个任务的输入、输出和判断逻辑动手写 prompt 之前我习惯先在纸上把三件事写清楚输入是什么git 提交记录、Jira/任务系统的变更、会议纪要、聊天记录输出是什么固定格式的周报文本分完成/进行中/阻塞三类判断逻辑是什么怎么从原始数据里判断一件事是完成还是进行中第三步最容易被忽略但它恰恰是决定插件好不好用的关键。比如 git commit 里写着fix bug这算完成还是进行中如果 commit 后面还有关联的 PR 没合并那应该是进行中。这些判断规则你必须显式写进 prompt否则 Claude 只能瞎猜。我的做法是把判断规则写成一张表直接放进 prompt数据特征归类commit 已合并到主分支完成commit 在 feature 分支且 PR 未合并进行中commit message 含 WIP 或 blocked阻塞有对应 issue 且 issue 状态为 open进行中4.2 写 command 文件prompt 的颗粒度控制有了上面的设计command 文件就好写了。核心是把判断逻辑写死把数据获取交给工具。--- description: 根据 git 记录生成本周周报 argument-hint: [起始日期如 2024-06-01] allowed-tools: Read, Grep, Bash(git log:*) --- 你是一个周报助手。请根据 $ARGUMENTS 起始日期到今天的 git 提交记录生成周报。 步骤 1. 执行 git log --since$ARGUMENTS --prettyformat:%h %s %d 获取提交 2. 按以下规则归类每条提交 - 已合并到 main/master完成 - 在 feature 分支且无合并标记进行中 - message 含 WIP/blocked阻塞 3. 输出格式 ## 本周完成 - [事项描述] ## 进行中 - [事项描述] ## 阻塞项 - [事项描述]原因xxx 注意不要编造未在 git 记录中出现的事项。这里有个细节值得说最后那句不要编造很重要。模型有很强的补全倾向如果你不明确禁止它可能会根据 commit message 脑补出一些你没做过的事。我在实际使用中吃过这个亏周报里出现了我根本没参与的模块差点在汇报时出洋相。4.3 参数传递与边界处理$ARGUMENTS是 Claude Code 传给 command 的参数。但用户可能不传参数或者传一个格式不对的日期。这时候 prompt 里要处理边界情况。我的做法是在 prompt 开头加一段兜底逻辑如果 $ARGUMENTS 为空默认取本周一作为起始日期。 如果 $ARGUMENTS 不是合法日期格式提示用户重新输入不要继续执行。这种兜底看起来啰嗦但能避免很多命令跑了一半报错的尴尬。尤其是团队共用的时候你不能指望每个人都记得传参数。4.4 实测中的意外情况第一次跑通之后我遇到了几个意料之外的问题这里分享出来帮你避坑。问题一git log 输出太长超出上下文。如果一周提交很多git log的输出可能几百行直接塞给模型会挤占上下文。我的解法是在 command 里加一步过滤只取 commit 的标题行不取完整 diffgit log --since$ARGUMENTS --prettyformat:%h %s --no-merges--no-merges去掉合并提交%s只取标题输出量能减少一大半。问题二分支判断不准。单纯看 commit 无法判断分支状态需要额外查git branch --contains。但这会让命令变复杂。我的折中方案是让用户手动维护一个进行中的清单文件command 读取这个文件来补充判断。工具不是万能的有些信息就是需要人喂。问题三格式不稳定。同样的输入模型有时输出带编号有时不带。解法是在 prompt 里给出完整的输出示例而不是只描述格式。示例比描述有效得多。5. 插件写完之后分发、版本管理和团队协作的坑一个人用插件和一群人用插件完全是两回事。knowledge-work-plugins这类项目之所以有价值很大程度上是因为它解决了团队共享工作流的问题。但共享这件事坑比想象中多。5.1 插件怎么分发给团队成员最朴素的方式是把仓库克隆下来让每个人自己复制到~/.claude/。但这有个致命问题更新不同步。你改了 command别人不知道还在用旧版本。我的做法是把这个仓库做成一个 git 仓库团队成员通过 git pull 更新。同时在 README 里写清楚更新步骤。更规范一点可以写一个安装脚本#!/bin/bash # install.sh TARGET$HOME/.claude mkdir -p $TARGET/commands $TARGET/skills cp -r ./commands/* $TARGET/commands/ cp -r ./skills/* $TARGET/skills/ echo 插件已安装到 $TARGET这个脚本简单但解决了手动复制容易漏文件的问题。注意cp -r会覆盖同名文件所以更新前最好提醒用户备份自己的本地修改。5.2 版本管理什么时候该打 tag插件仓库也需要版本管理但颗粒度不用太细。我的经验是当 command 的 prompt 逻辑发生实质性变化时打一个 tag。比如判断规则改了、输出格式改了、新增了命令这些值得打 tag。而错别字修正、注释调整这种直接提交就行。tag 命名用语义化版本比如v1.2.0。在 README 里维护一个 CHANGELOG写清楚每个版本改了什么。这样团队成员更新时能知道这次更新会不会影响我的使用习惯。5.3 团队协作中最容易吵起来的三件事第一件输出格式。有人喜欢周报用表格有人喜欢用列表。这种分歧没有对错但必须统一。我的解法是让格式可配置——在 command 里读一个配置文件用户可以选择格式。但这样会增加复杂度小团队直接投票定一个格式更省事。第二件权限范围。有人希望 command 能自动提交代码有人觉得太危险。这本质上是allowed-tools的配置问题。我的原则是默认最小权限需要更多权限时显式申请。宁可多敲几次确认也不要让一个命令能悄悄改你的代码库。第三件谁来维护。插件仓库最怕的是没人管。我的建议是设一个明确的维护者其他人提 PR。维护者负责 review prompt 的改动确保不会引入奇怪的逻辑。提示团队共享插件时一定要在 README 里写清楚这个命令会做什么、不会做什么。信任建立在透明之上。6. 让插件真正好用的几个进阶技巧前面讲的都是能用这一节讲好用。这些技巧是我用了几个月之后慢慢摸索出来的官方文档里基本不会写。6.1 prompt 里加自检步骤模型输出之后让它自己检查一遍能显著降低错误率。比如在周报 command 的最后加一句输出之前请自检 1. 每个完成项是否都有对应的已合并 commit 2. 是否有编造的事项 3. 格式是否符合要求 如有不符请修正后再输出。这个技巧的原理是让模型把生成和校验分成两步。生成时它关注内容校验时它关注规则分开做比混在一起做效果好。我实测下来加了自检之后格式错误率下降非常明显。6.2 用 skill 承载领域知识用 command 承载操作流程这是我用了一段时间才想明白的分工。举个例子代码审查这件事怎么审是领域知识检查哪些点、什么算严重问题审哪个 PR是操作流程。所以我的做法是把审查清单写成一个 skill把拉取 PR 并触发审查写成一个 command。command 里只写调用代码审查 skill对 PR #xxx 进行审查具体的检查项交给 skill。这样检查清单更新时只需要改 skill所有引用它的 command 都自动生效。6.3 给 command 加干跑模式有些 command 会执行有副作用的操作比如写文件、提交代码。这种命令最好支持一个干跑参数只输出我打算做什么不真正执行。实现方式是在 prompt 里判断参数如果 $ARGUMENTS 包含 --dry-run只输出计划执行的操作不要实际执行。这个模式在调试新 command 时特别有用。你可以先干跑几次确认逻辑对了再去掉参数真正执行。6.4 定期清理失效的插件插件写多了会积累垃圾。有些 command 你半年没用过有些 skill 引用的文件已经删了。我建议每个月花十分钟过一遍把不用的删掉。判断标准很简单过去一个月你用过吗没用过就删。别舍不得留着只会让/命令列表越来越长找东西越来越难。6.5 把常用参数做成默认值有些参数你每次都传一样的值比如周报的起始日期永远是本周一。这种可以在 command 里设默认值用户不传就用默认。如果 $ARGUMENTS 为空使用本周一作为起始日期。这样日常使用就变成敲一个/weekly-report回车不用记参数格式。降低使用门槛是让插件真正被用起来的关键。7. 我踩过的那些坑一份真实的排错记录最后这部分我想把几个印象深刻的坑完整记录下来。不是给结论而是给排查过程因为排查思路比结论更有复用价值。7.1 命令不生效从文件在哪开始查有一次我写了个新 command敲/死活看不到。排查过程是这样的第一步确认文件位置。ls ~/.claude/commands/看文件在不在。在。第二步确认文件名。文件名是weekly-report.md命令应该是/weekly-report。没问题。第三步检查 frontmatter 格式。打开文件一看---只写了开头没写结尾。YAML 解析失败整个文件被忽略了。这个坑的教训是frontmatter 的---必须成对出现。少一个文件就废了而且不会有任何报错提示非常隐蔽。7.2 权限报错allowed-tools 写错了工具名另一次command 里用了Bash(git log:*)结果执行时报权限错误。查了半天发现是工具名大小写问题——应该是Bash不是bash。Claude Code 的工具名是大小写敏感的。Read、Grep、Bash、Write这些首字母都要大写。写错了不会报工具名错误只会报权限不足很容易误导排查方向。7.3 输出乱码编码问题有次 command 输出的中文全是乱码。原因是文件保存成了 GBK 编码而 Claude Code 按 UTF-8 读取。解法很简单把文件转成 UTF-8 就行。但这个坑的隐蔽之处在于编辑器里看着是正常的只有 Claude Code 读出来才乱码。我的习惯是所有.claude/下的文件都用 UTF-8 保存编辑器里设置默认编码为 UTF-8。这个设置一次省心很久。7.4 skill 不触发description 写得太文艺我写过一个 skilldescription 是帮助用户进行深度思考。结果它从来不触发。后来改成当用户要求分析问题、拆解需求、或进行头脑风暴时使用立刻就正常了。原因是模型判断是否加载 skill靠的是 description 和当前任务的语义匹配。深度思考太抽象模型不知道对应什么具体任务。而分析问题、拆解需求、头脑风暴是具体的动作词匹配度高得多。写 description 的诀窍用动词用具体场景别用形容词。7.5 排查的通用思路把这几个坑抽象一下排查插件问题的通用顺序是文件层面文件在不在文件名对不对编码对不对frontmatter 格式对不对配置层面allowed-tools 写对了吗有没有被项目级配置覆盖逻辑层面prompt 里的判断规则清晰吗有没有歧义模型层面description 的触发条件明确吗输出格式给了示例吗按这个顺序查90% 的问题都能定位。剩下 10%通常是模型本身的随机性导致的多跑几次看看是不是稳定复现。8. 关于 knowledge-work-plugins 这类项目我的几点判断写到这里我想跳出具体操作聊聊对这类项目的看法。knowledge-work-plugins这个名字其实点出了一个趋势AI 工具的价值正在从模型能力转向工作流封装。模型再强如果你每次都要重新描述需求效率提升是有限的。真正拉开差距的是你有没有把自己的工作流沉淀成可复用的插件。我观察到的一个现象是同样用 Claude Code有人效率提升 30%有人提升 3 倍。差距不在模型在于后者把重复劳动都插件化了。他们不是在用 AI而是在训练 AI 按自己的方式干活。所以我的建议是别急着收集一堆现成插件先花一周时间观察自己每天重复做什么。找出那三五个最高频、最套路化的任务把它们做成 command。哪怕一开始很粗糙用起来之后再迭代。插件这东西用起来比写得好更重要。至于knowledge-work-plugins这个具体项目它的价值不在于提供了多少现成插件而在于它示范了一种组织方式——怎么把知识工作的流程拆解成 commands、skills、hooks 三层结构。你可以直接用它也可以照着它的思路搭自己的。最后分享一个我自己的小习惯我会在~/.claude/下放一个NOTES.md记录每个插件的用途、参数、以及上次为什么改它。插件写多了之后这个笔记比任何文档都有用因为它记录的是你自己的使用历史。