1. 从零认识 knowledge-work-plugins它到底解决什么问题第一次看到knowledge-work-plugins这个仓库名很多人会以为它又是一个“插件合集”点进去发现是一堆 Markdown 和 JSON 配置然后一脸懵地关掉。我最初也是这个反应。但真正把它跑起来、接到 Claude Code 里用了一周之后我才意识到这东西的价值不在“插件”两个字而在于它把知识工作者的重复性流程做成了可复用、可组合、可版本管理的模块。先说清楚它是什么。knowledge-work-plugins本质上是一套面向 Claude Code / Claude Cowork 的插件与斜杠命令slash commands集合用 Markdown 定义提示词逻辑用 JSON 定义元数据和依赖关系通过 Claude Code 的插件加载机制挂载到本地环境。装好之后你在 Claude Code 的交互界面里敲/就能看到一批新增的命令比如会议纪要整理、竞品调研、周报生成、需求拆解、文档摘要这类高频动作每个命令背后都是一段经过打磨的提示词工作流而不是你临时手打的那几句“帮我总结一下”。它能做什么简单讲它把“我每次都要跟 AI 重复描述一遍我要什么”这件事变成了“我敲一个命令参数一填结果就出来了”。对于每天要处理大量文档、会议、调研、写作的人来说这个差别是巨大的。你不需要每次都写一大段上下文也不需要记住某个复杂提示词的措辞插件把最佳实践固化下来了。适合谁参考三类人最值得看一是重度使用 Claude Code 做日常知识工作的人比如产品经理、研究员、咨询顾问、技术写作者二是想自己写插件但不知道从哪下手的开发者这个仓库就是最好的模板库三是团队里负责搭建 AI 工作流的人你可以直接 fork 一份改成自己团队的规范。我踩过的第一个坑就是以为装上就能用。实际上 Claude Code 的插件机制对目录结构、plugin.json字段、命令文件的 frontmatter 都有要求格式错一个字就加载失败而且报错信息相当含蓄。所以下面我会把结构、原理、实操、排错全部拆开讲尽量让你少走我走过的弯路。2. 插件机制的核心设计与选型逻辑2.1 为什么是 Markdown JSON而不是写代码很多人第一反应是插件不应该是写 TypeScript 或者 Python 吗为什么这个仓库里全是.md和.json这背后其实是一个很关键的选型判断。Claude Code 的插件系统设计哲学是**“提示词即逻辑”**。一个插件做的事情本质上是“接收用户输入 → 组装上下文 → 调用模型 → 返回结构化结果”。这个流程里真正决定质量的是提示词而不是代码。如果用传统编程语言写你反而要把提示词塞进字符串里可读性差、改起来痛苦、版本 diff 也难看。用 Markdown 写提示词就是正文frontmatter 里放元数据改一行就是改一行git diff 清清楚楚。JSON 则承担了“声明式配置”的角色。plugin.json里定义插件名、版本、作者、命令入口、依赖关系。这种声明式的好处是加载器可以快速校验不需要执行任何代码就能知道这个插件提供哪些命令、依赖什么环境。安全性和可预测性都更好。提示这种“Markdown 定义行为 JSON 定义结构”的模式在 Claude Code 生态里是主流做法。你如果自己写插件不要试图绕过它去写脚本除非你确实需要调用外部 API。2.2 斜杠命令的本质预置提示词模板斜杠命令slash commands这个词容易让人误解以为是什么高级功能。实际上它的本质非常朴素一个命令对应一个 Markdown 文件文件内容就是发给模型的提示词模板命令参数通过占位符注入。比如你有一个/weekly-report命令对应的文件可能是commands/weekly-report.md里面写着类似这样的结构--- description: 根据本周工作记录生成周报 arguments: - name: notes description: 本周的工作要点用换行分隔 required: true --- 请根据以下工作要点生成一份结构化的周报。 要求 1. 按项目分组 2. 每个项目下列出完成事项、进行中事项、风险 3. 语言简洁避免空话 工作要点 {{notes}}当你敲/weekly-report并粘贴内容后Claude Code 会把{{notes}}替换成你的输入整段发给模型。就这么简单。但正是这种简单让它极其灵活——你可以把任何重复性的提示词工作流固化成一个命令。2.3 插件与命令的层级关系这里有个容易混淆的点插件plugin和命令command不是一回事。一个插件可以包含多个命令插件是分发单位命令是使用单位。层级作用文件示例插件分发、版本管理、依赖声明plugin.json命令具体的一个斜杠命令commands/xxx.md资源命令引用的模板、数据resources/xxx.md配置用户级或项目级设置.claude/settings.json理解这个层级你在排错时就能快速定位是插件没加载plugin.json 问题还是命令没注册commands 目录问题还是命令执行出错提示词或参数问题。2.4 为什么选择本地加载而不是远程分发knowledge-work-plugins采用的是本地目录加载模式你需要把仓库克隆到本地然后在 Claude Code 配置里指向它。这个选择乍看不如“一键安装”方便但有几个实际好处。第一是可控性。知识工作涉及大量内部文档、会议记录、业务数据如果插件从远程拉取你很难审计它到底发了什么。本地加载意味着所有提示词你都能看到、能改。第二是可定制性。团队用的时候几乎一定要改。比如周报模板要符合公司格式调研模板要包含特定维度。本地加载让你直接改文件改完立即生效不需要等上游更新。第三是版本锁定。你可以把某个稳定版本 fork 到自己的仓库避免上游更新导致行为变化。对于依赖 AI 输出稳定性的工作流这一点很重要。3. 核心细节解析与实操要点3.1 目录结构一个都不能错插件的目录结构是有硬性约定的我第一次装失败就是因为把commands写成了command。标准结构大致如下knowledge-work-plugins/ ├── plugin.json ├── commands/ │ ├── weekly-report.md │ ├── meeting-notes.md │ └── research.md ├── resources/ │ └── templates/ └── README.mdplugin.json必须在根目录commands目录名必须复数每个命令文件必须是.md且带 frontmatter。这些看起来是小事但加载器不会给你友好提示只会静默跳过或者报一个模糊的错误。注意目录名大小写在 Linux 和 macOS 上敏感在 Windows 上不敏感。如果你在 Windows 上开发、在 Linux 上部署务必统一用小写。3.2 plugin.json 的关键字段plugin.json是插件的身份证字段不多但每个都有用。常见的字段包括{ name: knowledge-work-plugins, version: 1.0.0, description: 面向知识工作者的 Claude Code 插件集合, author: your-name, commands: [ commands/weekly-report.md, commands/meeting-notes.md ] }这里有个细节commands字段有的版本是自动扫描目录有的版本需要显式列出。我建议显式列出因为这样加载行为可预测不会因为多了一个临时文件就多出一个命令。版本号建议遵循语义化版本方便你后续做兼容性判断。3.3 命令文件的 frontmatter 规范每个命令文件的头部是 YAML frontmatter用---包裹。字段包括description、arguments、aliases等。description会显示在命令列表里写得好不好直接影响你记不记得住这个命令。arguments定义参数每个参数有name、description、required。参数在正文里用{{name}}引用。这里有个坑参数名不要用中文也不要用带空格的字符串否则替换会失败。--- description: 把零散会议记录整理成结构化纪要 arguments: - name: raw_notes description: 原始会议记录 required: true - name: attendees description: 参会人列表 required: false --- 请把以下会议记录整理成结构化纪要。 参会人{{attendees}} 原始记录 {{raw_notes}} 输出格式 - 会议主题 - 关键结论 - 待办事项负责人 截止时间 - 遗留问题3.4 参数注入的边界情况参数注入看起来简单但有几个边界情况必须处理。第一是多行输入如果你的参数是一大段文本用户粘贴进来会带换行Markdown 模板里要确保{{raw_notes}}独占一行否则可能被解析成列表项。第二是特殊字符如果输入里包含{{或}}可能被误认为占位符建议在提示词里加一句“以下内容按字面处理”。第三是空参数required: false的参数如果没填替换后会留下空白提示词里最好用条件语句处理比如“如果参会人未提供则忽略该行”。3.5 资源文件的引用方式有些命令需要引用外部模板比如一份固定的调研框架。这时候把模板放在resources/下在命令文件里用相对路径引用。但要注意Claude Code 不会自动把资源文件内容注入你需要在提示词里明确说“请参考 resources/templates/research-framework.md 的结构”或者用加载器支持的 include 语法不同版本支持情况不同建议先查文档。我个人的做法是能内联就内联。资源文件虽然整洁但增加了加载失败的风险。除非模板很长或者多个命令共用否则直接写在命令文件里更稳。4. 完整实操流程从克隆到跑通第一个命令4.1 环境准备与前置检查在动手之前先确认你的环境。你需要一个能正常运行的 Claude Code 环境无论是 CLI 还是桌面版。CLI 版本可以通过claude --version确认桌面版在设置里能看到版本号。插件机制在不同版本上行为有差异建议用较新的稳定版。然后确认你的工作目录。插件可以装在用户级目录对所有项目生效也可以装在项目级目录只对当前项目生效。我建议先装在项目级跑通了再考虑全局。项目级目录通常是项目根目录下的.claude/文件夹。# 确认 Claude Code 可用 claude --version # 进入你的项目目录 cd ~/projects/my-workspace # 确认 .claude 目录存在没有就创建 mkdir -p .claude/plugins4.2 克隆与放置插件把knowledge-work-plugins克隆到你选定的位置。注意不要克隆到.claude/plugins里面再嵌套一层加载器通常期望插件目录直接包含plugin.json。cd .claude/plugins git clone https://github.com/your-org/knowledge-work-plugins.git # 确认结构正确 ls knowledge-work-plugins/ # 应该看到 plugin.json commands/ resources/ README.md如果你是从压缩包解压的注意解压后可能多一层目录比如knowledge-work-plugins-main/需要把里面的内容移到正确位置。4.3 配置加载路径Claude Code 需要知道去哪里找插件。配置方式有两种一种是在.claude/settings.json里声明插件目录另一种是通过命令行参数指定。我推荐前者因为可版本管理。{ plugins: { directories: [ .claude/plugins/knowledge-work-plugins ] } }改完配置后重启 Claude Code 会话。注意是重启会话不是重开终端。插件加载发生在会话初始化阶段热重载支持有限。4.4 验证命令是否注册成功重启后在 Claude Code 交互界面里敲/应该能看到新增的命令列表。如果没看到先别急着改配置按下面的顺序排查确认plugin.json能被 JSON 解析器解析用python -m json.tool plugin.json验证确认commands目录下的文件都有合法的 frontmatter确认配置里的路径是相对项目根目录还是绝对路径两者行为不同查看 Claude Code 的日志输出通常会有加载失败的提示我遇到过一次是因为plugin.json里多了一个尾随逗号JSON 解析失败但加载器只报了一句“no plugins loaded”排查了半小时。4.5 跑通第一个命令以会议纪要为例选一个最简单的命令先跑通建立信心。会议纪要整理是个好选择因为输入输出都很直观。# 在 Claude Code 会话里 /meeting-notes # 然后按提示粘贴原始记录如果命令有参数Claude Code 会依次询问。填完后模型开始处理几秒到几十秒不等取决于输入长度。输出结果如果符合预期说明整条链路通了。提示第一次跑建议用一段短的、脱敏的测试数据不要直接上真实会议记录。确认行为符合预期后再用真实数据。4.6 参数传递的两种方式参数传递有两种方式交互式填写和命令行内联。交互式就是敲完命令后按提示输入适合长文本。内联是在命令后面直接跟参数适合短参数。/meeting-notes --attendees 张三,李四,王五内联方式对含空格的值需要引号包裹。如果你的参数经常是长文本建议用交互式避免 shell 转义问题。4.7 自定义命令的修改与生效改命令文件后需要重启会话才能生效。这一点和热重载的前端开发体验不同要有心理准备。改的时候建议小步走一次改一个地方改完立即验证否则出问题不知道是哪次改动导致的。如果你要新增命令在commands/下新建.md文件写好 frontmatter 和正文然后在plugin.json的commands数组里加上路径重启会话即可。5. 常见问题与排查技巧实录5.1 命令不显示从加载链路倒推命令不显示是最常见的问题排查要按链路顺序来不要跳步。下面这张表是我整理的排查顺序按优先级排列。排查项检查方法常见原因配置文件路径确认 settings.json 里的路径相对路径基准搞错plugin.json 合法性JSON 解析器验证尾随逗号、注释、BOMcommands 目录名ls 确认写成 command 或 Commands命令文件 frontmatter检查---包裹缺少结束的---会话是否重启完全退出再进只关了窗口没退进程版本兼容性查文档确认支持旧版本不支持插件我踩过最坑的一次是配置文件里用了~表示家目录但加载器不解析~导致路径无效。改成绝对路径或相对路径就好了。5.2 命令执行报错参数与提示词问题命令能显示但执行报错通常是参数注入或提示词本身的问题。常见表现是模型回复“我没有看到输入内容”或者输出一堆占位符。原因一般是参数名拼写不一致frontmatter 里叫raw_notes正文里写成rawNotes或者参数没传但正文里强制引用。解决方法是在提示词开头加一段防御性说明比如“如果某个参数为空请忽略相关部分并继续”。还有一种情况是输入内容太长超出上下文窗口。这时候要么分段处理要么在命令里加一句“如果输入超过 X 字请先摘要再处理”。5.3 输出格式不稳定提示词约束技巧同一个命令有时候输出很规整有时候格式乱掉。这是提示词工程的经典问题。解决办法是把格式要求写得极其具体最好给出示例。不要写“输出结构化的结果”要写“输出必须包含以下四个二级标题会议主题、关键结论、待办事项、遗留问题。待办事项用无序列表每项格式为‘负责人 - 事项 - 截止时间’”。约束越具体输出越稳定。另外可以在提示词末尾加一句“不要添加任何额外的解释性文字直接输出结果”减少模型自由发挥。5.4 插件冲突同名命令的处理如果你装了多个插件可能出现同名命令。Claude Code 的处理策略通常是后加载的覆盖先加载的或者直接报冲突。避免冲突的方法是给命令加前缀比如kw-weekly-reportkw代表 knowledge work。虽然敲起来多几个字符但能避免很多麻烦。5.5 性能问题长提示词的加载开销插件多了之后会话启动会变慢因为加载器要读取所有命令文件。如果你的命令文件里有很长的提示词启动开销会更明显。优化方法是把长模板拆到 resources 里按需加载或者精简提示词去掉冗余描述。我实测下来20 个命令以内的插件启动开销基本无感。超过 50 个命令启动会明显变慢。所以不要什么都做成命令只把真正高频的固化下来。5.6 版本升级后的兼容性处理上游更新后你的本地修改可能冲突。建议的做法是fork 一份到自己的仓库把上游设为 remote需要更新时先看 changelog再决定是否 merge。不要直接在上游仓库上改否则更新时很痛苦。如果你只是改了提示词可以把改动记录在一个单独的 patch 文件里更新后重新应用。虽然土但有效。6. 进阶玩法把插件变成团队工作流6.1 团队共享的插件仓库组织方式一个人用和团队用组织方式完全不同。团队用的时候我建议按职能分目录而不是按命令类型分。比如commands/pm/放产品经理用的commands/research/放研究员用的。这样每个人只需要关注自己那部分也方便做权限控制。plugin.json里可以按职能分组声明虽然加载器不一定支持分组显示但至少文件组织清晰。6.2 结合项目上下文做定制插件命令可以引用项目里的文件比如CLAUDE.md或者项目规范文档。这样命令的输出就能自动符合项目约定。比如周报命令里加一句“请参考项目根目录的 CLAUDE.md 中的术语表”输出就会用团队统一的术语。这个玩法很实用但要注意文件路径的稳定性。如果项目结构变了命令就失效了。建议把引用的文件路径写在一个配置里命令里引用配置变量。6.3 命令组合把多个命令串成工作流单个命令解决单点问题组合起来能解决流程问题。比如“会议纪要 → 待办提取 → 周报汇总”可以串成一条链。Claude Code 本身不一定支持命令链但你可以写一个“元命令”在提示词里引导模型依次执行多个步骤。我的做法是写一个/weekly-digest命令输入是一周的会议纪要合集提示词里明确要求“先提取每个会议的待办再按项目汇总最后生成周报”。这样一次调用完成三步比手动跑三次命令高效。6.4 用 git 管理提示词版本提示词是要迭代的。今天觉得输出不错下周可能发现某个场景下不行需要调整。用 git 管理每次改动都有记录出问题能回滚。建议 commit message 写清楚“改了什么、为什么改、解决了什么场景”三个月后你还能看懂。6.5 提示词迭代的评估方法怎么判断一次改动是变好还是变坏我的方法是建一个测试集。挑 5 到 10 个有代表性的输入每次改完提示词都跑一遍对比输出。不用很正式一个 Markdown 文件记录输入和期望输出要点就行。这样能避免“改了一个场景坏了三个场景”的情况。7. 我个人的实操心得用这套插件大概三个月最大的体会是插件的价值不在于省那几秒钟打字时间而在于把“怎么做”这件事标准化了。以前每个人用 AI 的方式都不一样输出质量参差不齐。现在把好的提示词固化成命令团队里所有人敲同一个命令输出质量的下限就被抬高了。另一个体会是不要贪多。我一开始想把所有重复动作都做成命令结果命令列表长到记不住反而降低了使用频率。后来砍到 8 个真正高频的每个都打磨得很顺使用率反而上去了。插件这东西少而精比多而杂有用得多。最后一个技巧给命令写清楚 description。这个字段会显示在命令列表里是你未来唯一能快速识别命令用途的线索。我见过太多人 description 写“处理文档”三个月后自己都不知道这个命令具体处理什么。写具体点比如“把会议录音转写文本整理成带待办的纪要”一眼就懂。如果你刚开始接触建议先从仓库里挑一个最贴近你日常工作的命令跑通、改顺、用一周再考虑扩展。别一上来就 fork 改一堆那样大概率是改完就放着吃灰。 
长河君 · 2026/10/18 22:17:26 · 阅读 1.2k Claude Code knowledge-work-plugins 插件机制与斜杠命令实战指南
1. 从零认识 knowledge-work-plugins它到底解决什么问题第一次看到knowledge-work-plugins这个仓库名很多人会以为它又是一个“插件合集”点进去发现是一堆 Markdown 和 JSON 配置然后一脸懵地关掉。我最初也是这个反应。但真正把它跑起来、接到 Claude Code 里用了一周之后我才意识到这东西的价值不在“插件”两个字而在于它把知识工作者的重复性流程做成了可复用、可组合、可版本管理的模块。先说清楚它是什么。knowledge-work-plugins本质上是一套面向 Claude Code / Claude Cowork 的插件与斜杠命令slash commands集合用 Markdown 定义提示词逻辑用 JSON 定义元数据和依赖关系通过 Claude Code 的插件加载机制挂载到本地环境。装好之后你在 Claude Code 的交互界面里敲/就能看到一批新增的命令比如会议纪要整理、竞品调研、周报生成、需求拆解、文档摘要这类高频动作每个命令背后都是一段经过打磨的提示词工作流而不是你临时手打的那几句“帮我总结一下”。它能做什么简单讲它把“我每次都要跟 AI 重复描述一遍我要什么”这件事变成了“我敲一个命令参数一填结果就出来了”。对于每天要处理大量文档、会议、调研、写作的人来说这个差别是巨大的。你不需要每次都写一大段上下文也不需要记住某个复杂提示词的措辞插件把最佳实践固化下来了。适合谁参考三类人最值得看一是重度使用 Claude Code 做日常知识工作的人比如产品经理、研究员、咨询顾问、技术写作者二是想自己写插件但不知道从哪下手的开发者这个仓库就是最好的模板库三是团队里负责搭建 AI 工作流的人你可以直接 fork 一份改成自己团队的规范。我踩过的第一个坑就是以为装上就能用。实际上 Claude Code 的插件机制对目录结构、plugin.json字段、命令文件的 frontmatter 都有要求格式错一个字就加载失败而且报错信息相当含蓄。所以下面我会把结构、原理、实操、排错全部拆开讲尽量让你少走我走过的弯路。2. 插件机制的核心设计与选型逻辑2.1 为什么是 Markdown JSON而不是写代码很多人第一反应是插件不应该是写 TypeScript 或者 Python 吗为什么这个仓库里全是.md和.json这背后其实是一个很关键的选型判断。Claude Code 的插件系统设计哲学是**“提示词即逻辑”**。一个插件做的事情本质上是“接收用户输入 → 组装上下文 → 调用模型 → 返回结构化结果”。这个流程里真正决定质量的是提示词而不是代码。如果用传统编程语言写你反而要把提示词塞进字符串里可读性差、改起来痛苦、版本 diff 也难看。用 Markdown 写提示词就是正文frontmatter 里放元数据改一行就是改一行git diff 清清楚楚。JSON 则承担了“声明式配置”的角色。plugin.json里定义插件名、版本、作者、命令入口、依赖关系。这种声明式的好处是加载器可以快速校验不需要执行任何代码就能知道这个插件提供哪些命令、依赖什么环境。安全性和可预测性都更好。提示这种“Markdown 定义行为 JSON 定义结构”的模式在 Claude Code 生态里是主流做法。你如果自己写插件不要试图绕过它去写脚本除非你确实需要调用外部 API。2.2 斜杠命令的本质预置提示词模板斜杠命令slash commands这个词容易让人误解以为是什么高级功能。实际上它的本质非常朴素一个命令对应一个 Markdown 文件文件内容就是发给模型的提示词模板命令参数通过占位符注入。比如你有一个/weekly-report命令对应的文件可能是commands/weekly-report.md里面写着类似这样的结构--- description: 根据本周工作记录生成周报 arguments: - name: notes description: 本周的工作要点用换行分隔 required: true --- 请根据以下工作要点生成一份结构化的周报。 要求 1. 按项目分组 2. 每个项目下列出完成事项、进行中事项、风险 3. 语言简洁避免空话 工作要点 {{notes}}当你敲/weekly-report并粘贴内容后Claude Code 会把{{notes}}替换成你的输入整段发给模型。就这么简单。但正是这种简单让它极其灵活——你可以把任何重复性的提示词工作流固化成一个命令。2.3 插件与命令的层级关系这里有个容易混淆的点插件plugin和命令command不是一回事。一个插件可以包含多个命令插件是分发单位命令是使用单位。层级作用文件示例插件分发、版本管理、依赖声明plugin.json命令具体的一个斜杠命令commands/xxx.md资源命令引用的模板、数据resources/xxx.md配置用户级或项目级设置.claude/settings.json理解这个层级你在排错时就能快速定位是插件没加载plugin.json 问题还是命令没注册commands 目录问题还是命令执行出错提示词或参数问题。2.4 为什么选择本地加载而不是远程分发knowledge-work-plugins采用的是本地目录加载模式你需要把仓库克隆到本地然后在 Claude Code 配置里指向它。这个选择乍看不如“一键安装”方便但有几个实际好处。第一是可控性。知识工作涉及大量内部文档、会议记录、业务数据如果插件从远程拉取你很难审计它到底发了什么。本地加载意味着所有提示词你都能看到、能改。第二是可定制性。团队用的时候几乎一定要改。比如周报模板要符合公司格式调研模板要包含特定维度。本地加载让你直接改文件改完立即生效不需要等上游更新。第三是版本锁定。你可以把某个稳定版本 fork 到自己的仓库避免上游更新导致行为变化。对于依赖 AI 输出稳定性的工作流这一点很重要。3. 核心细节解析与实操要点3.1 目录结构一个都不能错插件的目录结构是有硬性约定的我第一次装失败就是因为把commands写成了command。标准结构大致如下knowledge-work-plugins/ ├── plugin.json ├── commands/ │ ├── weekly-report.md │ ├── meeting-notes.md │ └── research.md ├── resources/ │ └── templates/ └── README.mdplugin.json必须在根目录commands目录名必须复数每个命令文件必须是.md且带 frontmatter。这些看起来是小事但加载器不会给你友好提示只会静默跳过或者报一个模糊的错误。注意目录名大小写在 Linux 和 macOS 上敏感在 Windows 上不敏感。如果你在 Windows 上开发、在 Linux 上部署务必统一用小写。3.2 plugin.json 的关键字段plugin.json是插件的身份证字段不多但每个都有用。常见的字段包括{ name: knowledge-work-plugins, version: 1.0.0, description: 面向知识工作者的 Claude Code 插件集合, author: your-name, commands: [ commands/weekly-report.md, commands/meeting-notes.md ] }这里有个细节commands字段有的版本是自动扫描目录有的版本需要显式列出。我建议显式列出因为这样加载行为可预测不会因为多了一个临时文件就多出一个命令。版本号建议遵循语义化版本方便你后续做兼容性判断。3.3 命令文件的 frontmatter 规范每个命令文件的头部是 YAML frontmatter用---包裹。字段包括description、arguments、aliases等。description会显示在命令列表里写得好不好直接影响你记不记得住这个命令。arguments定义参数每个参数有name、description、required。参数在正文里用{{name}}引用。这里有个坑参数名不要用中文也不要用带空格的字符串否则替换会失败。--- description: 把零散会议记录整理成结构化纪要 arguments: - name: raw_notes description: 原始会议记录 required: true - name: attendees description: 参会人列表 required: false --- 请把以下会议记录整理成结构化纪要。 参会人{{attendees}} 原始记录 {{raw_notes}} 输出格式 - 会议主题 - 关键结论 - 待办事项负责人 截止时间 - 遗留问题3.4 参数注入的边界情况参数注入看起来简单但有几个边界情况必须处理。第一是多行输入如果你的参数是一大段文本用户粘贴进来会带换行Markdown 模板里要确保{{raw_notes}}独占一行否则可能被解析成列表项。第二是特殊字符如果输入里包含{{或}}可能被误认为占位符建议在提示词里加一句“以下内容按字面处理”。第三是空参数required: false的参数如果没填替换后会留下空白提示词里最好用条件语句处理比如“如果参会人未提供则忽略该行”。3.5 资源文件的引用方式有些命令需要引用外部模板比如一份固定的调研框架。这时候把模板放在resources/下在命令文件里用相对路径引用。但要注意Claude Code 不会自动把资源文件内容注入你需要在提示词里明确说“请参考 resources/templates/research-framework.md 的结构”或者用加载器支持的 include 语法不同版本支持情况不同建议先查文档。我个人的做法是能内联就内联。资源文件虽然整洁但增加了加载失败的风险。除非模板很长或者多个命令共用否则直接写在命令文件里更稳。4. 完整实操流程从克隆到跑通第一个命令4.1 环境准备与前置检查在动手之前先确认你的环境。你需要一个能正常运行的 Claude Code 环境无论是 CLI 还是桌面版。CLI 版本可以通过claude --version确认桌面版在设置里能看到版本号。插件机制在不同版本上行为有差异建议用较新的稳定版。然后确认你的工作目录。插件可以装在用户级目录对所有项目生效也可以装在项目级目录只对当前项目生效。我建议先装在项目级跑通了再考虑全局。项目级目录通常是项目根目录下的.claude/文件夹。# 确认 Claude Code 可用 claude --version # 进入你的项目目录 cd ~/projects/my-workspace # 确认 .claude 目录存在没有就创建 mkdir -p .claude/plugins4.2 克隆与放置插件把knowledge-work-plugins克隆到你选定的位置。注意不要克隆到.claude/plugins里面再嵌套一层加载器通常期望插件目录直接包含plugin.json。cd .claude/plugins git clone https://github.com/your-org/knowledge-work-plugins.git # 确认结构正确 ls knowledge-work-plugins/ # 应该看到 plugin.json commands/ resources/ README.md如果你是从压缩包解压的注意解压后可能多一层目录比如knowledge-work-plugins-main/需要把里面的内容移到正确位置。4.3 配置加载路径Claude Code 需要知道去哪里找插件。配置方式有两种一种是在.claude/settings.json里声明插件目录另一种是通过命令行参数指定。我推荐前者因为可版本管理。{ plugins: { directories: [ .claude/plugins/knowledge-work-plugins ] } }改完配置后重启 Claude Code 会话。注意是重启会话不是重开终端。插件加载发生在会话初始化阶段热重载支持有限。4.4 验证命令是否注册成功重启后在 Claude Code 交互界面里敲/应该能看到新增的命令列表。如果没看到先别急着改配置按下面的顺序排查确认plugin.json能被 JSON 解析器解析用python -m json.tool plugin.json验证确认commands目录下的文件都有合法的 frontmatter确认配置里的路径是相对项目根目录还是绝对路径两者行为不同查看 Claude Code 的日志输出通常会有加载失败的提示我遇到过一次是因为plugin.json里多了一个尾随逗号JSON 解析失败但加载器只报了一句“no plugins loaded”排查了半小时。4.5 跑通第一个命令以会议纪要为例选一个最简单的命令先跑通建立信心。会议纪要整理是个好选择因为输入输出都很直观。# 在 Claude Code 会话里 /meeting-notes # 然后按提示粘贴原始记录如果命令有参数Claude Code 会依次询问。填完后模型开始处理几秒到几十秒不等取决于输入长度。输出结果如果符合预期说明整条链路通了。提示第一次跑建议用一段短的、脱敏的测试数据不要直接上真实会议记录。确认行为符合预期后再用真实数据。4.6 参数传递的两种方式参数传递有两种方式交互式填写和命令行内联。交互式就是敲完命令后按提示输入适合长文本。内联是在命令后面直接跟参数适合短参数。/meeting-notes --attendees 张三,李四,王五内联方式对含空格的值需要引号包裹。如果你的参数经常是长文本建议用交互式避免 shell 转义问题。4.7 自定义命令的修改与生效改命令文件后需要重启会话才能生效。这一点和热重载的前端开发体验不同要有心理准备。改的时候建议小步走一次改一个地方改完立即验证否则出问题不知道是哪次改动导致的。如果你要新增命令在commands/下新建.md文件写好 frontmatter 和正文然后在plugin.json的commands数组里加上路径重启会话即可。5. 常见问题与排查技巧实录5.1 命令不显示从加载链路倒推命令不显示是最常见的问题排查要按链路顺序来不要跳步。下面这张表是我整理的排查顺序按优先级排列。排查项检查方法常见原因配置文件路径确认 settings.json 里的路径相对路径基准搞错plugin.json 合法性JSON 解析器验证尾随逗号、注释、BOMcommands 目录名ls 确认写成 command 或 Commands命令文件 frontmatter检查---包裹缺少结束的---会话是否重启完全退出再进只关了窗口没退进程版本兼容性查文档确认支持旧版本不支持插件我踩过最坑的一次是配置文件里用了~表示家目录但加载器不解析~导致路径无效。改成绝对路径或相对路径就好了。5.2 命令执行报错参数与提示词问题命令能显示但执行报错通常是参数注入或提示词本身的问题。常见表现是模型回复“我没有看到输入内容”或者输出一堆占位符。原因一般是参数名拼写不一致frontmatter 里叫raw_notes正文里写成rawNotes或者参数没传但正文里强制引用。解决方法是在提示词开头加一段防御性说明比如“如果某个参数为空请忽略相关部分并继续”。还有一种情况是输入内容太长超出上下文窗口。这时候要么分段处理要么在命令里加一句“如果输入超过 X 字请先摘要再处理”。5.3 输出格式不稳定提示词约束技巧同一个命令有时候输出很规整有时候格式乱掉。这是提示词工程的经典问题。解决办法是把格式要求写得极其具体最好给出示例。不要写“输出结构化的结果”要写“输出必须包含以下四个二级标题会议主题、关键结论、待办事项、遗留问题。待办事项用无序列表每项格式为‘负责人 - 事项 - 截止时间’”。约束越具体输出越稳定。另外可以在提示词末尾加一句“不要添加任何额外的解释性文字直接输出结果”减少模型自由发挥。5.4 插件冲突同名命令的处理如果你装了多个插件可能出现同名命令。Claude Code 的处理策略通常是后加载的覆盖先加载的或者直接报冲突。避免冲突的方法是给命令加前缀比如kw-weekly-reportkw代表 knowledge work。虽然敲起来多几个字符但能避免很多麻烦。5.5 性能问题长提示词的加载开销插件多了之后会话启动会变慢因为加载器要读取所有命令文件。如果你的命令文件里有很长的提示词启动开销会更明显。优化方法是把长模板拆到 resources 里按需加载或者精简提示词去掉冗余描述。我实测下来20 个命令以内的插件启动开销基本无感。超过 50 个命令启动会明显变慢。所以不要什么都做成命令只把真正高频的固化下来。5.6 版本升级后的兼容性处理上游更新后你的本地修改可能冲突。建议的做法是fork 一份到自己的仓库把上游设为 remote需要更新时先看 changelog再决定是否 merge。不要直接在上游仓库上改否则更新时很痛苦。如果你只是改了提示词可以把改动记录在一个单独的 patch 文件里更新后重新应用。虽然土但有效。6. 进阶玩法把插件变成团队工作流6.1 团队共享的插件仓库组织方式一个人用和团队用组织方式完全不同。团队用的时候我建议按职能分目录而不是按命令类型分。比如commands/pm/放产品经理用的commands/research/放研究员用的。这样每个人只需要关注自己那部分也方便做权限控制。plugin.json里可以按职能分组声明虽然加载器不一定支持分组显示但至少文件组织清晰。6.2 结合项目上下文做定制插件命令可以引用项目里的文件比如CLAUDE.md或者项目规范文档。这样命令的输出就能自动符合项目约定。比如周报命令里加一句“请参考项目根目录的 CLAUDE.md 中的术语表”输出就会用团队统一的术语。这个玩法很实用但要注意文件路径的稳定性。如果项目结构变了命令就失效了。建议把引用的文件路径写在一个配置里命令里引用配置变量。6.3 命令组合把多个命令串成工作流单个命令解决单点问题组合起来能解决流程问题。比如“会议纪要 → 待办提取 → 周报汇总”可以串成一条链。Claude Code 本身不一定支持命令链但你可以写一个“元命令”在提示词里引导模型依次执行多个步骤。我的做法是写一个/weekly-digest命令输入是一周的会议纪要合集提示词里明确要求“先提取每个会议的待办再按项目汇总最后生成周报”。这样一次调用完成三步比手动跑三次命令高效。6.4 用 git 管理提示词版本提示词是要迭代的。今天觉得输出不错下周可能发现某个场景下不行需要调整。用 git 管理每次改动都有记录出问题能回滚。建议 commit message 写清楚“改了什么、为什么改、解决了什么场景”三个月后你还能看懂。6.5 提示词迭代的评估方法怎么判断一次改动是变好还是变坏我的方法是建一个测试集。挑 5 到 10 个有代表性的输入每次改完提示词都跑一遍对比输出。不用很正式一个 Markdown 文件记录输入和期望输出要点就行。这样能避免“改了一个场景坏了三个场景”的情况。7. 我个人的实操心得用这套插件大概三个月最大的体会是插件的价值不在于省那几秒钟打字时间而在于把“怎么做”这件事标准化了。以前每个人用 AI 的方式都不一样输出质量参差不齐。现在把好的提示词固化成命令团队里所有人敲同一个命令输出质量的下限就被抬高了。另一个体会是不要贪多。我一开始想把所有重复动作都做成命令结果命令列表长到记不住反而降低了使用频率。后来砍到 8 个真正高频的每个都打磨得很顺使用率反而上去了。插件这东西少而精比多而杂有用得多。最后一个技巧给命令写清楚 description。这个字段会显示在命令列表里是你未来唯一能快速识别命令用途的线索。我见过太多人 description 写“处理文档”三个月后自己都不知道这个命令具体处理什么。写具体点比如“把会议录音转写文本整理成带待办的纪要”一眼就懂。如果你刚开始接触建议先从仓库里挑一个最贴近你日常工作的命令跑通、改顺、用一周再考虑扩展。别一上来就 fork 改一堆那样大概率是改完就放着吃灰。