plugin-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Plugin Validation & Best Practices

插件验证与最佳实践

Validate Claude Code plugins against architectural standards. SKILL.md serves as a navigation guide; detailed content lives in

references/

针对架构标准验证Claude Code插件。SKILL.md作为导航指南，详细内容存放在

references/

目录中。

Quick Start

快速开始

Run validation on a plugin:

bash

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

For specific checks only:

bash

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

对插件运行验证：

bash

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

仅运行特定检查项：

bash

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

Component Selection Guide

组件选择指南

Component	When to Use	Key Requirements
Instruction-type Skills	User-invoked workflows, linear process	Imperative voice, phase-based, declared in `commands`
Knowledge-type Skills	Reference knowledge for agents	Declarative voice, topic-based, declared in `skills`
Agents	Isolated, specialized decision-making	Restricted tools, 2-4 `<example>` blocks, isolated context
MCP Servers	External tool/data integration	stdio/http/sse transport, ${CLAUDE_PLUGIN_ROOT} paths
LSP Servers	IDE features (go to definition)	Language server binary, extension mapping
Hooks	Event-driven automation	PreToolUse/PostToolUse events, command/prompt/agent types

See

./references/component-model.md

for detailed selection criteria and

./references/components/

for implementation guides.

组件	使用场景	核心要求
指令型Skill	用户调用的工作流、线性流程	命令式语气、分阶段、在 `commands` 中声明
知识型Skill	供Agent使用的参考知识	陈述式语气、按主题划分、在 `skills` 中声明
Agent	独立的专业决策模块	受限工具集、2-4个 `<example>` 块、独立上下文
MCP服务器	外部工具/数据集成	stdio/http/sse传输协议、使用${CLAUDE_PLUGIN_ROOT}路径
LSP服务器	IDE功能（如跳转到定义）	语言服务器二进制文件、扩展映射
Hook	事件驱动的自动化	PreToolUse/PostToolUse事件、命令/提示词/Agent类型

查看

./references/component-model.md

获取详细选择标准，

./references/components/

目录获取实现指南。

Progressive Disclosure

渐进式披露

Three-tier token structure ensures efficient context usage:

Level	Content	Token Budget	Loading
1	Metadata (name + description)	~100 tokens	Always (at startup)
2	SKILL.md body	Under 5k tokens	When skill triggered
3	References/ files	Effectively unlimited	On-demand via bash

Implementation Pattern:

SKILL.md: Overview and navigation to reference files
References/: Detailed specs, examples, patterns
Scripts/: Executable utilities (no context cost until executed)

See

./references/component-model.md

for complete token budget guidelines.

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

层级	内容	令牌预算	加载时机
1	元数据（名称+描述）	~100令牌	始终加载（启动时）
2	SKILL.md主体内容	不超过5k令牌	Skill触发时
3	References/目录文件	实际上无限制	通过bash按需加载

实现模式:

SKILL.md：概述及参考文件导航
References/: 详细规范、示例、模式
Scripts/: 可执行工具（执行前无上下文成本）

查看

./references/component-model.md

获取完整的令牌预算指南。

Validation Workflow

验证工作流

Structure: File patterns, directory layout, kebab-case naming
Manifest: plugin.json required fields and schema compliance
Frontmatter: YAML frontmatter in components, third-person descriptions
Tool Invocations: Anti-pattern detection (implicit vs explicit tool calls)
Token Budget: Progressive disclosure compliance (under 5k tokens for SKILL.md)

Run validation with

-v

flag for verbose output showing all passing checks.

See

./references/validation-checklist.md

for complete criteria.

结构：文件模式、目录布局、短横线命名法（kebab-case）
清单文件：plugin.json必填字段及 schema 合规性
前置内容：组件中的YAML前置内容、第三人称描述
工具调用：反模式检测（隐式vs显式工具调用）
令牌预算：渐进式披露合规性（SKILL.md不超过5k令牌）

运行验证时添加

-v

参数可查看所有通过检查项的详细输出。

查看

./references/validation-checklist.md

获取完整检查标准。

Requirement Levels (RFC 2119)

要求级别（RFC 2119）

MUST: Absolute requirement - plugin will not function correctly without it

Use
```
MUST
```
only, avoid
```
REQUIRED
```
or
```
SHALL
```

