Plugin Validator

插件验证工具

Validation Checks

验证检查项

1. Manifest Validation

1. 清单验证

plugin.json exists at correct location
Valid JSON syntax
Required fields present (name, description, version)
Semantic versioning format (X.Y.Z)
Array fields properly formatted (agents, commands, skills)
No duplicate entries

plugin.json存在于正确路径
JSON语法有效
包含必填字段（name、description、version）
符合语义化版本格式（X.Y.Z）
数组字段格式正确（agents、commands、skills）
无重复条目

2. Structure Validation

2. 结构验证

Referenced agents exist at specified paths
Referenced commands exist at specified paths
Referenced skills exist at specified paths
File paths are relative (not absolute)
No broken file references
Directory structure follows conventions

引用的Agent存在于指定路径
引用的命令存在于指定路径
引用的Skill存在于指定路径
文件路径为相对路径（非绝对路径）
无失效文件引用
目录结构遵循规范

3. Frontmatter Validation

3. 前置元数据验证

YAML syntax is valid
Required fields present (name, description)
Field values match allowed types
Tools list is valid (if specified)
Model value is valid (sonnet|opus|haiku|inherit)
No conflicting or deprecated fields

YAML语法有效
包含必填字段（name、description）
字段值符合允许的类型
工具列表有效（若已指定）
Model值有效（sonnet|opus|haiku|inherit）
无冲突或已弃用的字段

4. Dependency Validation

4. 依赖项验证

No circular dependencies between agents/skills
Skill references resolve correctly
Tool permissions are valid
Cross-references between components exist
External dependencies documented

5. Configuration Validation

5. 配置验证

No conflicting settings between components
File permissions are readable
No duplicate agent/command names
Version consistency across files
Repository metadata accurate

Process

验证流程

Identify plugin location

bash

# Find plugin.json
find . -name "plugin.json" -o -name ".claude-plugin/plugin.json"

Run manifest validation
- Parse JSON syntax
- Check required fields
- Validate semver format
- Verify array structures
Validate file structure
- Read manifest file references
- Check each referenced file exists
- Verify paths are relative
- Check directory conventions
Check frontmatter
- For each agent/command file
- Parse YAML frontmatter
- Validate required fields
- Check field value constraints
Analyze dependencies
- Build dependency graph
- Detect circular references
- Validate skill references
- Check tool usage patterns
Report findings
- Categorize by severity (critical, warning, info)
- Provide specific file/line references
- Suggest fixes with examples
- Prioritize by impact

确定插件位置

bash

# Find plugin.json
find . -name "plugin.json" -o -name ".claude-plugin/plugin.json"

执行清单验证
- 解析JSON语法
- 检查必填字段
- 验证语义化版本格式
- 校验数组结构
验证文件结构
- 读取清单中的文件引用
- 检查每个引用文件是否存在
- 验证路径为相对路径
- 检查目录规范
检查前置元数据
- 针对每个Agent/命令文件
- 解析YAML前置元数据
- 验证必填字段
- 检查字段值约束
分析依赖项
- 构建依赖关系图
- 检测循环引用
- 验证Skill引用
- 检查工具使用模式
生成报告
- 按严重程度分类（严重、警告、信息）
- 提供具体的文件/行号引用
- 附带示例修复建议
- 按影响优先级排序

Validation Severity Levels

验证严重等级

