plugin-best-practices

插件验证与最佳实践

根据架构标准验证 Claude Code 插件。本文件是导航指南；详细内容位于 references/ 中。

快速开始

运行插件验证：

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/validate-plugin.py <plugin-path>

仅运行特定检查：

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/validate-plugin.py <plugin-path> --check=manifest,frontmatter

组件选择指南

组件	适用场景	主要要求
指令型 Skills	用户调用的工作流、线性流程	使用祈使语气，按阶段组织，在 commands 中声明；名称以 use-<action> 为前缀（例如 use-kicad-cli）
知识型 Skills	提供给 Agent 的参考知识	使用陈述语气，按主题组织，在 skills 中声明；名称以 using-<topic> 为前缀（例如 using-git-worktrees）
Agents	隔离的专业决策	限制工具，包含 2-4 个 <example> 块，使用隔离上下文
MCP 服务	外部工具/数据集成	使用 stdio/http/sse 传输，采用 ${CLAUDE_PLUGIN_ROOT} 路径
LSP 服务	IDE 功能（跳转到定义）	语言服务二进制文件，扩展映射
Hooks	事件驱动的自动化	生命周期事件，command/http/mcp_tool/prompt/agent 类型
Monitors	长时间运行的监视器（日志、部署）	每个条目都需包含 name+command+description；v2.1.105+
Themes	捆绑的颜色预设	JSON，包含 name、base、overrides
Output Styles	调整响应格式	Markdown，包含 name + description frontmatter

有关详细的选择标准，请参阅 ./references/component-model.md；有关实现指南，请参阅 ./references/components/。

渐进式披露

三级令牌结构可确保高效使用上下文：

级别	内容	令牌预算	加载时机
1	元数据（名称 + 描述）	~100 个令牌	始终（启动时）
2	SKILL.md 正文	少于 5k 个令牌	触发技能时
3	References/ 文件	实际上不受限制	通过 bash 按需加载

实现模式：

• SKILL.md：概述及指向参考文件的导航
• References/：详细规范、示例、模式
• Scripts/：可执行工具（执行前不占用上下文）

完整的令牌预算指南请参阅 ./references/component-model.md。

验证工作流

以下五项顺序检查涵盖插件质量的所有方面：

1. 结构：文件模式、目录布局、kebab-case 命名
2. 清单：plugin.json 必填字段和架构合规性
3. Frontmatter：组件中的 YAML frontmatter、第三人称描述
4. 工具调用：反模式检测（隐式与显式工具调用）
5. 令牌预算：渐进式披露合规性（SKILL.md 少于 5k 个令牌）

使用 -v 标志运行验证，可通过详细输出查看所有通过的检查。

完整标准请参阅 ./references/validation-checklist.md。

要求级别（RFC 2119）

插件文档采用 RFC 2119 要求级别：

• MUST / MUST NOT：绝对要求或禁止事项
• SHOULD / SHOULD NOT：推荐做法，但存在已知例外
• MAY：完全可选

完整的 RFC 2119 规范请参阅 ./references/rfc-2119.md。

关键模式

工具调用规则

工具	方式	示例
Read、Write、Edit、Glob、Grep	隐式	“查找匹配……的文件”
Bash	隐式	“运行 git status”
Task	隐式	“启动 plugin-name:agent-name Agent”
Skill	显式	“使用 Skill 工具加载 plugin-name:skill-name 技能”
TaskCreate	显式	“使用 TaskCreate 工具跟踪进度”
AskUserQuestion	显式	“使用 AskUserQuestion 工具执行[操作]”
MCP 工具	隐式	“查询数据库中的用户记录”

限定名称：插件组件必须使用 plugin-name:component-name 格式。

allowed-tools：绝不能只使用 Bash，始终使用 Bash(git:*) 之类的过滤器。

内联 Bash：对于动态上下文，使用内联语法（感叹号 + 反引号 + 命令 + 反引号）。

MCP 工具调用：使用自然语言描述意图——Claude 会自动识别合适的 MCP 工具。切勿在技能内容中指定 mcp__server__tool 之类的确切 MCP 工具名称。

有关完整模式和反模式，请参阅 ./references/tool-invocations.md。 有关 MCP 专用调用模式，请参阅 ./references/mcp-patterns.md。

技能 Frontmatter（官方最佳实践）

必填字段：

• name：最多 64 个字符，只能包含小写字母、数字和连字符。按类型命名：指令型技能使用 use-<action> 前缀（例如，use-kicad-cli）；知识型技能使用 using-<topic> 前缀（例如，using-git-worktrees）。
• description：最多 1024 个字符。必须使用第三人称，并包含具体的触发短语。

Description 最佳实践：

要求	说明
人称	仅使用第三人称（“应在……时使用此技能”）
结构	[功能说明]。在[场景 1]、[场景 2]或[用户短语]出现时使用。
用途	技能发现——Claude 使用此信息从 100 多个技能中进行选择
触发短语	包含具体的用户短语，例如“验证插件”“检查 frontmatter”

支持其他字段，但会影响渐进式披露的一致性。

有关完整的 frontmatter 规范，请参阅 ./references/components/skills.md。

Agent Frontmatter

必填字段（依据上游规范）：

• name：3–50 个字符，使用 kebab-case
• description：触发条件以及 2–4 个 <example> 块

可选字段：model、color、effort、maxTurns、tools、disallowedTools、skills、memory、background、isolation（仅 "worktree" 有效）。

插件 Agent 中禁止的字段（安全要求）：hooks、mcpServers、permissionMode。

