⚡

插件验证与最佳实践Skill plugin-best-practices

本技能用于验证Claude Code插件的架构标准和最佳实践，确保插件开发符合规范，包括插件结构验证、清单文件审查、前端元数据合规性检查、工具调用模式验证等。关键词：Claude Code插件、验证、最佳实践、架构设计、软件开发、技能开发、插件开发。

架构设计 0 次安装 0 次浏览 更新于 3/16/2026

name: 插件最佳实践 description: 根据Agents、Skills、MCP和渐进披露的架构最佳实践验证Claude Code插件。用于验证插件结构、审查清单文件、检查前端元数据合规性或验证工具调用模式时使用。

插件验证与最佳实践

验证Claude Code插件以符合架构标准。SKILL.md作为导航指南；详细内容位于references/中。

快速开始

对插件运行验证：

python3 plugin-optimizer/scripts/validate-plugin.py <plugin-path>

对于特定检查：

python3 plugin-optimizer/scripts/validate-plugin.py <plugin-path> --check=manifest,frontmatter

组件选择指南

组件 何时使用 关键要求
指令型技能 用户调用的工作流，线性过程 命令式语音，基于阶段，在commands中声明
知识型技能 代理的参考知识 声明式语音，基于主题，在skills中声明
代理 隔离的、专门的决策制定 受限工具，2-4个<example>块，隔离上下文
MCP服务器 外部工具/数据集成 stdio/http/sse传输，${CLAUDE_PLUGIN_ROOT}路径
LSP服务器 IDE功能（转到定义） 语言服务器二进制文件，扩展映射
钩子 事件驱动自动化 PreToolUse/PostToolUse事件，命令/提示/代理类型

参见./references/component-model.md获取详细选择标准和./references/components/获取实施指南。

渐进披露

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

级别 内容 令牌预算 加载
1 元数据（名称+描述） ~100令牌 始终（启动时）
2 SKILL.md正文 低于5k令牌 当技能触发时
3 References/文件 有效无限 通过bash按需

实施模式：

  • SKILL.md：概述和导航到参考文件
  • References/：详细规格、示例、模式
  • Scripts/：可执行实用程序（执行前无上下文成本）

参见./references/component-model.md获取完整令牌预算指南。

验证工作流

  1. 结构：文件模式、目录布局、烤肉串命名法
  2. 清单：plugin.json必需字段和模式合规性
  3. 前端元数据：组件中的YAML前端元数据，第三人称描述
  4. 工具调用：反模式检测（隐式与显式工具调用）
  5. 令牌预算：渐进披露合规性（SKILL.md低于5k令牌）

使用-v标志运行验证以显示所有通过检查。

参见./references/validation-checklist.md获取完整标准。

要求级别 (RFC 2119)

MUST：绝对要求 - 没有它插件无法正确运行

  • 仅使用MUST，避免REQUIRED或SHALL

MUST NOT：绝对禁止 - 行为被禁止

  • 仅使用MUST NOT，避免SHALL NOT

SHOULD：推荐实践 - 存在有效理由忽略，但必须理解含义

  • 仅使用SHOULD，避免RECOMMENDED
  • 在选择不同路线前考虑安全含义

SHOULD NOT：不鼓励但可能在特定情况下有效

  • 仅使用SHOULD NOT，避免NOT RECOMMENDED
  • 实施前权衡全部含义

MAY：真正可选 - 供应商选择

  • 仅使用MAY，避免OPTIONAL
  • 没有功能的实施必须与包含功能的实施互操作

参见./references/rfc-2119.md获取完整RFC 2119规范。

关键模式

工具调用规则

工具 样式 示例
读、写、编辑、全局、搜索 隐式 “查找文件匹配…”
Bash 隐式 “运行git status”
任务 隐式 “启动plugin-name:agent-name代理”
技能 显式 “使用Skill工具加载plugin-name:skill-name技能”
TaskCreate 显式 “使用TaskCreate工具跟踪进度”
AskUserQuestion 显式 “使用AskUserQuestion工具以[动作]”

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