CRITICAL (Plugin won't load)

严重（插件无法加载）

Invalid JSON in plugin.json
Missing required fields (name, description, version)
Referenced files don't exist
Invalid YAML in frontmatter
Circular dependencies

plugin.json中存在无效JSON
缺失必填字段（name、description、version）
引用的文件不存在
前置元数据中存在无效YAML
循环依赖

WARNING (Plugin may malfunction)

警告（插件可能异常）

Invalid semver format
Deprecated field usage
Missing optional but recommended fields
Inconsistent naming conventions
Potential conflicts

无效的语义化版本格式
使用已弃用字段
缺失可选但推荐的字段
命名规范不一致
潜在冲突

INFO (Best practice suggestions)

信息（最佳实践建议）

Missing documentation
Version mismatch across files
Code style inconsistencies
Missing cross-references
Optimization opportunities

缺失文档
各文件版本不匹配
代码风格不一致
缺失交叉引用
优化机会

Examples

使用示例

✅ Good trigger: "Validate the waypoint plugin" ✅ Good trigger: "Check why my plugin isn't loading" ✅ Good trigger: "Plugin health check for claire" ✅ Good trigger: "My agent file has errors"

❌ Bad trigger: "Create a new plugin" (creation, not validation) ❌ Bad trigger: "Update plugin version" (modification, not validation) ❌ Bad trigger: "Install plugin" (installation, not validation)

✅ 有效触发词："验证waypoint插件" ✅ 有效触发词："检查我的插件为什么无法加载" ✅ 有效触发词："为claire插件做健康检查" ✅ 有效触发词："我的Agent文件报错了"

❌ 无效触发词："创建新插件"（属于创建操作，非验证） ❌ 无效触发词："更新插件版本"（属于修改操作，非验证） ❌ 无效触发词："安装插件"（属于安装操作，非验证）

Common Issues and Fixes

常见问题与修复方案

Issue: Plugin not loading

问题：插件无法加载

Check:

plugin.json exists in correct location
JSON syntax is valid
Required fields present
Version follows semver

Fix:

bash

undefined

检查项：

plugin.json存在于正确路径
JSON语法有效
包含必填字段
版本遵循语义化格式

修复方案：

bash

undefined

Validate JSON syntax

python3 -m json.tool plugin.json

Check location

test -f .claude-plugin/plugin.json || test -f plugin.json

undefined

test -f .claude-plugin/plugin.json || test -f plugin.json

undefined

Issue: Agent not working

问题：Agent无法工作

Check:

Agent file exists at path in plugin.json
YAML frontmatter is valid
Required fields (name, description) present
Tools list is valid

Fix:

bash

undefined

检查项：

Agent文件存在于plugin.json指定的路径
YAML前置元数据有效
包含必填字段（name、description）
工具列表有效

修复方案：

bash

undefined

Check agent path

grep '"agents"' plugin.json

Validate YAML (first 20 lines typically contain frontmatter)

head -20 agents/my-agent.md

undefined

head -20 agents/my-agent.md

undefined

Issue: Circular dependencies

问题：循环依赖

Check:

Agent A references skill B
Skill B references agent A
Build dependency graph

Fix:

Restructure to remove circular reference
Extract shared logic to separate component
Document dependency rationale

检查项：

Agent A引用Skill B
Skill B引用Agent A
构建依赖关系图

修复方案：

重构以移除循环引用
将共享逻辑提取到独立组件
记录依赖关系的合理性

Supporting Files

参考文件

For detailed validation rules, see:

manifest.md - plugin.json validation rules
frontmatter.md - YAML frontmatter validation
structure.md - File structure conventions
dependencies.md - Dependency analysis

如需详细验证规则，请查看：

manifest.md - plugin.json验证规则
frontmatter.md - YAML前置元数据验证规则
structure.md - 文件结构规范
dependencies.md - 依赖项分析规则

Quick Reference

快速参考

Valid plugin.json structure

有效的plugin.json结构

json

{
  "name": "plugin-name",
  "description": "Plugin description",
  "version": "1.0.0",
  "agents": ["./agents/agent-name.md"],
  "commands": ["./commands/command-name.md"],
  "skills": ["./skills/skill-name"]
}

json

{
  "name": "plugin-name",
  "description": "Plugin description",
  "version": "1.0.0",
  "agents": ["./agents/agent-name.md"],
  "commands": ["./commands/command-name.md"],
  "skills": ["./skills/skill-name"]
}

Valid agent/command frontmatter

有效的Agent/命令前置元数据

yaml

---
name: component-name
description: Component description
tools: Read, Write, Bash
model: sonnet
---

yaml

---
name: component-name
description: Component description
tools: Read, Write, Bash
model: sonnet
---

Validation command pattern

验证命令示例

bash

undefined

bash

undefined

Validate plugin at current directory

ls -la .claude-plugin/plugin.json plugin.json

Check all referenced files

grep -o '"[^"]*.md"' plugin.json | while read file; do test -f "${file//"/}" && echo "✓ $file" || echo "✗ $file" done

undefined

grep -o '"[^"]*.md"' plugin.json | while read file; do test -f "${file//"/}" && echo "✓ $file" || echo "✗ $file" done

undefined

plugin-validator

Original

Translation

Plugin Validator

插件验证工具

Validation Checks

验证检查项

1. Manifest Validation

1. 清单验证

2. Structure Validation

2. 结构验证

3. Frontmatter Validation

3. 前置元数据验证

4. Dependency Validation

4. 依赖项验证

5. Configuration Validation

5. 配置验证

Process

验证流程

Validation Severity Levels

验证严重等级

CRITICAL (Plugin won't load)

严重（插件无法加载）

WARNING (Plugin may malfunction)

警告（插件可能异常）

INFO (Best practice suggestions)

信息（最佳实践建议）

Examples

使用示例

Common Issues and Fixes

常见问题与修复方案

Issue: Plugin not loading

问题：插件无法加载

Validate JSON syntax

Validate JSON syntax

Check location

Check location

Issue: Agent not working

问题：Agent无法工作

Check agent path

Check agent path

Validate YAML (first 20 lines typically contain frontmatter)

Validate YAML (first 20 lines typically contain frontmatter)

Issue: Circular dependencies

问题：循环依赖

Supporting Files

参考文件

Quick Reference

快速参考

Valid plugin.json structure

有效的plugin.json结构

Valid agent/command frontmatter

有效的Agent/命令前置元数据

Validation command pattern

验证命令示例

Validate plugin at current directory

Validate plugin at current directory

Check all referenced files

Check all referenced files

Related

相关工具