plugin-authoring

用途

Plugin Authoring 是 Claude Code 插件开发的规范指南（Skill）。当创作、修改或调试 Claude Code 插件时使用；当上下文出现 .claude-plugin/、plugin.json、marketplace.json、commands/、agents/、skills/ 或 hooks/ 时触发。

主要能力

以只读方式诊断当前仓库布局。
提出最小安全动作：脚手架、校验或审查。
在用户同意后，通过 /plugin-development:... 命令执行。
将深入审计升级给 plugin-reviewer 代理。
防护原则：默认只读；编辑前先询问。

使用方式

操作流程

诊断当前仓库布局（只读）。
提出最小安全动作（脚手架、校验或审查）。
用户同意后通过 /plugin-development:... 命令执行。
将深入审计升级给 plugin-reviewer 代理。

快速链接（渐进式披露）

Schemas：schemas/plugin-manifest.md、schemas/hooks-schema.md、schemas/marketplace-schema.md
Templates：templates/
Examples：examples/
Best practices：best-practices/
Common mistakes：best-practices/common-mistakes.md
Testing this skill：testing-plugin-authoring.md

常用 Playbook

脚手架 → /plugin-development:init <name> 后填充模板
添加组件 → /plugin-development:add-command|add-skill|add-agent|add-hook
校验 → /plugin-development:validate（schema 与结构检查）
本地测试 → /plugin-development:test-local（dev marketplace）

创建新插件的工作流

运行 /plugin-development:init <plugin-name> 生成结构。
编辑 .claude-plugin/plugin.json 填写元数据。
使用 /plugin-development:add-command 等添加组件。
使用 /plugin-development:validate 校验。
使用 /plugin-development:test-local 本地测试。

添加 Slash Command

运行 /plugin-development:add-command <name> <description>。
编辑 commands/<name>.md 填写指令。
添加 frontmatter：description 与 argument-hint。
测试：/plugin install 你的插件，然后 /<name>。

添加 Skill

运行 /plugin-development:add-skill <name> <when-to-use>。
编辑 skills/<name>/SKILL.md 填写指令。
frontmatter 要求：
- name：仅小写字母、数字与连字符，最多 64 字符（必填）。不能包含保留字 'anthropic' 或 'claude'。不能包含 XML 标签。
- description：同时包含 Skill 做 WHAT 与 WHEN 使用时，最多 1024 字符（必填）。不能包含 XML 标签。
- model：指定使用的 Claude 模型，例如 model: claude-sonnet-4-20250514（可选，默认使用对话的模型）。
- allowed-tools：逗号分隔的工具列表（可选）。列出后 Skill 激活时无需许可即可使用。若省略，Skill 不限制工具。
保持 SKILL.md 低于 500 行以获得最佳性能；将细节放在同级文件（reference.md、examples.md、scripts/）。

组件清单

□ .claude-plugin/plugin.json 存在（必需）
□ 组件目录位于插件根目录（commands/、agents/、skills/、hooks/）
□ 不要将组件放在 .claude-plugin/ 目录内
□ Commands 使用 kebab-case 命名
□ Skills 具有有效 frontmatter（name + description 必填，可选：model、allowed-tools）
□ Skills name 校验：
- 与目录名一致
- 仅小写字母、数字、连字符
- 最多 64 字符
- 无保留字（'anthropic'、'claude'）
- 无 XML 标签
□ Hooks 使用 ${CLAUDE_PLUGIN_ROOT} 指定路径（不用相对路径）
□ 所有脚本可执行（chmod +x）

发布清单

□ plugin.json：包含 name/version/keywords
□ 不要在组件字段中包含标准路径
□ 本地 marketplace 可干净安装
□ 使用 /plugin-development:validate 校验
□ 测试所有命令、skill 与 hook
□ 存在 README.md 并附使用示例

红旗警示（若即将做以下事情请停止）

将 commands/、agents/、skills/ 或 hooks/ 放入 .claude-plugin/ → 位置错误（组件应放插件根目录）
向 plugin.json 添加 "commands": "./commands/" → 不必要（标准目录会自动发现，这样做会破坏功能）
在 hooks 中使用 ./scripts/format.sh 等相对路径 → 应使用 ${CLAUDE_PLUGIN_ROOT}/scripts/format.sh
测试前跳过 /plugin-development:validate → 始终先校验
忘记对 hook 脚本 chmod +x → 脚本不会执行（静默失败）
在 skill 名称中使用 'claude' 或 'anthropic' → 保留字（将被拒绝）

以上都会导致静默失败。有疑问时，进行校验。

为什么校验很重要

校验清单：跳过会导致插件无法加载，且无错误信息。
chmod +x scripts：跳过会导致 hooks 静默失败。
${CLAUDE_PLUGIN_ROOT}：跳过会在开发时可用，安装后失效。
标准目录规则：跳过会导致组件无法被发现。
运行 /plugin-development:validate 可在调试开始前捕获 90% 的问题。

故障排除

插件未加载？检查 plugin.json 路径是否相对于插件根目录。不要为标准目录包含 commands、agents、skills 或 hooks 字段。
命令未显示？确认插件根目录存在含 .md 文件的 commands/ 目录。不要为标准路径向 plugin.json 添加 commands 字段。
Hooks 未运行？确保脚本可执行（chmod +x）并使用 ${CLAUDE_PLUGIN_ROOT} 指定路径。
Skill 未触发？检查 name 与目录一致，且仅使用小写字母、数字与连字符（最多 64 字符）。确保 description 同时包含做什么与何时使用（最多 1024 字符）。两个字段都不能包含 XML 标签。

注意事项

对确定性任务优先使用模板与脚本，而非自由生成。
若需要写入，先提出命令或 PR 风格的 diff。
复杂审计请委托给 /agents plugin-reviewer。
测试前始终使用 /plugin-development:validate 校验。

官方文档：Anthropic 官方 skill 编写最佳实践参见 https://docs.anthropic.com/en/docs/agents-and-tools/agent-skills/skill-authoring-best-practices