plugin.json 写法分析

第三章第5节自己做插件时，plugin.json 最少只需要一个 name。

ECC 的 plugin.json 也不长，三十来行。但它最值得看的，不是写了什么，而是刻意没写的那几个字段。每一个「没写」，背后都是一个小技巧。

一、完整的 plugin.json

plugin.json 声明插件的基本身份与入口

.claude-plugin/plugin.json（省略了 keywords）：

{
  "name": "ecc",
  "version": "2.2.3",
  "description": "Harness-native ECC plugin for engineering teams - 71 agents, 302 skills, ...",
  "author": { "name": "Affaan Mustafa", "url": "https://x.com/affaanmustafa" },
  "homepage": "https://ecc.tools",
  "repository": "https://github.com/affaan-m/ECC",
  "license": "MIT",
  "userConfig": {
    "hooks_enabled": {
      "type": "boolean",
      "title": "Enable ECC hooks",
      "default": true
    },
    "hook_profile": {
      "type": "string",
      "title": "ECC hook profile",
      "description": "Choose minimal, standard, or strict.",
      "default": "standard"
    }
  },
  "mcpServers": {},
  "skills": ["./skills/"],
  "commands": ["./commands/"]
}

逐个看关键字段：

字段	值	说明
`name`	`ecc`	插件名，也是命名空间：Skill 调用是 `/ecc:xxx`，子代理是 `ecc:planner`
`version`	`2.2.3`	很多示例里省略了，但校验器实际会要，不写可能装不上
`userConfig`	两个开关	让用户选要不要开 Hook、开到哪一档，下面讲
`mcpServers`	`{}`	空对象，是刻意的，下面讲
`skills` / `commands`	`["./skills/"]`	必须写成数组，只有一项也不能写成字符串

再看少了什么：没有 agents，也没有 hooks。 可 ECC 明明有 71 个子代理和一整套 Hook。

二、没写的字段：agents 和 hooks

agents 和 hooks 可通过目录约定被发现

原因很简单：Claude Code 会按约定自动发现它们。

插件根目录的 agents/ 下的 .md，自动注册成子代理
插件根目录的 hooks/hooks.json，自动加载

这和第三章第5节讲的目录结构是一致的：东西放对位置，就不用在清单里再声明。

问题在于，写了反而出错：

多写了什么	报错
`"agents": [...]`	`agents: Invalid input`
`"hooks": "./hooks/hooks.json"`	`Duplicate hooks file detected`

ECC 在 hooks 这个字段上来回翻车了好几次。仓库里专门有一份文档 .claude-plugin/PLUGIN_SCHEMA_NOTES.md 记录了这段历史：

一、完整的 plugin.json

二、没写的字段：agents 和 hooks

本文是会员内容