plugin-validator

プラグインバリデーター

Claude Code マーケットプレイスプラグインの包括的な検証です。

自己進化するスキル：このスキルは使用を通じて改善されます。手順が誤っている場合、パラメーターにずれが生じた場合、または回避策が必要だった場合は、先延ばしにせず、すぐにこのファイルを修正してください。実際に再現可能な問題がある場合にのみ更新してください。

このスキルを使う場面

以下の場合に、このスキルを使用してください。

• リリース前にプラグインの構造を検証する
• フックでのサイレントな失敗を監査する
• plugin.json の構文と必須フィールドを確認する
• スキルファイルのフォーマットとフロントマターを検証する

クイックスタート

# 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	if ! を使わない mkdir|cp|mv|rm|jq
サイレントな Python	hooks/*.py	stderr 出力を伴わない except.*: pass

フックのエントリーポイントとユーティリティスクリプト

場所	種類	要件
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 との連携

このスキルは、plugin-add ワークフローのフェーズ 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. 現在地を確認します。 — 編集する前に、このスキルの正式なパスを特定します（スキル名で Glob を実行します）。修正対象はこのファイルと、その兄弟にあたる references/ のみです。他のドキュメントは修正しません。
1. 何が失敗しましたか？ — 原因となった指示を修正します。再発する可能性がある場合は、アンチパターンとして追加します。
2. 予想以上にうまくいったことは何ですか？ — 推奨プラクティスとして取り入れます。その理由も記録します。
3. 何が現状とずれていましたか？ — 現状と合わなくなったスクリプト、リファレンス、外部依存関係があれば、今すぐ修正します。
4. 記録します。 — 変更のたびに、きっかけ、修正内容、根拠を含む進化ログのエントリーを残します。

先送りしないでください。次回の実行では、ここに残した内容が引き継がれます。

---

---