字段顺序：name → description（包含触发条件和 <example> 块的 | 块标量）→ 其他 YAML 字段 → 结束的 ---。在 description 之外使用裸露的 <example> 块会导致 YAML 解析失败。

有关完整的 Agent 设计指南（包括 CO-STAR 框架），请参阅 ./references/components/agents.md。

任务管理

包含 3 个或更多不同步骤、多文件工作或顺序依赖的任务应使用 TaskCreate。单文件编辑和 1–2 步操作则不需要。

核心要求：

• 双形式命名：subject（“运行测试”）+ activeForm（“正在运行测试”）
• 开始前标记为 in_progress，完成后标记为 completed
• 仅在全部完成后才标记为 completed

有关完整模式和示例，请参阅 ./references/task-management.md。

MCP 服务配置

MCP 服务配置在插件根目录的 .mcp.json 中，或以内联方式配置在 plugin.json 的 mcpServers 下。支持三种传输类型：stdio（本地命令行工具）、http（远程 API，支持最广泛）和 sse（实时流式传输）。

绝不要硬编码密钥——始终使用 ${ENV_VAR} 语法。

有关完整的 MCP 集成模式，请参阅 ./references/mcp-patterns.md。 有关组件配置详情，请参阅 ./references/components/mcp-servers.md。

Hook 配置

Hook 事件覆盖完整的会话生命周期（28 个以上事件，包括 PreToolUse、PostToolUse、PostToolUseFailure、PostToolBatch、PermissionRequest、PermissionDenied、UserPromptSubmit、UserPromptExpansion、Setup、Notification、Stop/StopFailure、SubagentStart/SubagentStop、TaskCreated/TaskCompleted、TeammateIdle、InstructionsLoaded、ConfigChange、CwdChanged、FileChanged、WorktreeCreate/WorktreeRemove、PreCompact/PostCompact、Elicitation/ElicitationResult、SessionStart/SessionEnd）。五种 Hook 类型：command、http、mcp_tool、prompt、agent。

完整事件表和 AI 原生结构化输出模式，请参阅 ./references/components/hooks.md。

Agent Teams 与子 Agent

子 Agent 是隔离的单向子进程，会将结果返回给调用方。Agent Teams 则由多个独立会话组成，共享任务列表并直接进行点对点通信，适用于并行调查、多模块功能和竞争性假设。

	子 Agent	Agent Teams
上下文	返回给调用方	完全独立
通信	仅与主 Agent 通信	直接点对点通信
Token 成本	较低（经过总结）	较高（完整实例）

Agent Teams 目前处于实验阶段。使用 export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 启用。

完整指南请参阅 ./references/agent-teams.md，并行协调模式请参阅 ./references/parallel-execution.md。

目录结构

标准布局：

plugin-name/
├── .claude-plugin/plugin.json    # Manifest (declare components here)
├── skills/                       # Agent Skills (RECOMMENDED)
│   └── skill-name/
│       ├── SKILL.md
│       └── references/
├── commands/                     # Skills as flat .md files (legacy)
├── agents/                       # Subagent definitions
├── output-styles/                # Output style markdown
├── themes/                       # Color theme JSON
├── monitors/monitors.json        # Background monitor configs
├── hooks/hooks.json              # Hook configuration
├── bin/                          # Executables added to Bash PATH
├── settings.json                 # Plugin default settings
├── .mcp.json                     # MCP server definitions
├── .lsp.json                     # LSP server configurations
└── scripts/                      # Executable scripts

重要规则：

• 组件位于插件根目录，不要放在 .claude-plugin/ 内
• 脚本必须包含 shebang，且可执行
• 脚本必须使用 ${CLAUDE_PLUGIN_ROOT} 指定路径
• 所有路径必须是相对路径，并以 ./ 开头

完整布局指南请参阅 ./references/directory-structure.md。

参考目录

验证与质量

• ./references/validation-checklist.md - 完整的质量检查清单
• ./references/rfc-2119.md - 要求级别（MUST/SHOULD/MAY）

组件实现

• ./references/component-model.md - 组件类型、选择标准、Token 预算
• ./references/components/skills.md - Skill 结构、frontmatter、渐进式披露
• ./references/components/agents.md - Agent 设计、CO-STAR 框架、禁止字段
• ./references/components/commands.md - 命令 frontmatter、动态上下文
• ./references/components/hooks.md - Hook 事件、类型、AI 原生模式、模板
• ./references/components/mcp-servers.md - MCP 配置、stdio/http/sse
• ./references/components/lsp-servers.md - LSP 设置、二进制文件要求
• ./references/components/monitors.md - 后台监视器配置
• ./references/components/themes.md - 颜色主题 JSON 结构
• ./references/components/output-styles.md - 输出样式 frontmatter

配置与集成

• ./references/directory-structure.md - 插件布局、命名约定
• ./references/manifest-schema.md - plugin.json 架构、必填字段
• ./references/mcp-patterns.md - MCP 传输类型、安全最佳实践

开发模式

• ./references/tool-invocations.md - 工具使用模式与反模式
• ./references/tool-design-philosophy.md - 设计工具以发挥 Claude 优势的原则
• ./references/task-management.md - TaskCreate 模式、双形式命名
• ./references/cli-commands.md - 用于插件管理的 CLI 命令

高级主题

• ./references/agent-teams.md - 可并行处理的任务、多视角分析
• ./references/parallel-execution.md - 并行 Agent 协调模式
• ./references/debugging.md - 常见问题、错误消息、故障排除