1. 从 claude-plugins-official 这个仓库说起第一次看到claude-plugins-official这个名字很多人会下意识以为它是 Anthropic 官方发布的一个插件市场点进去就能像逛应用商店一样一键装插件。实际接触下来你会发现它更像是一个官方维护的插件规范与示例集合——里面放的是插件该怎么写、目录怎么组织、清单文件长什么样、有哪些官方认可的扩展点。换句话说它给的是标准答案的模板而不是装满成品的货架。这个区别非常关键。因为 Claude Code 的插件生态和传统 IDE 插件比如 VS Code 那种点一下 Install 就完事的完全不是一回事。Claude Code 的插件本质上是一组约定好的文件结构 配置声明它把你的自定义命令、子代理subagent、钩子hook、MCP 服务配置、技能skill这些东西打包成一个可被 Claude Code 识别的单元。claude-plugins-official这个仓库的价值就在于它用官方视角把这些约定固化下来让你不用去猜到底该放哪个目录、清单里该写哪些字段。我最初踩的坑就是以为装个插件跟装个 npm 包一样npm install完就生效。结果折腾半天发现Claude Code 的插件加载有一套自己的发现机制路径不对、清单字段写错、或者版本声明不匹配它就直接静默跳过连个像样的报错都不给你。这也是为什么热词里会冒出harness failed to load plugins这种让人头大的提示——它说的就是插件加载器在启动时没能成功激活某些条目。所以这篇内容我打算把claude-plugins-official这个仓库拆开讲清楚它到底定义了什么、插件是怎么被加载的、为什么会出现加载失败、以及怎么基于官方规范自己写一个能跑起来的插件。适合已经装好 Claude Code、想进一步做定制化的同学也适合那些被harness failed to load plugins卡住、想搞明白背后机制的人。哪怕你只是想搞清楚插件和 skill 到底啥关系看完也能有个清晰的判断。2. 插件机制的整体设计与思路拆解2.1 为什么 Claude Code 要用插件这套抽象要理解claude-plugins-official得先理解 Claude Code 为什么要引入插件这个概念。早期的 Claude Code 定制化方式很零散你想加个自定义命令就去某个目录丢个 markdown 文件你想加个钩子就去改全局配置文件你想接个外部工具就去配 MCP。这些方式各自能用但没法打包、没法分发、没法版本管理。团队里一个人配好了想同步给其他人只能靠你把这几个文件拷过去再改改路径。插件机制解决的就是这个打包与分发的问题。它把原本散落在各处的定制内容收敛到一个有明确边界的目录里用一个清单文件manifest声明我这个插件提供了什么。这样一来插件就可以被 Git 管理、被团队共享、被版本化。claude-plugins-official作为官方仓库做的就是把这份清单的 schema 和目录约定标准化让所有人写出来的插件都能被同一套加载器识别。这里有个设计哲学值得说Claude Code 的插件是声明式的不是命令式的。你不需要写代码去注册一个命令你只需要在约定位置放好文件、在清单里声明它。加载器启动时扫描目录、读取清单、按声明去挂载。这种设计的好处是加载过程可预测、可校验坏处是——一旦你的声明和实际文件对不上加载器不会帮你猜直接跳过。这就是很多插件没生效问题的根源。2.2 插件、Skill、MCP、Subagent 的关系梳理热词里频繁出现claude code skill、claude code怎么手动装github上的skills说明很多人把 skill 和 plugin 混为一谈。我梳理一下这几个概念在 Claude Code 里的层次关系这个搞清楚了后面写插件就不会迷路。概念本质归属层级典型用途Plugin打包与分发单元最外层容器把下面几样东西打包共享Skill一段可复用的能力描述插件内或独立教 Claude 怎么完成某类任务Subagent独立的子代理配置插件内或独立把某类任务隔离出去单独跑Hook生命周期回调插件内或独立在工具调用前后插入逻辑MCP Server外部工具/数据接入插件内或独立连接数据库、API、本地服务Command自定义斜杠命令插件内或独立快捷触发某个流程关键点在于Plugin 是容器Skill/Subagent/Hook/MCP/Command 是内容。你可以单独放一个 skill 到用户目录让它生效也可以把它塞进一个 plugin 里打包分发。claude-plugins-official定义的就是这个容器该怎么造、内容该怎么摆。我个人的经验是如果只是自己用、临时试直接放独立目录最快如果要给团队用、要跨机器同步、要版本管理那就老老实实按官方规范打成 plugin。别小看这个选择我见过太多人图省事把一堆 skill 散着放结果换台机器就全丢了回头还得一个个重新配。2.3 官方仓库的目录约定与清单结构claude-plugins-official最核心的产出是一套目录约定。虽然具体字段会随版本演进但骨架是稳定的。一个符合规范的插件大致长这样my-plugin/ ├── .claude-plugin/ │ └── plugin.json # 清单文件声明插件元信息与提供的能力 ├── commands/ # 自定义斜杠命令 │ └── hello.md ├── agents/ # 子代理定义 │ └── reviewer.md ├── skills/ # 技能 │ └── my-skill/ │ └── SKILL.md ├── hooks/ # 钩子脚本与配置 │ └── hooks.json └── .mcp.json # MCP 服务配置可选清单文件plugin.json是加载器读取的入口它至少要声明插件的名字、版本以及它提供了哪些能力。这里有个容易翻车的点清单里声明的每一项都必须在对应目录里真实存在。你声明了commands/hello.md但文件没放对位置加载器扫描时找不到就会记一条未激活。热词里那个harness failed to load plugins web boot: 2 entries did not activate说的就是启动时有 2 个条目没能激活——大概率就是声明和实际文件对不上或者路径写错了。提示清单文件里的路径通常是相对于插件根目录的不要写成绝对路径也不要用~。跨平台时尤其注意路径分隔符统一用正斜杠最稳。3. 核心细节解析与实操要点3.1 清单文件到底该写什么清单文件是插件的身份证 说明书。它告诉加载器我是谁、我提供什么、我依赖什么。虽然官方 schema 会更新但核心字段就那么几类。我按实际写插件的经验把最常打交道的字段列一下并说明每个字段为什么重要。{ name: my-team-plugin, version: 1.0.0, description: 团队内部常用的命令与技能集合, author: your-team, commands: [commands/hello.md], agents: [agents/reviewer.md], skills: [skills/my-skill], hooks: hooks/hooks.json }name和version是必填的加载器靠它们做去重和版本判断。如果你装了两个同名插件后加载的可能会覆盖前面的或者直接被跳过——这也是插件没生效的常见原因之一。description虽然不影响加载但在你列出已装插件时能帮你快速辨认强烈建议写清楚。commands、agents、skills这些数组字段每一项都是一个路径。路径必须真实存在这是硬性要求。我建议的做法是先建好文件再往清单里填路径而不是反过来。反过来写最容易出现声明了但文件没建的情况加载器一扫描就报未激活。hooks字段指向一个钩子配置文件这个文件里再声明具体在哪个生命周期触发哪个脚本。钩子的坑后面单独讲。3.2 目录命名与文件放置的硬性规则Claude Code 的插件加载器对目录名是有约定的不是随便叫什么都行。commands/、agents/、skills/、hooks/这些是约定目录加载器会去这些位置找对应类型的内容。你把命令文件放到skills/里它就不会被当成命令加载。我整理了一份常见目录与内容的对应关系照着放基本不会错目录放什么文件格式commands/自定义斜杠命令Markdownagents/子代理定义Markdownskills/技能每个技能一个子目录子目录内含 SKILL.mdhooks/钩子配置与脚本JSON 脚本文件.claude-plugin/清单文件plugin.json这里有个细节skills/下面是每个技能一个子目录子目录里放SKILL.md。不是直接把一堆 md 文件丢在skills/下。我第一次写的时候就犯了这个错把my-skill.md直接放skills/里结果加载器根本不认。后来才明白技能是一个目录级的概念因为一个技能可能附带参考文件、脚本、模板需要独立目录来装。注意目录名大小写敏感。在 Linux 和 macOS 上Commands/和commands/是两个不同的目录加载器只认小写的约定名。Windows 上虽然不区分大小写但为了跨平台一致也统一用小写。3.3 插件加载的完整流程理解加载流程是排查harness failed to load plugins的前提。加载器启动时大致做这几件事发现扫描配置的插件目录用户级、项目级、以及通过配置指定的路径找出所有含.claude-plugin/plugin.json的目录。解析读取每个plugin.json校验必填字段解析出它声明了哪些能力。校验对每一项声明去对应路径检查文件是否存在、格式是否合法。挂载把通过校验的能力注册到运行时命令进命令表、技能进技能库、钩子进钩子链。报告把没能激活的条目汇总输出类似N entries did not activate的提示。问题基本都出在第 3 步。加载器校验很严格但报错很克制——它不会告诉你你第 3 个命令文件路径写错了只会告诉你有 2 个条目没激活。所以排查时你得自己对照清单和实际文件一个个核对。我常用的排查手法是把清单里声明的路径逐条复制出来在终端里ls一遍。哪条ls不到问题就在哪。这个方法土但极其有效比盯着报错猜快得多。4. 实操过程与核心环节实现4.1 从零写一个最小可用插件光讲概念没用我带你从零写一个能跑起来的最小插件。这个插件提供一个自定义命令功能是让 Claude 帮你生成一段规范的提交信息。麻雀虽小但把清单、目录、命令文件三样都覆盖到了。第一步建目录结构mkdir -p my-first-plugin/.claude-plugin mkdir -p my-first-plugin/commands第二步写清单文件my-first-plugin/.claude-plugin/plugin.json{ name: my-first-plugin, version: 0.1.0, description: 一个演示用的最小插件, commands: [commands/commit-msg.md] }第三步写命令文件my-first-plugin/commands/commit-msg.md。命令文件本质是一段给 Claude 的提示词加上一些元信息。内容大致这样--- description: 根据当前改动生成规范的提交信息 --- 请查看当前工作区的改动按照约定式提交Conventional Commits的格式 生成一条简洁准确的提交信息。只输出提交信息本身不要额外解释。第四步把这个插件目录放到 Claude Code 能发现的位置。具体位置取决于你的配置通常是用户级插件目录或项目级插件目录。放好之后重启 Claude Code让它重新扫描。第五步验证。在 Claude Code 里输入斜杠看命令列表里有没有commit-msg。有说明加载成功没有就回到第 3 步的排查方法逐条核对路径。这个流程走一遍你就把插件机制的骨架摸清了。后面加技能、加钩子、加 MCP都是在这个骨架上扩展。4.2 给插件加一个技能技能和命令的区别在于命令是你主动用斜杠触发的技能是 Claude 在合适的时候自己判断要不要用。技能适合封装某类任务的完整做法比如如何审查一段 SQL、如何写单元测试。给上面的插件加一个技能先建目录mkdir -p my-first-plugin/skills/sql-review然后在skills/sql-review/SKILL.md里写技能描述。技能文件的关键是把触发条件和执行步骤写清楚因为 Claude 要靠这些描述来判断什么时候该调用它--- name: sql-review description: 当用户提供 SQL 语句并希望审查其性能或正确性时使用 --- 审查 SQL 时按以下顺序检查 1. 是否有全表扫描风险WHERE 条件是否命中索引 2. JOIN 的顺序与驱动表选择是否合理 3. 是否有隐式类型转换导致索引失效 4. 子查询能否改写为 JOIN 5. 是否缺少必要的 LIMIT 输出时按严重程度排序每条给出问题、原因、修改建议。写完记得回到plugin.json在skills数组里加上skills/sql-review。这一步最容易忘忘了就等于技能没声明加载器不会去挂载它。4.3 钩子的接入与常见陷阱钩子是插件里最容易出问题的部分因为它涉及脚本执行。钩子配置通常长这样{ hooks: { PostToolUse: [ { matcher: Write, hooks: [ { type: command, command: bash hooks/format.sh } ] } ] } }这段配置的意思是在Write工具使用之后执行hooks/format.sh。钩子的价值在于自动化——比如每次写完文件自动格式化、自动跑 lint。钩子的坑主要有三个。第一脚本路径。command里的路径是相对于插件根目录还是当前工作目录不同版本行为可能不同最稳的做法是用绝对路径或者在脚本里自己处理路径。第二脚本权限。在 Linux/macOS 上脚本得有可执行权限chmod x别忘了否则钩子触发时直接失败。第三脚本超时。钩子脚本如果卡住会拖慢整个工具调用所以脚本里别做重活快速返回。提示调试钩子时先在终端里手动跑一遍脚本确认脚本本身没问题再去排查钩子配置。把脚本问题和配置问题分开定位能省一半时间。4.4 把插件共享给团队插件写好了怎么让团队其他人用上最直接的方式是把插件目录提交到 Git 仓库其他人 clone 下来放到自己的插件目录里。但这样有个问题每个人的插件目录路径可能不一样手动放容易出错。更规范的做法是把插件做成一个独立的 Git 仓库然后在项目里通过配置引用它。这样插件可以独立版本化团队升级插件时拉一下就行不用互相拷文件。claude-plugins-official本身就是这种模式的示范——它是一个仓库你引用它、参考它而不是把它整个拷进项目。我个人的建议是团队内部插件单独建一个仓库按功能拆成多个插件目录每个插件有自己的plugin.json和版本号。这样谁需要哪个就引哪个不会互相干扰。5. 常见问题与排查技巧实录5.1 harness failed to load plugins 到底在说什么这个报错是问得最多的。harness指的是 Claude Code 的运行时框架failed to load plugins是说框架在加载插件阶段遇到了问题后面跟的N entries did not activate是具体有多少个条目没能激活。它不是说整个插件系统崩了而是说某些条目被跳过了。可能的原因按出现频率排现象可能原因排查方法命令不出现清单未声明或路径错核对 plugin.json 与文件技能不触发SKILL.md 描述不清检查 description 是否明确钩子不执行脚本无执行权限chmod x后重试整个插件不加载清单 JSON 语法错用 JSON 校验工具检查部分条目未激活声明了但文件不存在逐条 ls 核对路径我遇到最多的是清单 JSON 语法错误。JSON 不允许尾随逗号不允许注释一个多余的逗号就能让整个清单解析失败进而整个插件不加载。写完清单后丢进任意 JSON 校验器过一遍能避免大量低级问题。5.2 插件装了但命令不生效的排查顺序命令不生效按这个顺序查基本能定位到清单里声明了吗commands数组里有没有这个文件。文件在约定目录吗是不是放在commands/下。文件名和声明一致吗大小写、扩展名都要对。插件被加载了吗看启动日志有没有这个插件的加载记录。重启了吗Claude Code 通常在启动时扫描插件改完不重启不生效。这五步走下来九成问题能解决。剩下那一成多半是插件目录本身没在扫描范围内——检查你的插件目录配置确认它指向了你放插件的那个路径。5.3 技能不被调用的几个隐蔽原因技能比命令更难排查因为它是 Claude 自主判断调用的不生效时你甚至不知道是没加载还是加载了但没触发。先确认加载技能目录结构对不对、SKILL.md在不在、清单里声明了没。这些都对了再看触发。触发不灵通常是description写得太模糊。比如你写处理数据Claude 根本不知道什么时候该用写成当用户提供 CSV 文件并希望清洗数据时使用触发率立刻上来。我的经验是技能描述要写什么时候用而不是这是什么。前者是触发条件后者是功能说明Claude 靠前者做判断。5.4 跨平台使用插件的注意事项热词里有windows claude code 安装、claude code linux下载说明跨平台用户不少。插件在跨平台时有几个点要注意。路径分隔符是头号问题。清单和钩子配置里统一用正斜杠/Claude Code 在 Windows 上也能正确解析。别用反斜杠反斜杠在 JSON 里还得转义徒增麻烦。脚本兼容性是二号问题。钩子脚本如果用了 bash 特性在 Windows 上可能跑不了。要么用跨平台的脚本语言比如 Node.js要么在配置里针对不同平台写不同命令。换行符是三号问题。Git 在 Windows 上默认可能把 LF 转成 CRLF某些脚本对换行符敏感。建议在仓库里加.gitattributes强制脚本文件用 LF。注意跨平台插件测试时别只在你自己机器上测。至少在一个不同系统的环境里跑一遍很多问题只有换平台才暴露。6. 我踩过的坑和几条实在建议写插件这段时间踩的坑不算少挑几个最有代表性的说说。第一个坑是过度设计。一开始我想做一个全能插件把命令、技能、钩子、MCP 全塞进去结果清单越来越复杂加载失败的概率也越来越高。后来我改成一个插件只做一件事每个插件小而专加载稳定排查也容易。插件这东西宁可多几个小的别搞一个大的。第二个坑是忽略版本。清单里的version我一开始随便填后来团队里两个人装了同名不同版本的插件行为不一致排查了半天才发现是版本问题。现在我的习惯是每次改动插件内容必须升版本号哪怕只是改了个错别字。第三个坑是不写文档。插件写完了过两周自己都忘了某个命令是干嘛的。后来我在每个插件的plugin.json里把description写详细在技能文件里把用法写清楚。这不是给别人看的是给未来的自己看的。最后分享一个实用技巧建一个插件沙盒目录专门用来试新插件。新插件先在沙盒里跑通确认没问题了再挪到正式目录。这样即使插件有问题也不会影响你日常用的那套配置。这个习惯帮我省了无数次改坏配置导致 Claude Code 起不来的麻烦。插件生态还在演进claude-plugins-official的规范也可能调整。但底层那套声明式加载 严格校验的逻辑是稳定的把这套逻辑吃透规范怎么变你都能跟上。