Back to Details

plugin-validator

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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
  • Agent/Skill之间无循环依赖
  • Skill引用解析正确
  • 工具权限有效
  • 组件间的交叉引用存在
  • 外部依赖已文档化

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
  • 组件间无冲突设置
  • 文件权限为可读
  • 无重复的Agent/命令名称
  • 各文件版本一致
  • 仓库元数据准确

Process

验证流程

  1. Identify plugin location
    bash
    # Find plugin.json
find . -name "plugin.json" -o -name ".claude-plugin/plugin.json"
  2. Run manifest validation
    • Parse JSON syntax
    • Check required fields
    • Validate semver format
    • Verify array structures
  3. Validate file structure
    • Read manifest file references
    • Check each referenced file exists
    • Verify paths are relative
    • Check directory conventions
  4. Check frontmatter
    • For each agent/command file
    • Parse YAML frontmatter
    • Validate required fields
    • Check field value constraints
  5. Analyze dependencies
    • Build dependency graph
    • Detect circular references
    • Validate skill references
    • Check tool usage patterns
  6. Report findings
    • Categorize by severity (critical, warning, info)
    • Provide specific file/line references
    • Suggest fixes with examples
    • Prioritize by impact
  1. 确定插件位置
    bash
    # Find plugin.json
find . -name "plugin.json" -o -name ".claude-plugin/plugin.json"
  2. 执行清单验证
    • 解析JSON语法
    • 检查必填字段
    • 验证语义化版本格式
    • 校验数组结构
  3. 验证文件结构
    • 读取清单中的文件引用
    • 检查每个引用文件是否存在
    • 验证路径为相对路径
    • 检查目录规范
  4. 检查前置元数据
    • 针对每个Agent/命令文件
    • 解析YAML前置元数据
    • 验证必填字段
    • 检查字段值约束
  5. 分析依赖项
    • 构建依赖关系图
    • 检测循环引用
    • 验证Skill引用
    • 检查工具使用模式
  6. 生成报告
    • 按严重程度分类（严重、警告、信息）
    • 提供具体的文件/行号引用
    • 附带示例修复建议
    • 按影响优先级排序

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

Validate JSON syntax

python3 -m json.tool plugin.json
python3 -m json.tool plugin.json

Check location

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

Check agent path

grep '"agents"' plugin.json
grep '"agents"' plugin.json

Validate YAML (first 20 lines typically contain frontmatter)

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

Validate plugin at current directory

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

Check all referenced files

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

Related

相关工具

  • Agent: 
    claire-plugin-manager
    for plugin management and health checks
  • Skill: 
    doc-validator
    for documentation validation
  • Commands: Claude Code plugin system documentation
  • Agent: 
    claire-plugin-manager
    用于插件管理与健康检查
  • Skill: 
    doc-validator
    用于文档验证
  • 命令：Claude Code插件系统文档