MUST NOT: Absolute prohibition - behavior is forbidden

Use
```
MUST NOT
```
only, avoid
```
SHALL NOT
```

SHOULD: Recommended practice - valid reasons to ignore exist, but implications MUST be understood

Use
```
SHOULD
```
only, avoid
```
RECOMMENDED
```
Consider security implications before choosing different course

SHOULD NOT: Discouraged but may be valid in specific circumstances

Use
```
SHOULD NOT
```
only, avoid
```
NOT RECOMMENDED
```
Weigh full implications before implementing

MAY: Truly optional - vendor choice

Use
```
MAY
```
only, avoid
```
OPTIONAL
```
Implementations without a feature MUST interoperate with those that include it

See

./references/rfc-2119.md

for complete RFC 2119 specification.

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规范。

Critical Patterns

关键模式

Tool Invocation Rules

工具调用规则

Tool	Style	Example
Read, Write, Edit, Glob, Grep	Implicit	"Find files matching..."
Bash	Implicit	"Run `git status` "
Task	Implicit	"Launch `plugin-name:agent-name` agent"
Skill	Explicit	"Load `plugin-name:skill-name` skill using the Skill tool"
TaskCreate	Explicit	"Use TaskCreate tool to track progress"
AskUserQuestion	Explicit	"Use `AskUserQuestion` tool to [action]"

Qualified names: MUST use

plugin-name:component-name

format for plugin components.

allowed-tools: NEVER use bare

Bash

- always use filters like

Bash(git:*)

Inline Bash: Use inline syntax (exclamation + backtick + command + backtick) for dynamic context.

See

./references/tool-invocations.md

for complete patterns and anti-patterns.

工具	调用风格	示例
Read, Write, Edit, Glob, Grep	隐式	"查找匹配...的文件"
Bash	隐式	"执行 `git status` "
Task	隐式	"启动 `plugin-name:agent-name` agent"
Skill	显式	"使用Skill工具加载 `plugin-name:skill-name` skill"
TaskCreate	显式	"使用TaskCreate工具跟踪进度"
AskUserQuestion	显式	"使用 `AskUserQuestion` 工具执行[操作]"

限定名称：插件组件必须使用

plugin-name:component-name

格式。

allowed-tools：绝对不能使用裸

Bash

- 必须使用

Bash(git:*)

这类过滤器。

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

查看

./references/tool-invocations.md

获取完整模式及反模式。

Skill Frontmatter (Official Best Practices)

Skill前置内容（官方最佳实践）

Required fields:

```
name
```
: Max 64 chars, lowercase letters/numbers/hyphens only
```
description
```
: Max 1024 chars, third-person voice, includes trigger phrases like "Use when..."

Additional fields are supported but affect progressive disclosure alignment.

必填字段:

```
name
```
：最多64字符，仅允许小写字母/数字/短横线
```
description
```
：最多1024字符，第三人称语气，包含触发短语如"适用于...场景"

可选字段受支持，但会影响渐进式披露的一致性。

Agent Frontmatter

Agent前置内容

Required fields:

```
name
```
: 3-50 chars, kebab-case
```
model
```
: inherit, sonnet, opus, or haiku
```
color
```
: blue, cyan, green, yellow, magenta, or red
<example>
blocks: 2-4 required for router-friendliness

CO-STAR Framework:

Context: Background info
Objective: What to achieve
Style: Tone/Format
Tone: Attitude
Audience: Who is this for?
Response: Format of output

See

./references/components/agents.md

for complete agent design guidelines.

必填字段:

```
name
```
：3-50字符，短横线命名法（kebab-case）
```
model
```
: inherit, sonnet, opus, 或 haiku
```
color
```
: blue, cyan, green, yellow, magenta, 或 red
<example>
块: 必须有2-4个以适配路由

CO-STAR框架:

Context: 背景信息
Objective: 目标
Style: 语气/格式
Tone: 态度
Audience: 受众
Response: 输出格式

查看

./references/components/agents.md

获取完整的Agent设计指南。

Task Management

任务管理

Use TaskCreate for:

Tasks with 3+ distinct steps
Multi-file/multi-component work
Sequential dependencies

Don't use TaskCreate for:

Single file edits
1-2 step operations
Pure research/reading

Core Requirements:

