optimize-plugin

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Plugin Optimization

插件优化

Execute plugin validation and optimization workflow. Target: $ARGUMENTS

执行插件验证与优化工作流。目标： $ARGUMENTS

Background Knowledge

背景知识

Tool Invocation Patterns

工具调用模式

Tool	Style	Correct Format
Read, Write, Glob, Grep, Edit	Implicit	"Find files matching...", "Read each file..."
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"
AskUserQuestion	Explicit	"Use `AskUserQuestion` tool to [action]"
TaskCreate	Explicit	"Use TaskCreate tool to track"

Qualified Names: Plugin components MUST use

plugin-name:component-name

format.

Progressive Disclosure: Skills package domain expertise—turning general agents into knowledgeable specialists. Progressive disclosure protects context: metadata (~50 tokens) -> SKILL.md (~500 tokens) -> references (2000+ tokens, MUST only access when specifically needed).

工具	风格	正确格式
Read、Write、Glob、Grep、Edit	隐式	"查找匹配...的文件"、"读取每个文件..."
Bash	隐式	"运行 `git status` "
Task	隐式	"启动 `plugin-name:agent-name` agent"
Skill	显式	"使用Skill工具加载 `plugin-name:skill-name` skill"
AskUserQuestion	显式	"使用 `AskUserQuestion` 工具来[执行操作]"
TaskCreate	显式	"使用TaskCreate工具进行追踪"

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

plugin-name:component-name

格式。

渐进式披露：Skills封装了领域专业知识——将通用Agent转变为专业领域专家。渐进式披露可保护上下文：元数据（约50个token）-> SKILL.md（约500个token）-> 参考资料（2000+个token，仅在明确需要时才可访问）。

Component Template Validation

组件模板验证

Components MUST conform to templates in

${CLAUDE_PLUGIN_ROOT}/examples/

Agent Template Requirements:

Frontmatter:
```
name
```
,
```
description
```
,
```
color
```
,
```
allowed-tools
```
System Prompt: Second person ("You are..."), descriptive voice (NOT directive)
Structure: Knowledge Base + Core Responsibilities + Approach sections

Instruction-Type Skill Requirements (user-invocable: true):

Frontmatter:

name

description

user-invocable: true

allowed-tools

Voice: Imperative ("Load...", "Create...", "Execute...")
MANDATORY Phase Format:
```
## Phase N: [Phase Name]
```
with Goal and Actions subsections

Optional Pre-Phases:

## Background Knowledge

## Initialization

## Context

Knowledge-Type Skill Requirements (user-invocable: false):

Frontmatter:
```
name
```
,
```
description
```
,
```
user-invocable: false
```
Voice: Declarative ("is", "are", "provides")
Structure: Topic-based sections ("## Core Concepts", "## Best Practices")

Type Classification Quick Reference:

Component Type	user-invocable	Voice	Structure	Declared in
Agent	N/A	Descriptive (You are...)	Knowledge Base + Core Responsibilities + Approach	`agents`
Instruction Skill	`true`	Imperative (Load...)	Phase-based (Goal + Actions)	`commands`
Knowledge Skill	`false`	Declarative (is/are...)	Topic-based (concepts/patterns)	`skills`

Manifest Cross-Validation: Instruction-type MUST be in

plugin.json

commands

array; Knowledge-type MUST be in

plugin.json

skills

array.

组件必须符合

${CLAUDE_PLUGIN_ROOT}/examples/

中的模板要求。

Agent模板要求：

前置元数据：
```
name
```
、
```
description
```
、
```
color
```
、
```
allowed-tools
```
系统提示语：第二人称（"你是..."），描述性语气（而非指令性）
结构：知识库 + 核心职责 + 工作方法 章节

指令型Skill要求（user-invocable: true）：

前置元数据：

name

、

description

、

user-invocable: true

、

allowed-tools

语气：祈使句（"加载..."、"创建..."、"执行..."）
强制阶段格式：
```
## 第N阶段：[阶段名称]
```
，包含目标和操作子章节
可选前置阶段：
```
## 背景知识
```
、
```
## 初始化
```
、
```
## 上下文
```

知识型Skill要求（user-invocable: false）：

前置元数据：
```
name
```
、
```
description
```
、
```
user-invocable: false
```
语气：陈述句（"是"、"为"、"提供"）
结构：基于主题的章节（"## 核心概念"、"## 最佳实践"）