allowed-tools：切勿使用裸Bash - 总是使用过滤器如Bash(git:*)。

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

参见./references/tool-invocations.md获取完整模式和反模式。

技能前端元数据 (官方最佳实践)

必需字段：

  • name：最大64字符，仅小写字母/数字/连字符
  • description：最大1024字符，第三人称语音，包括触发短语如"Use when…"

附加字段支持但影响渐进披露对齐。

代理前端元数据

必需字段：

  • name：3-50字符，烤肉串命名法
  • model：继承、sonnet、opus或haiku
  • color：蓝色、青色、绿色、黄色、品红或红色
  • <example>块：2-4个必需以路由器友好

CO-STAR框架：

  • Context：背景信息
  • Objective：要实现的
  • Style：语调/格式
  • Tone：态度
  • Audience：为谁设计？
  • Response：输出格式

参见./references/components/agents.md获取完整代理设计指南。

任务管理

使用TaskCreate用于：

  • 具有3+个不同步骤的任务
  • 多文件/多组件工作
  • 顺序依赖

不使用TaskCreate用于：

  • 单文件编辑
  • 1-2步操作
  • 纯研究/阅读

核心要求：

  • 双重形式命名：主题（“运行测试”）+主动形式（“正在运行测试”）
  • 实时更新：在开始前标记in_progress，完成后标记completed
  • 任何时间单个活动任务
  • 诚实状态：仅在完全完成后标记completed

参见./references/task-management.md获取完整模式和示例。

MCP服务器配置

传输类型：

  • stdio：本地CLI工具（git、docker、npm） - 使用command、args、env
  • http：远程API（SaaS、云） - 使用url、headers
  • sse：实时流式传输（监控、实时更新） - 使用url、headers

安全：

  • 切勿硬编码秘密 - 总是使用${ENV_VAR}语法
  • 记录所需环境变量
  • 提供.env.example模板

参见./references/mcp-patterns.md获取完整MCP集成模式。

前端元数据要求 (完整)

技能前端元数据：

  • 必需：name（最大64字符，小写/连字符），description（最大1024字符，第三人称）
  • 可选：argument-hint、allowed-tools、model、disable-model-invocation、user-invocable、context、agent、hooks

代理前端元数据：

  • 必需：name（3-50字符，烤肉串命名法），model、color，2-4个<example>块

命令前端元数据：

  • 必需：description、argument-hint（如果无参数必须为空/省略）
  • 可选：allowed-tools、disable-model-invocation

参见./references/components/skills.md、./references/components/agents.md和./references/components/commands.md获取完整前端元数据规范。

目录结构

标准布局：

plugin-name/
├── .claude-plugin/plugin.json    # 清单（在此声明组件）
├── skills/                       # 代理技能（推荐）
│   └── skill-name/
│       ├── SKILL.md
│       └── references/
├── commands/                     # 遗留命令（可选）
├── agents/                       # 子代理定义
├── hooks/hooks.json              # 钩子配置
├── .mcp.json                     # MCP服务器定义
├── .lsp.json                     # LSP服务器配置
└── scripts/                      # 可执行脚本

关键规则：

  • 组件位于插件根目录，不在.claude-plugin/内
  • 脚本必须具有shebang可执行
  • 脚本必须使用${CLAUDE_PLUGIN_ROOT}用于路径
  • 所有路径必须相对并以./开始

参见./references/directory-structure.md获取完整布局指南。

钩子配置

可用事件：

  • PreToolUse、PostToolUse、PostToolUseFailure
  • PermissionRequest、UserPromptSubmit、Notification
  • Stop、SubagentStart、SubagentStop
  • SessionStart、SessionEnd、PreCompact

钩子类型：

  • command：执行shell命令或脚本
  • prompt：使用LLM评估（使用$ARGUMENTS占位符）
  • agent：运行具有工具的代理验证器