Dual form naming: subject ("Run tests") + activeForm ("Running tests")
Real-time updates: mark
```
in_progress
```
BEFORE starting,
```
completed
```
AFTER finishing
Single active task at any time
Honest status: only mark
```
completed
```
when FULLY done

See

./references/task-management.md

for complete patterns and examples.

适合使用TaskCreate的场景:

包含3个以上不同步骤的任务
多文件/多组件工作
有顺序依赖的任务

不适合使用TaskCreate的场景:

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

核心要求:

双重命名形式：主题（如"运行测试"）+ activeForm（如"正在运行测试"）
实时更新：开始前标记为
```
in_progress
```
，完成后标记为
```
completed
```
同一时间仅存在一个活跃任务
真实状态：仅在完全完成时标记为
```
completed
```

查看

./references/task-management.md

获取完整模式及示例。

MCP Server Configuration

MCP服务器配置

Transport Types:

stdio: Local CLI tools (git, docker, npm) - uses
```
command
```
,
```
args
```
,
```
env
```
http: Remote APIs (SaaS, cloud) - uses
```
url
```
,
```
headers
```
sse: Real-time streaming (monitoring, live updates) - uses
```
url
```
,
```
headers
```

Security:

NEVER hardcode secrets - always use
```
${ENV_VAR}
```
syntax
Document required environment variables
Provide
```
.env.example
```
template

See

./references/mcp-patterns.md

for complete MCP integration patterns.

传输类型:

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集成模式。

Frontmatter Requirements (Complete)

前置内容要求（完整版）

Skill Frontmatter:

Required:
```
name
```
(max 64 chars, lowercase/hyphens),
```
description
```
(max 1024 chars, third-person)

Optional:

argument-hint

allowed-tools

model

disable-model-invocation

user-invocable

context

agent

hooks

Agent Frontmatter:

Required:
```
name
```
(3-50 chars, kebab-case),
```
model
```
,
```
color
```
, 2-4
```
<example>
```
blocks

Command Frontmatter:

Required:
```
description
```
,
```
argument-hint
```
(MUST be empty/omitted if no arguments)
Optional:
```
allowed-tools
```
,
```
disable-model-invocation
```

See

./references/components/skills.md

./references/components/agents.md

, and

./references/components/commands.md

for complete frontmatter specifications.

Skill前置内容:

必填:
```
name
```
（最多64字符，小写/短横线）,
```
description
```
（最多1024字符，第三人称）

可选:

argument-hint

allowed-tools

model

disable-model-invocation

user-invocable

context

agent

hooks

Agent前置内容:

必填:
```
name
```
（3-50字符，短横线命名法）,
```
model
```
,
```
color
```
, 2-4个
```
<example>
```
块

Command前置内容:

必填:
```
description
```
,
```
argument-hint
```
（无参数时必须为空/省略）
可选:
```
allowed-tools
```
,
```
disable-model-invocation
```

查看

./references/components/skills.md

、

./references/components/agents.md

和

./references/components/commands.md

获取完整的前置内容规范。

Directory Structure

目录结构

Standard Layout:

plugin-name/
├── .claude-plugin/plugin.json    # Manifest (declare components here)
├── skills/                       # Agent Skills (RECOMMENDED)
│   └── skill-name/
│       ├── SKILL.md
│       └── references/
├── commands/                     # Legacy commands (optional)
├── agents/                       # Subagent definitions
├── hooks/hooks.json              # Hook configuration
├── .mcp.json                     # MCP server definitions
├── .lsp.json                     # LSP server configurations
└── scripts/                      # Executable scripts

Critical Rules:

Components live at plugin root, NOT inside
```
.claude-plugin/
```
Scripts MUST be executable with shebangs
Scripts MUST use
```
${CLAUDE_PLUGIN_ROOT}
```
for paths
All paths MUST be relative and start with
```
./
```

See

./references/directory-structure.md

for complete layout guidelines.

标准布局:

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

关键规则:

组件存放在插件根目录，而非
```
.claude-plugin/
```
内部
脚本必须包含shebang头以确保可执行
脚本必须使用
```
${CLAUDE_PLUGIN_ROOT}
```
路径
所有路径必须是相对路径且以
```
./
```
开头

查看

./references/directory-structure.md

获取完整的布局指南。

Hook Configuration

Hook配置

Available Events:

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