类型分类速查表：

组件类型	user-invocable	语气	结构	声明位置
Agent	N/A	描述性（你是...）	知识库 + 核心职责 + 工作方法	`agents`
指令型Skill	`true`	祈使句（加载...）	基于阶段（目标 + 操作）	`commands`
知识型Skill	`false`	陈述句（是/为...）	基于主题（概念/模式）	`skills`

清单交叉验证：指令型Skill必须在

plugin.json

的

commands

数组中声明；知识型Skill必须在

plugin.json

的

skills

数组中声明。

Phase 1: Discovery & Validation

阶段1：发现与验证

Goal: Validate structure and detect issues. Orchestrator MUST NOT apply fixes.

Actions:

Resolve path with
```
realpath
```
and verify existence
Validate
```
.claude-plugin/plugin.json
```
exists
Find component directories:
```
commands/
```
,
```
agents/
```
,
```
skills/
```
,
```
hooks/
```
Validate components against
```
${CLAUDE_PLUGIN_ROOT}/examples/
```
templates
Assess architecture: if
```
commands/
```
exists with
```
.md
```
files, use
```
AskUserQuestion
```
tool to ask about migrating to skills structure

Run validation:

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/validate-plugin.py "$TARGET"

Options:

--check=structure,manifest,frontmatter,tools,tokens

JSON output:
```
--json
```
Verbose:
```
-v, --verbose
```

Compile issues by severity (Critical, Warning, Info)

目标：验证结构并检测问题。编排器不得直接应用修复。

操作：

使用
```
realpath
```
解析路径并验证其存在性
验证
```
.claude-plugin/plugin.json
```
存在
查找组件目录：
```
commands/
```
、
```
agents/
```
、
```
skills/
```
、
```
hooks/
```
验证组件是否符合
```
${CLAUDE_PLUGIN_ROOT}/examples/
```
中的模板要求
评估架构：如果存在包含
```
.md
```
文件的
```
commands/
```
目录，使用
```
AskUserQuestion
```
工具询问是否要迁移至skills结构

运行验证：

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/validate-plugin.py "$TARGET"

选项：

--check=structure,manifest,frontmatter,tools,tokens

JSON输出：
```
--json
```
详细模式：
```
-v, --verbose
```

按严重程度整理问题（严重、警告、信息）

Phase 2: Agent-Based Optimization

阶段2：基于Agent的优化

Goal: Launch agent to apply ALL fixes. Orchestrator does NOT make fixes directly.

Condition: Always execute.

Actions:

Launch
```
plugin-optimizer:plugin-optimizer
```
agent with the following prompt content:
- Target plugin path (absolute path from Phase 1)
- Validation console output (issues list from Phase 1)
- Template validation results
- User decisions (migration choice if applicable)
- INSTRUCTION: Analyze the validation output to identify issues
Agent autonomously applies fixes (MUST use
```
AskUserQuestion
```
tool before applying template fixes, presenting violations with specific examples and before/after comparison)
Agent increments version in
```
.claude-plugin/plugin.json
```
after fixes:
- Patch (x.y.Z+1): Bug fixes
- Minor (x.Y+1.0): New components
- Major (X+1.0.0): Breaking changes
Wait for agent to complete

Path Reference Rules:

Same directory: Use relative paths (
```
./reference.md
```
)
Outside directory: Use
```
${CLAUDE_PLUGIN_ROOT}
```
paths
Component templates: See
```
${CLAUDE_PLUGIN_ROOT}/examples/
```

Redundancy & Efficiency:

Redundancy: Allow strategic repetition of critical content (MUST/SHOULD requirements). Favor concise restatement.
Efficiency: Agent detects if tasks need Agent Teams (Parallelizable > 5 files, Multi-domain).

目标：启动Agent以应用所有修复。编排器不得直接进行修复。

条件：必须执行此阶段。

操作：

启动
```
plugin-optimizer:plugin-optimizer
```
agent，传入以下提示内容：
- 目标插件路径（阶段1得到的绝对路径）
- 验证控制台输出（阶段1得到的问题列表）
- 模板验证结果
- 用户决策（如适用的迁移选择）
- 指令：分析验证输出以识别问题
Agent自主应用修复（在应用模板修复前必须使用
```
AskUserQuestion
```
工具，向用户展示违规示例及前后对比）
修复完成后，Agent在
```
.claude-plugin/plugin.json
```
中升级版本：
- 补丁版本（x.y.Z+1）：修复Bug
- 小版本（x.Y+1.0）：新增组件
- 大版本（X+1.0.0）：破坏性变更
等待Agent完成任务

