1. 项目缘起与核心定位1.1 从一个真实痛点说起我在日常工作中大量使用 Claude Code 处理代码审查、文档生成和自动化脚本编写。用得越深越发现一个问题每次开启新会话都要重新交代一遍项目背景、代码规范、常用命令和输出格式。比如我负责的一个后端服务项目每次都要告诉它“用 FastAPI 风格写接口”“日志用 structlog”“测试用 pytest factory_boy”重复到让人抓狂。knowledge-work-plugins这个项目本质上就是为解决这类重复劳动而生的。它是一套面向 Claude Code 和 Claude Cowork 的插件集合把知识工作者日常高频使用的技能、命令和工作流封装成可复用、可分发、可组合的模块。你可以把它理解成给 Claude Code 装上一套“职业技能包”——装上之后它就知道在特定场景下该用什么工具、按什么流程、输出什么格式。这个项目适合三类人一是每天用 Claude Code 写代码、写文档、做分析的深度用户二是想把团队内部最佳实践固化下来、让 AI 助手“入职即上手”的技术负责人三是对 Claude Code 插件机制好奇、想自己写插件但不知道从哪下手的开发者。不管你是哪一类理解这个项目的设计思路和实操方法都能让你的 AI 协作效率上一个台阶。1.2 为什么是“插件”而不是“提示词”很多人第一反应是我写个 system prompt 不就行了为什么要搞插件这么重我一开始也这么想直到我维护了十几个项目的提示词模板之后才发现问题。提示词是“散装”的每个项目一份改了一处忘了另一处提示词是“静态”的没法根据当前打开的文件类型动态切换行为提示词是“不可组合”的想把“代码审查”和“安全扫描”两个能力合在一起用只能复制粘贴拼起来。插件的核心价值在于三点。第一是封装性一个插件把相关的 slash commands、技能定义、配置文件和辅助脚本打包在一起安装即用卸载即走不会污染全局环境。第二是可组合性你可以同时装“代码审查插件”和“文档生成插件”在同一个会话里按需调用互不干扰。第三是可分发性团队里一个人写好插件其他人通过一个命令就能装上保证所有人用的都是同一套规范。提示如果你目前只是偶尔用 Claude Code 问几个问题确实没必要上插件。但当你发现自己反复输入类似的指令超过三次就该考虑把它封装成插件了。1.3 项目整体架构一览knowledge-work-plugins的目录结构遵循 Claude Code 插件规范核心由以下几部分组成.claude-plugin/目录存放插件元信息其中plugin.json是入口文件声明插件名称、版本、作者和包含的组件。commands/目录存放 slash command 定义文件每个.md文件对应一个可通过/调用的命令。skills/目录存放技能定义描述 Claude 在特定场景下应具备的能力和知识。agents/目录存放子代理配置用于把复杂任务拆解给专门的代理处理。hooks/目录存放钩子脚本在特定事件如文件保存、会话开始触发时执行。README.md和文档说明安装方法、使用示例和贡献指南。这种结构的好处是职责清晰。你想加一个新命令就在commands/下新建一个文件想调整某个技能的行为就改skills/下对应的定义。不需要动核心逻辑降低了维护成本。2. 核心机制深度拆解2.1 Slash Commands 的工作原理Slash commands 是用户与插件交互最直接的入口。当你在 Claude Code 会话中输入/时它会扫描已安装插件中commands/目录下的所有.md文件把文件名作为命令名把文件内容作为命令的提示词模板。一个典型的命令文件长这样--- description: 对当前选中的代码进行安全审查 allowed-tools: Read, Grep, Bash --- 请对以下代码进行安全审查重点关注 1. 输入验证是否充分 2. 是否存在注入风险 3. 敏感信息是否硬编码 4. 错误处理是否泄露内部信息 审查完成后按严重程度分级列出问题并给出修复建议。这里有几个关键点值得展开。description字段决定了这个命令在命令列表里显示什么说明写得好不好直接影响你记不记得住这个命令是干嘛的。allowed-tools字段限制了执行该命令时 Claude 可以调用的工具范围这是安全边界——比如一个只读审查命令就不应该允许Write工具。正文部分就是提示词模板Claude 会把当前上下文选中的代码、打开的文件等和这段模板一起送给模型。我实测下来命令文件里的提示词要写得“具体到可执行”。像“请审查代码”这种就太泛模型会给你一堆泛泛而谈而“检查所有用户输入是否经过 sanitize、检查 SQL 拼接是否使用参数化查询”这种模型就能给出真正有用的结果。2.2 Skills 与 Commands 的分工很多人分不清 skills 和 commands 的区别。我用一个类比来解释command 像是你按下的一个按钮按下去就执行一个动作skill 像是你给 Claude 的一本参考手册它会在需要的时候自己翻阅。具体来说commands 是用户主动触发的有明确的输入输出预期skills 是模型在推理过程中根据任务需要自动加载的知识模块。比如你装了一个“Python 测试规范”的 skill当 Claude 在帮你写测试代码时它会自动参考这个 skill 里的规范而不需要你手动调用。在knowledge-work-plugins里skills 通常包含领域知识比如某个框架的最佳实践、某个 API 的使用约定。决策规则在什么情况下该用什么方案什么情况下该拒绝。输出模板特定类型任务的输出格式要求。这种分工让插件既能响应用户的显式指令又能在后台默默提升输出质量。我个人的经验是把“每次都要交代的背景知识”放进 skills把“需要主动触发的操作”做成 commands这样用起来最顺手。2.3 插件加载与优先级机制Claude Code 启动时会按以下顺序加载插件内置插件随 Claude Code 一起发布用户级插件安装在用户主目录下项目级插件安装在项目.claude/目录下后加载的插件会覆盖先加载的同名命令。这个机制很有用你可以在用户级装一个通用插件然后在特定项目里装一个项目级插件来覆盖某些命令的行为。比如通用插件里的/review命令做基础审查项目级插件里的/review命令加上该项目特有的检查项。注意覆盖是整体覆盖不是合并。如果你只想在原有命令基础上加一条检查项需要把原命令内容复制过来再修改而不是只写新增部分。2.4 权限模型与安全边界插件系统有一套权限模型决定了插件能做什么、不能做什么。核心概念是allowed-tools和denied-tools配置项作用典型场景allowed-tools白名单只允许调用列出的工具只读审查命令只允许 Read、Grepdenied-tools黑名单禁止调用列出的工具禁止某个命令执行 Bash无配置继承会话默认权限大多数普通命令这套机制的意义在于当你从社区安装一个第三方插件时你可以通过审查它的allowed-tools配置来判断它是否安全。一个文档生成插件如果声明了Bash权限你就该多留个心眼。我自己的做法是所有涉及文件写入的命令都显式声明allowed-tools: Read, Write不写Bash所有涉及网络请求的命令单独审查其必要性。这样即使插件本身有 bug也不会造成意外破坏。3. 从零搭建一个知识工作插件3.1 环境准备与项目初始化在开始写插件之前你需要确保本地已经装好 Claude Code。安装方式根据操作系统不同略有差异但核心步骤一致下载对应平台的安装包运行安装程序然后在终端里执行claude --version验证安装成功。安装完成后创建一个插件开发目录。我习惯在~/dev/claude-plugins/下放所有自研插件每个插件一个子目录。以创建一个“API 文档生成”插件为例mkdir -p ~/dev/claude-plugins/api-doc-gen/.claude-plugin mkdir -p ~/dev/claude-plugins/api-doc-gen/commands mkdir -p ~/dev/claude-plugins/api-doc-gen/skills cd ~/dev/claude-plugins/api-doc-gen然后创建.claude-plugin/plugin.json{ name: api-doc-gen, version: 1.0.0, description: 根据代码自动生成 API 文档, author: your-name, commands: [commands/], skills: [skills/] }这个文件是插件的“身份证”Claude Code 靠它识别插件并加载对应目录。name字段要唯一建议用 kebab-caseversion遵循语义化版本规范方便后续更新管理。3.2 编写第一个 Slash Command在commands/目录下新建gen-api-doc.md--- description: 扫描当前项目的路由定义生成 Markdown 格式的 API 文档 allowed-tools: Read, Grep, Write --- 请执行以下步骤生成 API 文档 1. 使用 Grep 搜索项目中所有路由定义文件识别框架类型FastAPI、Express、Spring 等 2. 逐个读取路由文件提取每个接口的路径、方法、请求参数、响应结构 3. 按以下模板生成 Markdown 文档 ## 接口名称 - **路径**: /api/xxx - **方法**: GET/POST/... - **请求参数**: 参数名、类型、是否必填、说明 - **响应示例**: JSON 代码块 - **错误码**: 常见错误及含义 4. 将结果写入 docs/API.md 注意如果发现接口缺少参数说明或响应定义在文档中用 [待补充] 标记不要编造。这个命令的设计有几个考量。第一它明确要求先识别框架类型因为不同框架的路由定义方式差异很大不先判断就容易提取错误。第二它给出了固定的输出模板保证每次生成的文档格式一致。第三它明确禁止编造信息这是 AI 生成文档最容易出问题的地方——模型会“脑补”不存在的参数。写完之后在项目里安装这个插件进行测试claude plugin install ~/dev/claude-plugins/api-doc-gen然后在 Claude Code 会话里输入/gen-api-doc看它是否能正确执行。3.3 设计一个实用的 SkillSkill 文件放在skills/目录下每个 skill 一个子目录里面放SKILL.md。以“代码审查规范”为例--- name: code-review-standards description: 团队代码审查的检查清单和输出规范 --- ## 审查维度 ### 正确性 - 边界条件是否处理空值、越界、并发 - 错误处理是否完整异常是否被吞掉 - 资源是否正确释放文件句柄、数据库连接 ### 可维护性 - 函数是否过长超过 50 行需拆分 - 命名是否表意清晰避免缩写歧义 - 是否有重复代码可以抽取 ### 安全性 - 用户输入是否验证和转义 - 敏感数据是否加密存储 - 权限检查是否在每个入口都有 ## 输出格式 按严重程度分三级 - **阻断**: 必须修复才能合并 - **建议**: 应该修复但不阻塞合并 - **提示**: 可选优化记录备查 每条问题需包含文件路径、行号、问题描述、修复建议。这个 skill 的价值在于它把团队内部的审查标准固化下来。新成员用 Claude Code 做审查时输出质量直接对齐团队要求不需要额外培训。我实测下来有了这个 skill 之后代码审查意见的“可操作性”提升非常明显以前模型爱说“建议优化错误处理”现在会说“第 42 行的except Exception会吞掉 KeyboardInterrupt建议改为except (ValueError, IOError)”。3.4 用 Hooks 实现自动化触发Hooks 是插件里最容易被忽视但威力最大的部分。它允许你在特定事件发生时自动执行脚本。比如你想在每次保存文件时自动运行格式化{ hooks: { PostToolUse: [ { matcher: Write, command: bash hooks/format-on-save.sh } ] } }hooks/format-on-save.sh可以调用项目的格式化工具#!/bin/bash FILE$(echo $CLAUDE_TOOL_INPUT | jq -r .file_path) if [[ $FILE *.py ]]; then black $FILE 2/dev/null elif [[ $FILE *.js || $FILE *.ts ]]; then prettier --write $FILE 2/dev/null fi注意Hook 脚本要尽量轻量、快速返回。如果脚本执行超过几秒会明显拖慢 Claude Code 的响应速度。我踩过的坑是在 hook 里跑了全量测试结果每次保存文件都要等半分钟后来改成只跑受影响文件的 lint 才恢复正常。3.5 本地调试与迭代方法插件开发最烦的是“改了要重装才能测”。我的做法是直接用--plugin-dir参数指定插件目录启动 Claude Codeclaude --plugin-dir ~/dev/claude-plugins/api-doc-gen这样修改命令文件后重启会话就能生效不需要反复安装卸载。调试 slash command 时我习惯在命令文件里临时加一行echo输出中间状态确认模型是否正确理解了指令。调试 skill 时则通过观察模型输出是否引用了 skill 里的规范来判断加载是否成功。另一个实用技巧是建一个“测试项目”里面放各种典型场景的代码文件每次改完插件就在这个项目里跑一遍看输出是否符合预期。这比在真实项目里试错安全得多。4. 实战场景与组合玩法4.1 场景一多插件协同的代码审查流水线单独一个审查插件能力有限但把几个插件组合起来就能形成一条完整的流水线。我的配置是这样的security-scan插件负责安全维度的检查输出漏洞列表。style-check插件负责代码风格和规范检查。review-summary插件把前两者的输出汇总成一份审查报告。在 Claude Code 里依次执行/security-scan /style-check /review-summaryreview-summary的命令定义里会读取前两个命令的输出文件按统一格式合并。这种“分而治之”的思路比写一个巨型审查命令要好维护得多——安全规则变了只改 security-scan风格规范变了只改 style-check。我实测下来这条流水线在中等规模的项目约 5 万行代码上跑一次完整审查大约需要 3-5 分钟能发现 80% 以上的常见问题。剩下的 20% 需要人工判断的模型会明确标注“需要人工确认”不会强行给结论。4.2 场景二文档生成与同步知识工作者另一大痛点是文档和代码不同步。代码改了文档没改过两个月谁也不知道哪个是对的。用插件可以缓解这个问题doc-sync插件对比代码变更和文档变更找出可能过时的文档段落。changelog-gen插件根据 git 提交记录生成 changelog。readme-update插件检查 README 里的示例代码是否还能运行。doc-sync的实现思路是先用git diff找出本次变更涉及的文件和函数然后在文档里搜索这些函数名如果文档里提到了但内容没更新就标记为“可能过时”。这个逻辑不复杂但非常实用。我把它设成 pre-commit hook每次提交前自动跑一遍提醒我更新文档。4.3 场景三团队知识库的插件化封装团队里总有一些“只有老员工知道”的知识某个服务的部署流程、某个接口的调用注意事项、某个工具的配置方法。这些知识散落在 wiki、聊天记录和某人的脑子里新人上手成本很高。我的做法是建一个team-knowledge插件把这些知识做成 skillsdeploy-checklistskill部署前的检查清单。api-gotchasskill各接口的坑和注意事项。troubleshootingskill常见故障的排查步骤。新人装好这个插件后遇到问题时 Claude 会自动参考这些知识给出建议。比如新人问“订单服务部署后报 503 怎么办”Claude 会加载troubleshootingskill按里面记录的步骤引导排查。这个做法的好处是知识“活”了。以前写在 wiki 里的文档没人看现在集成到日常工具里用的时候自然就看到了。而且更新方便改一个 skill 文件所有人下次会话就生效。4.4 插件组合的配置管理插件装多了之后管理是个问题。我的经验是分三层管理层级位置内容更新频率用户级~/.claude/plugins/通用工具类插件低团队级内部 git 仓库团队规范类插件中项目级项目.claude/plugins/项目特有插件高用户级放那些跟具体项目无关的比如“Markdown 格式化”“JSON 校验”。团队级放代码规范、审查标准这类全团队统一的。项目级放这个项目特有的比如“这个项目的数据库 schema 说明”。更新时按层级来项目级改动最频繁直接改直接生效团队级走 PR 流程保证质量用户级基本不动装好就不管了。5. 常见问题与排查实录5.1 插件装了但不生效这是最常见的问题排查顺序如下检查 plugin.json 格式用jq . plugin.json验证 JSON 是否合法。我遇到过因为多了一个逗号导致整个插件加载失败的情况。检查目录结构commands/和skills/必须在 plugin.json 里正确声明且路径相对于插件根目录。检查命令文件名文件名就是命令名不能有空格或特殊字符。gen-api-doc.md对应/gen-api-doc。检查加载顺序用claude plugin list查看已加载插件确认你的插件在列表里。如果被同名插件覆盖了需要调整加载顺序或改命令名。提示Claude Code 启动时加--debug参数可以看到插件加载的详细日志排查加载问题非常有用。5.2 Slash Command 执行结果不符合预期模型没有按命令文件里的指令执行通常有三个原因。一是指令太模糊模型自由发挥。解决办法是把指令拆成明确的步骤每步都有可验证的输出。二是上下文太长指令被“淹没”了。这时候要把关键指令放在命令文件的开头并用加粗或列表突出。三是allowed-tools配置不对模型想调用某个工具但被拒绝了只能绕路走。我踩过的一个坑是命令里要求“读取所有相关文件”但allowed-tools只写了Read没写Grep模型没法搜索文件只能凭猜测回答。加上Grep之后就正常了。5.3 Skill 没有被自动加载Skill 的加载是模型根据任务判断的不是每次都会触发。如果发现 skill 没生效可以在命令里显式引用 skill 名称比如“请参考 code-review-standards skill 进行审查”。检查 skill 的description是否准确描述了适用场景描述太泛会导致模型判断不准。确认 skill 文件路径在 plugin.json 里正确声明。5.4 插件冲突与覆盖问题两个插件定义了同名命令时后加载的会覆盖先加载的。如果你发现某个命令的行为跟预期不符先用claude plugin list确认是否有同名命令被覆盖。解决办法要么改命令名要么调整插件加载顺序。我自己的命名习惯是给命令加前缀比如api-gen-doc、api-scan-security这样即使装了多个插件也不容易冲突。5.5 性能问题与优化建议插件装多了之后Claude Code 启动会变慢。主要原因是启动时要扫描所有插件的命令和 skill 文件。优化方法把不常用的插件禁用而不是卸载需要时再启用。命令文件尽量精简不要把大段参考文档塞进命令文件那部分应该放 skill。Hook 脚本要快超过 1 秒的脚本考虑改成异步或手动触发。我实测下来装 10 个左右的插件对启动速度影响在可接受范围内增加 1-2 秒超过 20 个就明显变慢了。所以插件要精选不要什么都装。5.6 常见问题速查表现象可能原因排查方法解决命令不显示plugin.json 格式错误jq . plugin.json修复 JSON命令执行无反应allowed-tools 缺工具查看 debug 日志补充工具声明输出格式不对命令指令模糊检查命令文件细化指令步骤skill 不生效description 不准确手动引用测试改 description启动变慢插件过多claude plugin list禁用不常用插件hook 不触发matcher 配置错误查看 hook 日志修正 matcher6. 插件开发的经验与边界6.1 什么该封装成插件不是所有东西都值得做成插件。我的判断标准是如果一个操作你每周至少做三次且每次的流程基本固定那就值得封装。反之一次性的、高度依赖具体上下文的操作写个临时提示词就够了。另外要考虑维护成本。插件是要长期维护的代码规范变了、工具升级了插件都得跟着改。如果某个流程本身还在快速迭代中过早封装反而会增加负担。我的做法是先用提示词跑一段时间等流程稳定了再封装成插件。6.2 插件粒度的把握一个插件应该只做一件事但要把这件事做完整。比如“API 文档生成”是一个合理的插件粒度它包含扫描路由、提取信息、生成文档、写入文件这一整套流程。而“读取文件”就不该单独做成插件它太底层了。我见过有人把一个插件的功能拆得太细结果用的时候要依次调用五六个命令体验很差。也见过有人把所有功能塞进一个插件结果命令列表长得找不到想要的。我的经验是一个插件对应一个完整的工作流命令数量控制在 3-7 个之间比较合适。6.3 版本管理与分发插件是要分发的所以版本管理很重要。我遵循的规则是主版本号命令名变更、输出格式不兼容变更时递增。次版本号新增命令或 skill 时递增。修订号修复 bug、调整提示词时递增。分发方式看场景。团队内部用 git 仓库成员通过claude plugin install git-url安装。公开分享可以发布到插件市场或者直接给一个压缩包。不管哪种方式README 里都要写清楚安装方法、依赖项和使用示例。6.4 安全审查不可跳过从外部安装插件前一定要审查它的内容。重点看三处allowed-tools是否声明了不必要的权限、hook 脚本是否执行了可疑操作、命令文件里是否有诱导模型泄露敏感信息的指令。我自己的审查清单是[ ] plugin.json 里的 author 和来源是否可信[ ] 所有命令的 allowed-tools 是否最小化[ ] hook 脚本是否只做声明的事情[ ] 是否有命令会读取或写入敏感路径[ ] 是否有命令会发起网络请求这套审查流程花不了几分钟但能避免很多风险。毕竟插件是运行在你本地环境里的权限给大了等于把家门钥匙交出去。6.5 持续迭代的思路插件不是写完就完了。我的做法是每次用完插件后花一分钟想想这次输出哪里不满意是提示词不够具体还是缺少某个检查项把这些记下来攒够几条就更新一版。另外要关注 Claude Code 本身的更新。新版本可能会引入新的插件能力比如新的 hook 事件类型、新的工具类型。及时跟进这些变化能让插件保持好用。我订阅了 Claude Code 的更新日志每次有新版本就看看有没有跟插件相关的改动。最后分享一个我个人的小习惯给每个插件写一个CHANGELOG.md记录每次改了什么、为什么改。过几个月回头看能快速回忆起当时的决策背景避免重复踩坑。这个习惯看起来麻烦但长期来看省的时间远超投入。