Claude Code 插件清单（plugin.json）权威参考：从字段解析到路径解析与校验实践

Claude Code 插件清单plugin.json权威参考从字段解析到路径解析与校验实践【免费下载链接】claude-codeClaude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code本指南以plugins/plugin-dev/skills/plugin-structure/references/manifest-reference.md为骨架完整讲解 Claude Code 插件清单.claude-plugin/plugin.json的全部字段、路径解析规则、加载顺序与校验逻辑并结合当前仓库中code-review、security-guidance、hookify、telemetry等真实插件的 manifest 进行印证。读完你将能够独立编写从最小可运行到企业级完整的插件清单并排查常见的配置错误。清单文件位置.claude-plugin/plugin.json插件清单manifest的存放路径是硬性规定必须位于插件根目录下的.claude-plugin/plugin.json。Claude Code 只会识别这个确切位置的清单文件位置错误将导致整个插件无法被加载。从仓库中的真实插件可以看到这一约定的普遍性——code-review、feature-dev、hookify、security-guidance、commit-commands、ralph-wiggum、pr-review-toolkit等插件均把清单放在plugins/plugin-name/.claude-plugin/plugin.json。同时注意一个关键区分见 SKILL.md清单文件必须在.claude-plugin/目录内组件目录commands/、agents/、skills/、hooks/必须位于插件根目录不能嵌套在.claude-plugin/内部只创建插件实际使用的组件目录。核心字段Core Fieldsname必填name是插件的唯一标识类型为 String格式为 kebab-case小写字母、数字和连字符。用途插件在 Claude Code 中的识别、与其他插件的冲突检测、命令命名空间可选。硬性要求在所有已安装插件中必须唯一只能使用小写字母、数字和连字符不能有空格或特殊字符必须以字母开头必须以字母或数字结尾。校验正则源码级约束/^[a-z][a-z0-9]*(-[a-z0-9])*$/示例对比✅ 合法api-tester、code-review、git-workflow-automation❌ 非法API Tester含空格与大写、code_review下划线、-git-workflow连字符开头、test-连字符结尾仓库印证plugins/code-review/.claude-plugin/plugin.json中name: code-review、plugins/pr-review-toolkit/.claude-plugin/plugin.json中name: pr-review-toolkit均严格符合该正则。version类型为 String采用语义化版本SemVerMAJOR.MINOR.PATCH。若未指定默认值为0.1.0。语义化版本含义MAJOR不兼容的 API 变更、破坏性变更MINOR向后兼容的新功能PATCH向后兼容的缺陷修复。预发布版本示例1.0.0-alpha.1Alpha、1.0.0-beta.2Beta、1.0.0-rc.1候选发布。版本示例0.1.0— 初始开发阶段1.0.0— 首个稳定版1.2.3— 1.2 的补丁更新2.0.0— 含破坏性变更的主版本仓库中版本使用的多样性正好佐证了这一点hookify与telemetry使用0.1.0开发初期code-review、feature-dev、security-guidance、ralph-wiggum、pr-review-toolkit使用1.0.0而security-guidance已演进到2.0.0见 security-guidance 清单。security-guidance的 README 也展示了一个插件随功能演进而按语义化版本升级的完整路径。description类型为 String推荐长度 50–200 字符用于简述插件的目的与功能。最佳实践聚焦插件做什么what而非怎么做how使用主动语态提及关键特性或收益为市场展示marketplace display控制在 200 字符以内。示例对比✅ Generates comprehensive test suites from code analysis and coverage reports✅ Integrates with Jira for automatic issue tracking and sprint management❌ A plugin that helps you do testing stuff过于空泛❌ 冗长到超过 200 字符的逐条功能罗列仓库印证plugins/security-guidance/.claude-plugin/plugin.json的 description 精准概括了“模式告警 LLM diff 审查 agentic commit 审查、覆盖注入/XSS/SSRF/硬编码密钥等 25 漏洞类别”的核心能力mods/diff/.claude-plugin/plugin.json的 description 则用一段话说明了 diff 面板的完整行为链路。这些都是“聚焦 what、主动语态”的范本。元数据字段Metadata Fieldsauthor类型为 Object包含 name必填、email可选、url可选也支持仅字符串的简写格式。对象格式{ author: { name: Jane Developer, email: janeexample.com, url: https://janedeveloper.com } }字符串格式{ author: Jane Developer janeexample.com (https://janedeveloper.com) }用途署名与归属、支持联系渠道、市场展示、社区认可。仓库印证plugins/code-review/.claude-plugin/plugin.json与plugins/feature-dev/.claude-plugin/plugin.json均使用author对象并带nameemailmods/telemetry/.claude-plugin/plugin.json则只提供了name: Anthropic说明 email/url 确实为可选项。homepage类型为 StringURL指向插件文档或落地页。应该指向插件文档站点、项目主页、详细使用指南、安装说明。不应指向源码仓库应使用repository字段、Issue 追踪器应放入文档、个人网站应使用author.url。仓库印证plugins/security-guidance/.claude-plugin/plugin.json中homepage指向了该插件的 GitHub 目录页用于说明插件的背景与安装方式。repository类型为 StringURL或 Object声明源码仓库位置。字符串格式{ repository: https://github.com/user/plugin-name }对象格式更详细{ repository: { type: git, url: https://github.com/user/plugin-name.git, directory: packages/plugin-name } }用途源码访问、Issue 报告、社区贡献入口、透明度与信任建设。directory字段特别适用于 monorepo 中插件位于子目录的场景。license类型为 String使用 SPDX 标识符。常见许可证MIT— 宽松许可最常用Apache-2.0— 宽松许可并含专利授权GPL-3.0— CopyleftBSD-3-Clause— 宽松许可ISC— 宽松许可与 MIT 类似UNLICENSED— 专有、非开源多许可证声明{ license: (MIT OR Apache-2.0) }完整清单可查阅 SPDX 许可证列表https://spdx.org/licenses/。建议同时在插件根目录放置 LICENSE 文件与license字段保持一致。keywords类型为字符串数组用于插件的发现与分类。最佳实践使用 5–10 个关键词包含功能分类添加技术名称使用常见搜索词避免与插件名重复。可考虑的分类维度功能类testing、debugging、documentation、deployment技术类typescript、python、docker、aws工作流类ci-cd、code-review、git-workflow领域类web-development、data-science、devops组件路径字段Component Path Fields这类字段的作用是为组件声明额外的目录或文件路径。其核心语义是补充supplement默认目录而不是替换replace。默认目录与自定义路径下的组件都会被加载。commands类型为 String 或字符串数组默认值为[./commands]用于声明额外的命令定义目录或文件。单一路径{ commands: ./custom-commands }多路径{ commands: [ ./commands, ./admin-commands, ./experimental-commands ] }适用场景按类别组织命令、分离稳定命令与实验命令、从共享位置加载命令。agents类型为 String 或字符串数组默认值为[./agents]格式与commands字段一致。适用场景按专长分组 agent、分离通用型与任务型 agent、从插件依赖加载 agent。hooks类型为 String指向 JSON 文件的路径或 Object内联配置默认值为./hooks/hooks.json。文件路径形式{ hooks: ./config/hooks.json }内联配置形式{ hooks: { PreToolUse: [ { matcher: Write, hooks: [ { type: command, command: bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh, timeout: 30 } ] } ] } }适用场景简单插件少于 50 行用内联配置复杂插件用外部 JSON 文件多套 hook 使用独立文件分别管理不同上下文。仓库印证hookify插件将 hook 配置放在plugins/hookify/hooks/hooks.json其中pretooluse.py使用${CLAUDE_PLUGIN_ROOT}引用插件根目录下的 Python 脚本mods/diff与mods/telemetry也各自维护hooks/hooks.json。这与清单中“外部 JSON 文件 ${CLAUDE_PLUGIN_ROOT}可移植路径”的最佳实践完全一致。${CLAUDE_PLUGIN_ROOT}是 Claude Code 提供的插件根目录环境变量让命令定义不依赖绝对路径、可在任意安装位置运行。mcpServers类型为 String指向 JSON 文件的路径或 Object内联配置默认值为./.mcp.json。文件路径形式{ mcpServers: ./.mcp.json }内联配置形式{ mcpServers: { github: { command: node, args: [${CLAUDE_PLUGIN_ROOT}/servers/github-mcp.js], env: { GITHUB_TOKEN: ${GITHUB_TOKEN} } } } }适用场景单个内联 server少于 20 行适合简单插件复杂插件使用外部.mcp.json多 server 场景始终建议使用外部文件。路径解析Path Resolution相对路径规则组件字段中的所有路径必须遵守四条规则必须是相对路径禁止绝对路径必须以./开头表示相对于插件根目录不能使用../禁止向上级目录导航只使用正斜杠/即使在 Windows 上也是如此。示例对比✅./commands✅./src/commands✅./configs/hooks.json❌/Users/name/plugin/commands绝对路径❌commands缺少./❌../shared/commands越级引用❌.\\commands反斜杠解析顺序Claude Code 加载组件时的顺序默认目录先扫描标准位置——./commands/、./agents/、./skills/、./hooks/hooks.json、./.mcp.json自定义路径再扫描清单中声明的位置——commands与agents字段给出的路径、hooks与mcpServers字段给出的文件合并行为所有位置发现的组件都会加载——不互相覆盖、全部注册名称冲突会导致报错。这一点再次印证了 SKILL.md 中的说明“自定义路径补充默认目录不会替换默认目录默认目录与自定义路径中的组件都会加载。”校验Validation清单校验Claude Code 在插件加载时对清单进行三层校验语法校验JSON 格式合法无语法错误字段类型正确。字段校验name字段存在且格式合法version若存在符合语义化版本路径为带./前缀的相对路径URL若存在合法。组件校验被引用的路径真实存在hook 与 MCP 配置合法无循环依赖。常见校验错误与修复name 格式非法含空格{ name: My Plugin // ❌ 含空格 }修复为 kebab-case{ name: my-plugin // ✅ }绝对路径{ commands: /Users/name/commands // ❌ 绝对路径 }修复为相对路径{ commands: ./commands // ✅ }缺少./前缀{ hooks: hooks/hooks.json // ❌ 缺少 ./ }修复为补上./{ hooks: ./hooks/hooks.json // ✅ }版本号不符合语义化版本{ version: 1.0 // ❌ 非 MAJOR.MINOR.PATCH }修复为完整三段式{ version: 1.0.0 // ✅ }三个档次的清单示例最小插件Minimal Plugin可运行插件的最低要求——只依赖默认目录自动发现无需任何组件路径配置{ name: hello-world }推荐插件Recommended Plugin面向分发的良好元数据配置{ name: code-review-assistant, version: 1.0.0, description: Automates code review with style checks and suggestions, author: { name: Jane Developer, email: janeexample.com }, homepage: https://docs.example.com/code-review, repository: https://github.com/janedev/code-review-assistant, license: MIT, keywords: [code-review, automation, quality, ci-cd] }这个档次与仓库中多数插件的实际形态高度一致——例如code-review、feature-dev、hookify的清单都是「name version description author」的紧凑结构在完整可用与配置精简之间取得平衡。完整插件Complete Plugin启用全部特性的企业级配置{ name: enterprise-devops, version: 2.3.1, description: Comprehensive DevOps automation for enterprise CI/CD pipelines, author: { name: DevOps Team, email: devopscompany.com, url: https://company.com/devops }, homepage: https://docs.company.com/plugins/devops, repository: { type: git, url: https://github.com/company/devops-plugin.git }, license: Apache-2.0, keywords: [ devops, ci-cd, automation, kubernetes, docker, deployment ], commands: [ ./commands, ./admin-commands ], agents: ./specialized-agents, hooks: ./config/hooks.json, mcpServers: ./.mcp.json }仓库中mods/telemetry/.claude-plugin/plugin.json还展示了一个清单里相对少见的字段types: ./types/index.d.ts用于为插件提供 TypeScript 类型声明——说明清单字段并非封闭集合插件可依据实际需求扩展。最佳实践元数据始终包含 version跟踪变更与更新撰写清晰的 description帮助用户理解插件用途提供联系信息支撑用户支持链接到文档降低支持负担选择合适的许可证与项目目标匹配。路径尽可能使用默认路径最小化配置逻辑化组织将相关组件归类记录自定义路径解释为何使用非标准布局测试路径解析在多个系统上验证注意 Windows 下也须使用正斜杠。维护变更即升版本遵循语义化版本更新 keywords反映新增功能保持 description 最新与实际能力一致维护 changelog记录版本历史更新 repository 链接保持 URL 有效。分发发布前补全元数据所有字段填写完整在干净环境测试验证插件在没有开发环境时也能工作校验清单使用校验工具包含 README说明安装与使用方法附带 LICENSE 文件放在插件根目录。小结.claude-plugin/plugin.json是 Claude Code 插件的“身份证与配置中心”name/version/description定义身份与用途author/homepage/repository/license/keywords支撑分发与可信度commands/agents/hooks/mcpServers则把默认目录之外的自定义组件接入自动发现。只要守住「路径相对、./开头、禁止../、正斜杠」四条铁律并理解“自定义路径是补充而非替换”的合并语义就能从最小清单起步一步步构建出结构清晰、可维护、可分发的高质量插件。如需进一步探索组件组织模式可继续阅读本仓库中的 manifest-reference.md、SKILL.md 与 plugin-structure README并对照plugins/与mods/下各真实插件的清单文件进行实践验证。【免费下载链接】claude-codeClaude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考