路径引用规则：

同一目录：使用相对路径（
```
./reference.md
```
）
目录外：使用
```
${CLAUDE_PLUGIN_ROOT}
```
路径
组件模板：参见
```
${CLAUDE_PLUGIN_ROOT}/examples/
```

冗余与效率：

冗余：允许关键内容的策略性重复（必须/应遵循的要求）。优先采用简洁的重述方式。
效率：Agent需检测任务是否需要Agent Teams（可并行处理>5个文件、多领域场景）。

Phase 3: Verification & Deliverables

阶段3：验证与交付物

Goal: Verify fixes, generate report, and update documentation.

Actions:

Execute validation script:

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/validate-plugin.py "$TARGET"

Analyze results: compare with Phase 1 findings, confirm critical issues resolved
If critical issues remain, resume agent execution
Generate final validation report using template below
Update
```
README.md
```
to reflect current state (metadata, directory structure, usage instructions; do not append version history log)

目标：验证修复效果、生成报告并更新文档。

操作：

执行验证脚本：

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/validate-plugin.py "$TARGET"

分析结果：与阶段1的发现对比，确认严重问题已解决
若仍有严重问题，恢复Agent执行
使用以下模板生成最终验证报告
更新
```
README.md
```
以反映当前状态（元数据、目录结构、使用说明；请勿追加版本历史日志）

Validation Report Template

验证报告模板

markdown

undefined

markdown

undefined

Plugin Validation Report

插件验证报告

Plugin: [name]

插件：[名称]

Location: [absolute-path] Version: [old] -> [new]

位置：[绝对路径] 版本：[旧版本] -> [新版本]

Summary

摘要

[2-3 sentences with key statistics]

[2-3句话，包含关键统计数据]

Phase 1: Issues Detected

阶段1：检测到的问题

Critical ([count])

严重问题（[数量]）

```
file/path
```
- [Issue description]

```
文件/路径
```
- [问题描述]

Warnings ([count])

警告（[数量]）

```
file/path
```
- [Issue description]

```
文件/路径
```
- [问题描述]

Phase 2: Fixes Applied

阶段2：已应用的修复

Structure Fixes

结构修复

[Fix description]

[修复描述]

Template Conformance

模板合规性

Agents: [Count] validated, [count] fixed
Instruction-type Skills: [Count] validated, [count] fixed
Knowledge-type Skills: [Count] validated, [count] fixed

Agents：[数量]已验证，[数量]已修复
指令型Skills：[数量]已验证，[数量]已修复
知识型Skills：[数量]已验证，[数量]已修复

Redundancy Fixes

冗余修复

[Consolidations applied]

[已应用的合并操作]

Phase 3: Verification Results

阶段3：验证结果

Structure validation: [PASS/FAIL]
Manifest validation: [PASS/FAIL]
Component validation: [PASS/FAIL]
Tool patterns validation: [PASS/FAIL]
Token budgets validation: [PASS/FAIL]

结构验证：[通过/失败]
清单验证：[通过/失败]
组件验证：[通过/失败]
工具模式验证：[通过/失败]
Token预算验证：[通过/失败]

Token Budget Analysis

Token预算分析

Skills analyzed: [count]
Tier 1 (Metadata ~50): [OK count], [WARNING count]
Tier 2 (SKILL.md ~500): [OK count], [WARNING count], [CRITICAL count]
Tier 3 (References 2000+ typical): [total tokens]

已分析Skills：[数量]
层级1（元数据~50）：[正常数量]，[警告数量]
层级2（SKILL.md~500）：[正常数量]，[警告数量]，[严重数量]
层级3（参考资料通常2000+）：[总token数]

Component Inventory

组件清单

Commands: [count] found, [count] valid
Agents: [count] found, [count] valid
Skills: [count] found, [count] valid

Commands：[数量]已找到，[数量]有效
Agents：[数量]已找到，[数量]有效
Skills：[数量]已找到，[数量]有效

Remaining Issues

剩余问题

[Issues that couldn't be auto-fixed with explanations]

[无法自动修复的问题及说明]

Overall Assessment

总体评估

[PASS/FAIL] - [Detailed reasoning]

undefined

[通过/失败] - [详细理由]

undefined