★ FEATURED ARTICLE 1. 从零认识 knowledge-work-plugins它到底解决什么问题第一次看到knowledge-work-plugins这个仓库名很多人会下意识以为它又是一个“插件市场”或者“扩展合集”。但真正翻过它的目录结构、跑过几个 slash commands 之后你会发现它的定位要具体得多——它是一套面向知识工作者的 Claude Code 插件集合把日常重复性的文档处理、信息整理、结构化输出这些动作封装成可以直接调用的命令。说白了它做的事情就是把你每天在终端里跟 Claude Code 反复敲的那些提示词变成一个个有名字、有参数、可复用的 slash commands。比如你经常需要把一段会议记录整理成行动项或者把一堆零散笔记归纳成周报以前你得每次重新描述需求现在直接/一下就行。这个项目适合谁三类人最值得花时间研究。第一类是已经在用 Claude Code 但还在“手搓提示词”阶段的开发者你会发现自己写的很多 prompt 其实可以固化下来第二类是需要处理大量文本信息的知识工作者比如产品经理、研究员、技术写作者第三类是喜欢折腾工具链、想把 AI 助手改造成自己专属工作流的人。核心关键词里出现的Claude Cowork、Claude Code、plugins、slash commands其实已经把这个项目的技术底座说清楚了——它跑在 Claude Code 之上用插件机制扩展能力用 slash commands 作为交互入口。理解这三层关系是读懂整个项目的前提。我自己的使用感受是这类插件集合的价值不在于“功能多”而在于“约定清晰”。它给你一套目录规范和命名习惯你照着填内容就行不用每次从空白文件开始想结构。接下来我会把这套东西拆开从设计思路到实操落地一步步讲清楚。2. 整体设计思路与目录结构拆解2.1 为什么用插件而不是一个大脚本很多人第一反应是我写一个 Python 脚本把所有功能塞进去不就行了为什么要搞成插件目录这个问题我在早期也纠结过后来实际用下来才明白差异在哪。插件机制的核心优势是隔离与可组合。每个插件是一个独立目录有自己的命令定义、自己的提示词模板、自己的配置。你改一个插件不会影响另一个删掉一个插件也不会留下残留。而一个大脚本的问题是功能越多耦合越重改一处经常牵动全身。另一个关键点是加载时机。Claude Code 启动时会扫描插件目录把可用的 slash commands 注册进来。这意味着你新增一个插件不需要重启整个工具链只要目录结构对命令就能被识别。这种“即插即用”的体验是大脚本很难做到的。还有一点容易被忽略插件天然适合分享。你可以把自己写好的插件目录直接打包发给同事对方放到对应位置就能用。而脚本分享往往还要处理依赖、路径、环境变量一堆事。2.2 目录结构的约定与含义一个典型的 knowledge-work-plugins 插件目录大致长这样plugins/ meeting-notes/ plugin.json commands/ summarize.md extract-actions.md prompts/ base.md weekly-report/ plugin.json commands/ generate.md这里有几个关键约定需要说清楚。plugin.json是插件的元信息文件里面通常包含插件名、版本、描述、作者这些字段。Claude Code 靠它来识别这是一个合法插件。commands/目录下每个.md文件对应一个 slash command。文件名就是命令名比如summarize.md对应/summarize。文件内容是提示词模板可以包含变量占位符。prompts/目录放的是可复用的提示词片段。比如多个命令都需要“你是一个专业的技术写作者”这样的角色设定就可以抽出来放这里命令文件里引用它。注意目录名和文件名尽量用英文小写加连字符避免空格和特殊字符。我踩过一次坑用中文命名目录结果在某些终端环境下路径解析出问题排查了半天。2.3 与 Claude Code 的加载机制配合Claude Code 启动时会按顺序做几件事先读取全局配置确定插件搜索路径然后扫描路径下的所有目录找plugin.json找到后解析元信息注册命令最后在交互界面里把这些命令挂到/菜单下。这个流程意味着两件事。第一你的插件目录必须放在 Claude Code 能扫描到的位置通常是配置里指定的plugins目录或者用户主目录下的某个约定路径。第二plugin.json格式必须正确哪怕少一个逗号整个插件都不会被加载。我建议的做法是先放一个最小可用的插件进去确认能被识别再逐步加功能。不要一上来就写五个命令最后发现一个都加载不了排查起来很痛苦。3. 核心细节解析与实操要点3.1 plugin.json 的字段设计与常见坑plugin.json看起来简单但字段设计有几个细节直接影响使用体验。一个比较完整的例子{ name: meeting-notes, version: 1.0.0, description: 把会议记录整理成结构化摘要和行动项, author: your-name, commands: [summarize, extract-actions], keywords: [meeting, notes, summary] }name字段建议和目录名保持一致避免混淆。commands数组列出这个插件提供的所有命令虽然 Claude Code 也会扫描commands/目录但显式声明能让加载更可靠。description不要写得太泛比如“一个有用的插件”这种等于没写。好的描述应该让人一眼知道这个插件解决什么具体问题。常见坑有两个。一是 JSON 不支持注释很多人习惯性加//注释导致解析失败。二是版本号格式虽然不强制语义化版本但建议遵循主版本.次版本.修订号的惯例方便后续管理。3.2 命令文件的提示词模板写法命令文件是整个插件的灵魂。它本质上是一个 Markdown 文件里面写的是发给 Claude 的提示词。但和普通提示词不同的是它可以包含变量占位符运行时会被替换成用户输入。一个summarize.md的例子你是一个专业的会议记录整理助手。 请把下面的会议记录整理成三部分 1. 核心结论不超过5条 2. 待办事项每条包含负责人和截止时间 3. 遗留问题需要后续讨论的 会议记录内容 {{input}}{{input}}就是占位符用户执行/summarize后跟的内容会填到这里。有些实现还支持{{file}}这样的占位符用来读取文件内容。写提示词模板有几个实操心得。第一角色设定要具体。“你是一个助手”不如“你是一个有十年经验的项目管理助理”。第二输出格式要明确。用编号列表、表格还是 JSON提前说清楚不然每次输出格式都不一样。第三约束条件要写死。“不超过5条”比“尽量简洁”有效得多。提示提示词模板里不要写太长的背景介绍Claude Code 本身有系统提示词你只需要补充任务特定的部分。写太长反而稀释了关键指令。3.3 变量传递与上下文注入knowledge-work-plugins 的一个实用特性是支持上下文注入。也就是说命令执行时不仅能拿到用户直接输入的内容还能拿到当前工作目录的一些信息比如文件列表、git 状态等。这个机制的价值在于你可以写出“感知环境”的命令。比如一个/review-changes命令可以自动读取当前 git diff然后让 Claude 做代码审查。用户不需要手动复制粘贴 diff 内容。实现上通常是在命令文件里用特定的占位符比如{{git_diff}}、{{file_list}}。Claude Code 在执行命令前会先收集这些信息替换占位符再发给模型。这里有个注意事项上下文注入的内容可能很大比如一个大型项目的文件列表。如果全部塞进提示词可能超出模型的上下文窗口。我的做法是加过滤条件比如只注入最近修改的文件或者只注入特定扩展名的文件。3.4 命令命名与参数设计命令名尽量用动词开头让人一看就知道是干什么的。/summarize、/extract、/generate这种就比/notes、/report更清晰。参数设计上Claude Code 的 slash commands 通常支持两种模式一种是直接跟自然语言比如/summarize 今天开了个会讨论了...另一种是跟文件路径比如/summarize ./meeting.md。我建议在命令文件里对两种模式都做兼容处理。比如先判断输入是不是一个存在的文件路径如果是就读取文件内容否则当作纯文本处理。这样用户用起来更灵活。还有一个技巧是默认行为设计。如果用户执行命令时没给任何输入应该怎么办是报错提示还是读取剪贴板还是读取当前目录的某个约定文件提前想清楚能减少很多“命令没反应”的困惑。4. 实操过程与核心环节实现4.1 环境准备与 Claude Code 安装确认在动手写插件之前先确认 Claude Code 本身能正常工作。安装方式根据操作系统不同有差异常见的是通过包管理器或者官方提供的安装脚本。安装完成后在终端执行claude命令应该能看到欢迎信息和版本号。如果提示无法连接服务先检查网络配置和账号状态这一步不通过后面插件调试无从谈起。确认 Claude Code 可用后找到它的配置目录。通常在用户主目录下比如~/.claude/或者~/.config/claude/。插件目录一般在这个配置目录下的plugins/子目录里。如果不存在手动创建。注意不同版本的 Claude Code 配置路径可能不同建议先查阅当前版本的文档或者执行claude --help看有没有相关参数说明。我遇到过版本升级后路径变化的情况旧插件突然不加载了就是因为这个。4.2 创建第一个插件从最小可用开始不要一上来就搞复杂插件。先创建一个只有一个命令的插件跑通整个流程。第一步在插件目录下新建文件夹hello-plugin。第二步在里面创建plugin.json{ name: hello-plugin, version: 0.1.0, description: 测试插件加载的最小示例, commands: [hello] }第三步创建commands/hello.md你是一个友好的助手。 请用一句话回应下面的输入并在结尾加上“插件测试成功”。 输入{{input}}第四步重启 Claude Code 或者执行重新加载命令。然后在交互界面输入/hello 测试如果能看到带有“插件测试成功”的回复说明整个链路通了。这个最小示例的价值在于它把变量替换、命令注册、提示词执行三个环节都覆盖了。后面加功能只是在这个基础上扩展不会遇到全新的问题。4.3 实现一个实用的会议记录整理插件跑通最小示例后我们来做一个真正有用的插件。假设你经常需要整理会议记录目标是输入原始记录输出结构化摘要。目录结构meeting-notes/ plugin.json commands/ summarize.md extract-actions.md prompts/ role.mdplugin.json{ name: meeting-notes, version: 1.0.0, description: 会议记录整理摘要生成与行动项提取, commands: [summarize, extract-actions] }prompts/role.md放公共角色设定你是一个有十年经验的项目管理助理擅长从杂乱的会议记录中提取关键信息。 你的输出必须简洁、结构化、可执行。commands/summarize.md引用角色设定并定义任务{{include: prompts/role.md}} 任务把下面的会议记录整理成结构化摘要。 输出格式 ## 核心结论 - 结论1 - 结论2 ## 待办事项 | 事项 | 负责人 | 截止时间 | |------|--------|----------| ## 遗留问题 - 问题1 会议记录 {{input}}commands/extract-actions.md专注行动项提取{{include: prompts/role.md}} 任务只提取下面会议记录中的行动项忽略其他内容。 输出格式每条行动项一行格式为“负责人 - 事项 - 截止时间”。 会议记录 {{input}}这里用到了{{include: ...}}语法来引用公共提示词片段。不同实现可能语法不同有的用{{ prompts/role.md}}具体看文档。核心思路是把重复内容抽出来改一处全局生效。4.4 参数计算与输入处理逻辑虽然插件主要是提示词工程但输入处理逻辑直接影响使用体验。以会议记录整理为例输入可能有几种形态直接粘贴的文本、一个 Markdown 文件路径、一个纯文本文件路径。我通常会在命令文件开头加一段判断逻辑虽然 Claude 本身能理解自然语言但明确指令更可靠首先判断输入类型 - 如果输入是一个存在的文件路径读取文件内容作为会议记录 - 否则把输入直接当作会议记录文本 然后执行整理任务。这种写法利用了 Claude 的理解能力不需要写真正的代码。实测下来对于常见路径格式识别准确率很高。另一个细节是长文本处理。如果会议记录特别长比如超过几千字直接塞进提示词可能导致输出质量下降。我的做法是在命令里加一句“如果输入超过2000字先分段处理再合并”。虽然 Claude 不一定严格按这个执行但给了它一个处理长文本的提示。4.5 调试与验证方法插件写完后怎么确认它按预期工作我的调试流程分三步。第一步语法检查。plugin.json用 JSON 校验工具过一遍命令文件的 Markdown 格式确认没有破坏结构的字符。第二步最小输入测试。用一段很短的、你知道预期输出的文本测试。比如“今天开会讨论了A和B决定下周完成C张三负责”。如果输出结构正确说明基本逻辑没问题。第三步边界测试。用空输入、超长输入、特殊字符输入分别测试。空输入时命令应该给出友好提示而不是报错超长输入时应该能处理而不是截断特殊字符输入时不应该破坏输出格式。提示调试时可以在命令文件里临时加一句“在输出开头打印当前使用的提示词版本”方便确认加载的是最新版本。调试完再删掉。5. 常见问题与排查技巧实录5.1 插件不加载的排查思路插件不加载是最常见的问题表现是输入/命令名没有任何反应或者提示命令不存在。排查按以下顺序进行。先确认插件目录位置是否正确。Claude Code 扫描的路径是固定的放错地方等于没放。可以查看配置文档确认当前版本的扫描路径。再确认plugin.json格式是否正确。用python -m json.tool plugin.json或者在线 JSON 校验工具检查。一个隐藏的坑是文件编码如果保存成了带 BOM 的 UTF-8某些解析器会报错。然后确认commands字段和实际文件名是否匹配。声明了summarize但文件叫summary.md命令就不会注册。最后确认 Claude Code 是否需要重启。有些版本支持热加载有些需要重启才能识别新插件。不确定的话重启一次最稳妥。5.2 命令执行结果不符合预期的调整方法命令能执行但输出不对通常问题出在提示词上。常见情况有三种。第一种输出格式不稳定。这次是列表下次是段落。解决办法是在提示词里用更明确的格式指令比如“必须使用 Markdown 表格表头为...”。必要时给出完整示例。第二种内容遗漏。该提取的信息没提取到。这通常是因为提示词里的任务描述不够具体。把“提取关键信息”改成“提取所有包含人名和时间节点的句子”效果会好很多。第三种过度发挥。Claude 加了很多你没要求的内容。在提示词末尾加一句“只输出要求的内容不要添加额外说明”通常能解决。我自己的经验是提示词调整是一个迭代过程。第一版写完后用三到五个不同类型的输入测试根据结果微调通常两三轮就能稳定下来。5.3 常见问题速查表问题现象可能原因排查方法解决方式命令不识别插件目录位置错误确认配置中的扫描路径移动到正确目录命令不识别plugin.json 格式错误JSON 校验工具检查修正语法错误命令不识别命令名与文件名不匹配对比 commands 字段和实际文件统一命名输出格式混乱提示词格式指令不明确检查命令文件增加格式示例输出内容遗漏任务描述太宽泛检查提示词细化任务指令输出内容过多缺少约束条件检查提示词增加“只输出...”约束长文本处理差超出上下文窗口测试长输入增加分段处理指令变量未替换占位符语法错误检查占位符写法参照文档修正语法5.4 独家避坑技巧分享几个我在实际使用中总结的技巧常规文档里不太会写。技巧一给命令加版本号注释。在命令文件第一行加!-- v1.2 --调试时能快速确认加载的是哪个版本。特别是当你同时维护多个插件时这个习惯能省很多时间。技巧二用注释保留废弃的提示词。调整提示词时不要直接删掉旧版本用 HTML 注释包起来。万一新版本效果不好可以快速回滚。技巧三建立个人插件索引。插件多了之后容易忘记哪个命令是干什么的。我在插件目录下放一个INDEX.md列出所有命令和一句话说明。虽然 Claude Code 不读这个文件但自己查阅很方便。技巧四命令名加前缀避免冲突。如果你装的插件多了不同插件可能有同名命令。建议给自己的插件命令加个短前缀比如mn-summarize表示 meeting-notes 插件的 summarize。虽然名字长一点但不会冲突。技巧五定期清理不用的插件。插件加载会占用启动时间虽然单个插件影响很小但积累多了也能感觉到。每隔一段时间清理一次只保留真正在用的。6. 插件组合与工作流扩展思路6.1 多个插件如何协同工作单个插件的价值有限真正提升效率的是插件组合。比如会议记录整理插件输出结构化摘要后可以用周报生成插件把多天的摘要合并成周报再用邮件草稿插件生成发送内容。这种组合的关键是输出格式约定。如果会议记录插件的输出格式经常变周报插件就很难稳定处理。所以我在设计插件时会尽量让输出格式固定下来必要时用 JSON 这种结构化格式作为中间产物。另一个协同方式是命令链。有些实现支持在一个命令里调用另一个命令比如/weekly-report内部先调用/summarize处理每天的记录再合并。这种链式调用能进一步减少手动操作。6.2 从个人使用到团队共享自己用顺了之后自然会想分享给团队。分享插件比分享脚本简单但有几个注意事项。第一去掉个人配置。插件里不要硬编码个人路径、个人 API key 这些东西。该用变量的地方用变量。第二写清楚依赖。如果插件依赖特定版本的 Claude Code 或者特定操作系统在plugin.json的description里说明。第三提供示例输入输出。在插件目录下放一个examples/文件夹放几个典型输入和对应输出。新用户一看就知道怎么用。第四版本管理。团队共享的插件建议用 git 管理每次修改打 tag方便追溯和回滚。6.3 后续可以扩展的方向knowledge-work-plugins 这套机制的可扩展性很强。除了文档处理还可以往几个方向延伸。一是代码相关。比如代码审查插件、提交信息生成插件、测试用例生成插件。这类插件对开发者价值很高。二是数据分析。比如 CSV 文件摘要插件、数据质量检查插件。把常见的数据处理动作固化下来。三是个人知识管理。比如笔记整理插件、标签生成插件、关联推荐插件。配合本地笔记系统使用。四是多语言处理。比如翻译插件、术语一致性检查插件。对于需要处理多语言内容的场景很实用。每个方向都可以独立成一个插件也可以组合成插件包。关键是保持每个插件职责单一组合起来才灵活。7. 我个人的使用体会与建议用了这段时间最大的感受是插件化的核心价值不是省时间而是省脑子。以前每次处理会议记录都要想一遍“我该怎么描述需求”现在直接一个命令脑子不用切换上下文。这种认知负担的降低比单纯的时间节省更有价值。另一个体会是不要追求大而全的插件。我一开始想做一个“万能知识工作插件”把所有功能塞进去结果提示词越写越长效果越来越差。后来拆成多个小插件每个只做一件事反而稳定得多。这跟软件开发里的单一职责原则是一个道理。还有一点提示词是需要维护的。模型在更新你的需求也在变化半年前好用的提示词现在可能效果一般。建议每隔一段时间回顾一下常用插件根据实际使用情况调整。我一般每季度过一遍删掉不用的优化常用的。最后分享一个小技巧如果你不确定某个命令该怎么写可以先在 Claude Code 里用自然语言交互几轮找到效果最好的表达方式再把那段对话提炼成命令文件。这样写出来的提示词比凭空想的要靠谱得多。
阅读完成 · 觉得有帮助？
)
)
)
