skill-tester

スキルテスター

ティア: 強力 · カテゴリ: エンジニアリング品質保証 · 依存関係: なし（Python 標準ライブラリのみ）

このリポジトリのスキルを検証、テスト、採点するメタスキルです。4 つのツールを、完全なパスを指定してリポジトリのルートから実行します。

1. scripts/skill_validator.py — 構造とドキュメントの準拠状況
2. scripts/script_tester.py — Python スクリプトの構文、インポート、実行時の動作、出力のテスト
3. scripts/quality_scorer.py — レターグレード付きの多次元採点
4. scripts/security_scorer.py — セキュリティ態勢の採点（quality_scorer.py --include-security からも利用可能）

対象範囲に関する注記： このスキルのティア別最低行数は、従来のスキルを対象としています。新しいスキルを作成する場合は、engineering/write-a-skill（SKILL.md は約 100 行未満、Matt Pocock の指針）が適用される基準です。ここでのティア最低行数を満たすために、新しいスキルの行数を増やさないでください。

クイックスタート（リポジトリのルートから実行できる、正確なコマンド）

# 1. Validate structure (exit non-zero on failure — usable as a gate)
python3 engineering/skills/skill-tester/scripts/skill_validator.py engineering/skills/self-eval --json

# 2. Test the skill's Python scripts (30s default timeout per script)
python3 engineering/skills/skill-tester/scripts/script_tester.py engineering/skills/self-eval --json

# 3. Score quality (fail CI below threshold with --minimum-score)
python3 engineering/skills/skill-tester/scripts/quality_scorer.py engineering/skills/self-eval --json --detailed --minimum-score 75

JSON を確認してください。バリデーターは overall_score、compliance_level、各チェックの checks{} を出力します。スコアラーは overall_score、letter_grade、tier_recommendation、dimensions、improvement_roadmap を出力します。ロードマップを上から順に対応し、目標スコアに達するまで再実行してください。

リポジトリ全体を監査する場合は、リポジトリのルートにある scripts/audit_skills.py を使用してください（すべてのスキルに対して write-a-skill チェックリストランナーを実行します）。

各ツールのチェック内容

skill_validator.py

• SKILL.md のフロントマター解析、必須セクション、ティア別の最低行数（--tier BASIC|STANDARD|POWERFUL）
• 必須構成：SKILL.md、README.md、scripts/、references/、assets/、expected_outputs/
• Python スクリプト：argparse の使用、標準ライブラリのみのインポート

script_tester.py

• AST ベースの構文検証、インポート解析（外部依存関係を検出）
• タイムアウト保護付きの制御実行（--timeout、デフォルトは 30 秒）
• --help 機能の検証、サンプルデータを使った実行結果と expected_outputs/ の比較

quality_scorer.py

4 つの評価軸をそれぞれ 25% で採点します：ドキュメント（詳細度、例、リファレンス）、コード品質（複雑さ、エラー処理、出力の一貫性）、完全性（必須ディレクトリ、サンプルデータ、期待される出力）、使いやすさ（ヘルプテキスト、例の明確さ）。0〜100 点のスコア、A〜F のレターグレード、ティアの推奨を出力します。

ティア分類

ティア	SKILL.md	スクリプト	CLI の範囲
BASIC	≥ 100 行	1（100〜300 LOC）	基本的な argparse
STANDARD	≥ 200 行	1〜2（300〜500 LOC）	サブコマンド、JSON とテキストの出力
POWERFUL	≥ 300 行	2〜3（500〜800 LOC）	複数のモード、CI 統合

（従来のスキル向けの参考情報です。新しいスキルでは write-a-skill に従ってください。上記の対象範囲に関する注記を参照してください。）

CI 統合

# GitHub Actions: gate changed skills
- name: "validate-changed-skills"
  run: |
    for skill in $changed_skills; do
      python3 engineering/skills/skill-tester/scripts/skill_validator.py "$skill" --json
      python3 engineering/skills/skill-tester/scripts/script_tester.py "$skill"
      python3 engineering/skills/skill-tester/scripts/quality_scorer.py "$skill" --minimum-score 75
    done

pre-commit フック：ステージングされたスキルのディレクトリに対してバリデーターを実行し、終了コードが 0 以外の場合はコミットをブロックします。

検証ループ

リポジトリのルートから 1 回実行し、次の条件を満たした場合にスキルは「合格」となります。

1. skill_validator.py <skill> --json が終了コード 0 で終了する
2. script_tester.py <skill> がすべてのスクリプトの合格を報告する
3. quality_scorer.py <skill> --minimum-score <target> が終了コード 0 で終了する

いずれかの手順が失敗した場合は、improvement_roadmap の最上位項目に対応して、3 つすべてを再実行してください。部分的な合格を報告してはいけません。

トラブルシューティング

• タイムアウトエラー → --timeout を増やすか、テスト対象のスクリプトを最適化してください
• インポート失敗 → 外部依存関係が検出されています。リポジトリの方針では標準ライブラリのみを使用します
• ティアの誤分類 → ティア表を基に行数と LOC を確認してください。新しいスキルには write-a-skill の例外が適用されることを忘れないでください

参照資料：references/ には、ツールが実装する構造仕様、ティア要件マトリックス、採点基準が含まれています。