最佳实践：

  • 在bash钩子中严格验证输入
  • 总是引用bash变量（例如，"$CLAUDE_PROJECT_DIR"）
  • 返回有效的JSON用于决策（allow/deny）和消息
  • 退出代码：0（成功），1（非阻塞），2（阻塞错误）

参见./references/components/hooks.md获取完整钩子模式和模板。

代理团队与子代理

子代理

插件定义的自主子进程，具有隔离上下文和受限工具。

何时使用：

  • 隔离的、专门的决策制定与专用系统提示
  • 顺序或单向工作流
  • 专注任务，只有结果重要
  • 偏好较低令牌成本

特点：

  • 定义为agents/目录中的.md文件
  • 隔离上下文，受限工具允许列表
  • 2-4个<example>块以路由器友好
  • 结果总结回主上下文

用法：

启动`plugin-name:agent-name`代理以处理此任务。

代理团队 (实验性)

多个Claude Code会话，具有共享任务列表和直接代理间通信。可以生成插件子代理或内置代理类型作为队友。

何时使用：

  • 研究和审查：并行调查与共享发现和挑战
  • 新模块/功能：每个队友拥有单独部分
  • 调试：并行测试竞争假设
  • 跨层协调：前端、后端、测试分给不同队友

何时不使用：

  • 顺序任务、同文件编辑、高依赖工作
  • 协调开销超过益处
  • 常规任务（单会话更成本有效）

比较：

子代理 代理团队
上下文 返回调用者 完全独立
通信 仅到主代理 直接点对点
协调 由主代理管理 共享任务列表
令牌成本 较低（总结） 较高（完整实例）

用法：

插件子代理作为队友：

创建一个具有插件定义代理的代理团队：
- plugin-name:specialist-a 用于方面A
- plugin-name:specialist-b 用于方面B

内置代理类型：

创建一个具有专门审查者的代理团队：
- 探索代理专注于维度1
- 探索代理专注于维度2
- 通用代理用于合成

启用：

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

最佳实践：

  • 给予队友特定上下文并避免文件冲突
  • 适当大小任务（具有清晰可交付物的自包含单元）
  • 如果需要协调，告诉领导"等待队友完成"
  • 在并行实施前从研究/审查任务开始

限制：无恢复、每会话一个团队、无嵌套、固定领导、慢关机。

参见./references/agent-teams.md获取完整指南和./references/component-model.md获取代理使用模式。

并行代理执行

何时使用：

  • 任务独立且结果可事后合并
  • 多个分析可同时运行

请求模式：

  • 显式：“同时启动所有代理：X代理、Y代理、Z代理”
  • 措辞：“启动3个并行代理以独立处理不同方面”

最佳实践：

  • "parallel"或"simultaneously"在请求中显式出现
  • 描述性样式命名代理和意图
  • 合并合并发现并解决冲突

常见模式：

  1. 顺序设置（如果需要）
  2. 并行启动专门分析
  3. 合并结果并呈现统一输出

参见./references/parallel-execution.md获取并行协调模式。

参考目录

验证与质量

  • ./references/validation-checklist.md - 完整质量检查表
  • ./references/rfc-2119.md - 要求级别 (MUST/SHOULD/MAY)

组件实施

  • ./references/component-model.md - 组件类型、选择标准、令牌预算
  • ./references/components/skills.md - 技能结构、前端元数据、渐进披露
  • ./references/components/agents.md - 代理设计、CO-STAR框架、示例块
  • ./references/components/commands.md - 命令前端元数据、动态上下文
  • ./references/components/hooks.md - 钩子事件、类型、bash模板
  • ./references/components/mcp-servers.md - MCP配置、stdio/http/sse
  • ./references/components/lsp-servers.md - LSP设置、二进制要求

配置与集成

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

开发模式

  • ./references/tool-invocations.md - 工具使用模式和反模式
  • ./references/task-management.md - TaskCreate模式、双重形式命名
  • ./references/cli-commands.md - 插件管理的CLI命令

高级主题

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