plugin-validator

插件验证器

全面验证 Claude Code 市场插件。

自我进化技能：此技能会在使用过程中不断改进。如果指令有误、参数发生偏移，或需要采用变通方法，请立即修复此文件，不要拖延。仅针对真实且可复现的问题进行更新。

何时使用此技能

在以下情况下使用此技能：

• 发布前验证插件结构
• 审查钩子是否存在静默失败
• 检查 plugin.json 语法和必需字段
• 验证技能文件格式和 frontmatter

快速开始

# Validate a specific plugin
uv run plugins/plugin-dev/skills/plugin-validator/scripts/audit_silent_failures.py plugins/my-plugin/

# Validate with fix suggestions
uv run plugins/plugin-dev/skills/plugin-validator/scripts/audit_silent_failures.py plugins/my-plugin/ --fix

验证阶段

阶段 1：结构验证

检查插件目录结构：

/usr/bin/env bash << 'VALIDATE_EOF'
PLUGIN_PATH="${1:-.}"

# Check plugin.json exists
if [[ ! -f "$PLUGIN_PATH/plugin.json" ]]; then
    echo "ERROR: Missing plugin.json" >&2
    exit 1
fi

# Validate JSON syntax
if ! jq empty "$PLUGIN_PATH/plugin.json" 2>/dev/null; then
    echo "ERROR: Invalid JSON in plugin.json" >&2
    exit 1
fi

# Check required fields
REQUIRED_FIELDS=("name" "version" "description")
for field in "${REQUIRED_FIELDS[@]}"; do
    if ! jq -e ".$field" "$PLUGIN_PATH/plugin.json" >/dev/null 2>&1; then
        echo "ERROR: Missing required field: $field" >&2
        exit 1
    fi
done

echo "Structure validation passed"
VALIDATE_EOF

阶段 2：静默失败审计

关键规则：所有钩子入口点在失败时都必须向 stderr 输出信息。

运行审计脚本：

uv run plugins/plugin-dev/skills/plugin-validator/scripts/audit_silent_failures.py plugins/my-plugin/

检查内容

检查项	目标文件	模式
Shellcheck	hooks/*.sh	SC2155、SC2086 等
静默 bash	hooks/*.sh	mkdir|cp|mv|rm|jq 未使用 if !
静默 Python	hooks/*.py	except.*: pass 未输出到 stderr

钩子入口点与工具脚本

位置	类型	要求
plugins/*/hooks/*.sh	入口点	必须向 stderr 输出信息
plugins/*/hooks/*.py	入口点	必须向 stderr 输出信息
plugins/*/scripts/*.sh	工具脚本	可以采用回退行为
plugins/*/scripts/*.py	工具脚本	可以采用回退行为

阶段 3：修复模式

Bash：静默 mkdir

# BAD - silent failure
mkdir -p "$DIR"

# GOOD - emits to stderr
if ! mkdir -p "$DIR" 2>&1; then
    echo "[plugin] Failed to create directory: $DIR" >&2
fi

Python：静默 except pass

# BAD - silent failure
except (json.JSONDecodeError, OSError):
    pass

# GOOD - emits to stderr
except (json.JSONDecodeError, OSError) as e:
    print(f"[plugin] Warning: {e}", file=sys.stderr)

与 /plugin-dev:create 集成

此技能会在插件添加工作流的阶段 3 中调用：

### 3.4 Plugin Validation

**MANDATORY**: Run plugin-validator before registration.

Task with subagent_type="plugin-dev:plugin-validator"
prompt: "Validate the plugin at plugins/$PLUGIN_NAME/"

退出代码

代码	含义
0	所有验证均已通过
1	发现违规项（参见输出）
2	错误（路径无效、缺少文件）

参考资料

• 静默失败模式

故障排除

问题	原因	解决方案
未找到 plugin.json	缺少清单文件	创建包含必需字段的 plugin.json
JSON 语法无效	plugin.json 格式错误	运行 jq empty plugin.json 查找语法错误
缺少必需字段	清单不完整	在 plugin.json 中添加 name、version、description
Shellcheck 错误	Bash 脚本问题	运行 shellcheck hooks/*.sh 查看详情
Bash 中发生静默失败	缺少错误处理	在 mkdir/cp/mv/rm 命令外添加 if ! 检查
Python 中出现静默 except:pass	缺少 stderr 输出	在 pass 前添加 print(..., file=sys.stderr)
退出代码 2	路径无效或缺少文件	确认插件路径存在且结构正确
使用 --fix 后仍有违规项	未应用修复建议	根据输出手动应用建议的修复

执行后反思

此技能完成后，请在结束任务前进行反思：

0. 确认位置。 — 编辑前，查找此 SKILL.md 的规范路径（使用 Glob 搜索此技能的名称）。所有修正仅针对此文件及其同级的 references/ — 绝不修改其他文档。
1. 哪里出了问题？ — 修复导致问题的指令。如果问题可能再次发生，请将其列为反模式。
2. 哪些做法超出预期？ — 将其提升为推荐做法，并说明原因。
3. 哪里出现偏差？ — 任何与实际情况不再相符的脚本、引用或外部依赖都要立即修正。
4. 记录下来。 — 每项更改都要在演进日志中记录触发原因、修复措施和证据。

切勿推迟。下次调用将继承你留下的一切。

---

---