Hook Types:

```
command
```
: Execute shell commands or scripts
```
prompt
```
: Evaluate with LLM (uses
```
$ARGUMENTS
```
placeholder)
```
agent
```
: Run agentic verifier with tools

Best Practices:

Validate inputs strictly in bash hooks
Always quote bash variables (e.g.,
```
"$CLAUDE_PROJECT_DIR"
```
)
Return valid JSON for decisions (
```
allow
```
/
```
deny
```
) and messages
Exit codes: 0 (success), 1 (non-blocking), 2 (blocking error)

See

./references/components/hooks.md

for complete hook patterns and templates.

可用事件:

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

Hook类型:

```
command
```
: 执行shell命令或脚本
```
prompt
```
: 由LLM评估（使用
```
$ARGUMENTS
```
占位符）
```
agent
```
: 使用工具运行Agent验证器

最佳实践:

在bash hook中严格验证输入
始终对bash变量加引号（如
```
"$CLAUDE_PROJECT_DIR"
```
）
返回有效的JSON格式决策（
```
allow
```
/
```
deny
```
）和消息
退出码: 0（成功）, 1（非阻塞）, 2（阻塞错误）

查看

./references/components/hooks.md

获取完整的Hook模式及模板。

Agent Teams vs Subagents

Agent团队 vs 子Agent

Subagents

子Agent

Plugin-defined autonomous subprocesses with isolated context and restricted tools.

When to Use:

Isolated, specialized decision-making with dedicated system prompt
Sequential or single-direction workflow
Focused tasks where only the result matters
Lower token cost preferred

Characteristics:

Defined as
```
.md
```
files in
```
agents/
```
directory
Isolated context, restricted tool allowlists
2-4
```
<example>
```
blocks for router-friendliness
Results summarized back to main context

Usage:

markdown

Launch `plugin-name:agent-name` agent to handle this task.

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

使用场景:

具有独立系统提示的专业决策模块
顺序或单向工作流
仅关注结果的聚焦任务
偏好较低令牌成本

特性:

定义为
```
agents/
```
目录下的
```
.md
```
文件
独立上下文、受限工具允许列表
2-4个
```
<example>
```
块以适配路由
结果汇总后返回主上下文

使用方式:

markdown

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

Agent Teams (Experimental)

Agent团队（实验性）

Multiple Claude Code sessions with shared task list and direct inter-agent communication. Can spawn plugin subagents or built-in agent types as teammates.

When to Use:

Research and review: Parallel investigation with shared findings and challenges
New modules/features: Each teammate owns separate piece
Debugging: Competing hypotheses tested in parallel
Cross-layer coordination: Frontend, backend, tests split across teammates

When NOT to Use:

Sequential tasks, same-file edits, high-dependency work
Coordination overhead exceeds benefit
Routine tasks (single session more cost-effective)

Comparison:

	Subagents	Agent Teams
Context	Returns to caller	Fully independent
Communication	To main agent only	Direct peer-to-peer
Coordination	Managed by main agent	Shared task list
Token cost	Lower (summarized)	Higher (full instances)

Usage:

Plugin subagents as teammates:

markdown

Create an agent team with plugin-defined agents:
- plugin-name:specialist-a for aspect A
- plugin-name:specialist-b for aspect B

Built-in agent types:

markdown

Create an agent team with specialized reviewers:
- Explore agent focused on dimension 1
- Explore agent focused on dimension 2
- general-purpose agent for synthesis

Enable:

bash

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Best Practices:

Give teammates specific context and avoid file conflicts
Size tasks appropriately (self-contained units with clear deliverables)
Tell lead to "Wait for teammates to finish" if coordination needed
Start with research/review tasks before parallel implementation

Limitations: No resumption, one team per session, no nesting, fixed lead, slow shutdown.

See

./references/agent-teams.md

for complete guide and

./references/component-model.md

for agent usage patterns.

多个Claude Code会话，共享任务列表并支持Agent间直接通信。可将插件子Agent或内置Agent类型作为团队成员。

使用场景:

研究与评审: 并行调查，共享发现与挑战
新模块/功能: 每个成员负责独立部分
调试: 并行测试竞争性假设
跨层协调: 前端、后端、测试任务拆分给不同成员

不适用场景:

顺序任务、单文件编辑、高依赖工作
协调成本超过收益
常规任务（单会话更经济）

对比:

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

使用方式:

插件子Agent作为团队成员:

markdown

创建包含插件定义Agent的团队：
- plugin-name:specialist-a 负责A方面
- plugin-name:specialist-b 负责B方面

内置Agent类型:

markdown

创建包含专业评审的Agent团队：
- 探索Agent聚焦维度1
- 探索Agent聚焦维度2
- 通用Agent负责整合

启用方式:

bash

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

最佳实践:

为团队成员提供特定上下文，避免文件冲突
合理拆分任务（独立单元，交付物明确）
若需要协调，告知负责人"等待成员完成"
先从研究/评审任务开始，再尝试并行实现

限制: 不支持恢复，每个会话仅一个团队，不支持嵌套，固定负责人，关闭速度慢。

查看

./references/agent-teams.md

获取完整指南，

./references/component-model.md

获取Agent使用模式。

Parallel Agent Execution

并行Agent执行

When to Use:

Tasks are independent and results can be merged afterward
Multiple analyses can run simultaneously

Request Patterns:

Explicit: "Launch all agents simultaneously: X agent, Y agent, Z agent"
Phrasing: "Launch 3 parallel agents to process different aspects independently"

Best Practices:

"parallel" or "simultaneously" appears explicitly in the request
Descriptive style names the agent and intent
Consolidation merges findings and resolves conflicts

Common Pattern:

Sequential setup (if needed)
Launch specialized analyses in parallel
Consolidate results and present unified output

See

./references/parallel-execution.md

for parallel coordination patterns.

使用场景:

任务独立，结果可后续合并
可同时运行多个分析

请求模式:

显式: "同时启动所有Agent：X agent、Y agent、Z agent"
表述: "启动3个并行Agent独立处理不同方面"

最佳实践:

请求中明确包含"parallel"或"同时"字样
描述性命名Agent及意图
整合阶段合并发现并解决冲突

常见模式:

顺序设置（若需要）
并行启动专业分析
整合结果并呈现统一输出

查看

./references/parallel-execution.md

获取并行协调模式。

Reference Directory

参考目录

Validation & Quality

验证与质量

```
./references/validation-checklist.md
```
- Complete quality checklist
```
./references/rfc-2119.md
```
- Requirement levels (MUST/SHOULD/MAY)

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

Component Implementation

组件实现

```
./references/component-model.md
```
- Component types, selection criteria, token budgets
```
./references/components/skills.md
```
- Skill structure, frontmatter, progressive disclosure
```
./references/components/agents.md
```
- Agent design, CO-STAR framework, example blocks
```
./references/components/commands.md
```
- Command frontmatter, dynamic context
```
./references/components/hooks.md
```
- Hook events, types, bash templates
```
./references/components/mcp-servers.md
```
- MCP configuration, stdio/http/sse
```
./references/components/lsp-servers.md
```
- LSP setup, binary requirements

```
./references/component-model.md
```
- 组件类型、选择标准、令牌预算
```
./references/components/skills.md
```
- Skill结构、前置内容、渐进式披露
```
./references/components/agents.md
```
- Agent设计、CO-STAR框架、示例块
```
./references/components/commands.md
```
- Command前置内容、动态上下文
```
./references/components/hooks.md
```
- Hook事件、类型、bash模板
```
./references/components/mcp-servers.md
```
- MCP配置、stdio/http/sse
```
./references/components/lsp-servers.md
```
- LSP设置、二进制要求

Configuration & Integration

配置与集成

```
./references/directory-structure.md
```
- Plugin layout, naming conventions
```
./references/manifest-schema.md
```
- plugin.json schema, required fields
```
./references/mcp-patterns.md
```
- MCP transport types, security best practices

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

Development Patterns

开发模式

```
./references/tool-invocations.md
```
- Tool usage patterns and anti-patterns
```
./references/task-management.md
```
- TaskCreate patterns, dual-form naming
```
./references/cli-commands.md
```
- CLI commands for plugin management

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

Advanced Topics

高级主题

```
./references/agent-teams.md
```
- Parallelizable tasks, multi-perspective analysis
```
./references/parallel-execution.md
```
- Parallel agent coordination patterns
```
./references/debugging.md
```
- Common issues, error messages, troubleshooting

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