skill-tester

スキルテスター

スキルパッケージの構造準拠を検証し、Python スクリプトの構文と標準ライブラリのみを使用しているかをテストし、ドキュメント、コード品質、完全性、使いやすさの4つの観点から品質を評価します。評価はレターグレードと改善の推奨事項で示します。BASIC、STANDARD、POWERFUL のティア分類に対応しています。

主な機能

• 構造の検証 — 必須ファイル、ディレクトリ構成、YAML フロントマター、必須の SKILL.md セクションをティアの基準に照らして確認します。
• スクリプトのテスト — AST による構文チェック、標準ライブラリのみを使用しているかのインポート分析、argparse と __main__ ガードの検出、実行時の --help およびサンプルデータによる実行テストを行います。
• 品質評価 — 重みが均等な4つの評価項目から総合スコア、レターグレード（A+ から F）、優先順位付きの改善ロードマップを作成します。
• ティア分類 — SKILL.md の詳細度、スクリプト数／LOC、argparse、出力形式、エラー処理に関する BASIC／STANDARD／POWERFUL の要件を適用します。
• 2種類の出力 — 人が読みやすいレポートと、CI/CD のゲートに使える適切な終了コード付きの --json に対応します。

使用するタイミング

• 新しいスキルを作成し、公開前に検証するとき。
• 既存のスキルの構造、スクリプト、品質を監査するとき。
• CI/CD パイプラインに品質ゲートを組み込むとき。

最初に確認すること

検証の前に、次の入力を確認してください。不明な項目や曖昧な項目があれば、推測せずに質問してください。

• 対象のスキルパス — 検証、テスト、評価するスキルディレクトリ（3つのツールすべての対象）
• 対象のティア — BASIC／STANDARD／POWERFUL（--tier。必須セクション、スクリプト数、構造の基準を設定します）
• 合格基準 — 最低品質スコア、および失敗を CI のゲートとするかどうか（--minimum-score、終了コード）

停止ルール：出力に最も大きく影響する2～3項目だけ質問してください。ユーザーが「そのまま下書きして」と言った場合は作業を進め、成果物の冒頭に前提を列挙してください。

クイックスタート

# Validate skill structure and documentation
python skill_validator.py engineering/my-skill --tier POWERFUL --json

# Test all Python scripts in a skill
python script_tester.py engineering/my-skill --timeout 30

# Score quality with improvement roadmap
python quality_scorer.py engineering/my-skill --detailed --minimum-score 75

ツール

ツール	目的	コマンド
skill_validator.py	ティアのルールに照らして、構造、フロントマター、必須セクション、スクリプトを検証します	python scripts/skill_validator.py engineering/my-skill --tier POWERFUL --json
script_tester.py	スクリプトの静的テストと実行時テストを行います（構文、インポート、argparse、--help、サンプル）	python scripts/script_tester.py engineering/my-skill --timeout 60 --json
quality_scorer.py	4つの品質評価項目をレターグレードと改善ロードマップ付きで採点します	python scripts/quality_scorer.py engineering/my-skill --detailed --minimum-score 75 --json

すべてのパラメーター表、出力形式、終了コードについては、references/tool-reference.md を参照してください。

リファレンス

タスクに合ったリファレンスを読み込んでください。このファイルは簡潔に保ち、必要に応じて詳細を確認します。

• references/workflows-and-cicd.md — 3つの主要な検証ワークフロー、ティア要件と品質評価の表、CI/CD 統合、アンチパターン、トラブルシューティング、成功基準を説明します。検証を実施するときや、CI ゲートを組み込むときに読んでください。
• references/tool-reference.md — 3つの Python ツールの全パラメーター表、出力形式、終了コードを説明します。ツールをスクリプトから実行するときや、JSON 出力を解釈するときに読んでください。
• references/skill-structure-specification.md — スキルのディレクトリ構造、必須ファイル、フロントマターに関する正式な仕様です。「有効な構造」の定義を決めるときに読んでください。
• references/tier-requirements-matrix.md — BASIC／STANDARD／POWERFUL の完全な要件マトリクスと、ティアごとの詳細な基準を説明します。スキルのティアを分類または引き上げるときに読んでください。
• references/quality-scoring-rubric.md — コンポーネントごとの重みと評価区分を含む、詳細な採点基準です。品質スコアを解釈または調整するときに読んでください。

対象範囲と制限事項

対象：

• ティアごとの要件（BASIC、STANDARD、POWERFUL）に照らしたスキルディレクトリの構造検証
• 構文チェック、インポート検証、argparse の検出、main ガードの確認など、Python スクリプトの静的解析
• ドキュメント、コード品質、完全性、使いやすさを対象とした多面的な品質スコアリング
• JSON（CI/CD パイプライン向け）と人間が読みやすい形式（開発者向け）の二種類の出力形式

対象外：

• スクリプトのロジックの機能的な正しさやアルゴリズムの精度。テスターが検証するのは構造と規約であり、ビジネスロジックではありません
• スクリプトのパフォーマンスベンチマークやメモリプロファイリング。実行時の分析については engineering/performance-profiler を参照してください
• スクリプトコードのセキュリティ脆弱性スキャン。依存関係とコードのセキュリティ監査については engineering/skill-security-auditor を参照してください
• スキル間の依存関係の解決や統合テスト。スキルは個別に検証され、スキル間の互換性は確認されません

統合ポイント

スキル	統合	データフロー
engineering/skill-security-auditor	検証に合格した後でセキュリティ監査を実行します	skill_validator.py が構造要件への準拠を確認し、その後 skill-security-auditor が同じスキルのパスで脆弱性をスキャンします
engineering/ci-cd-pipeline-builder	品質ゲートのステージとして skill-tester を組み込みます	パイプラインビルダーは、skill_validator.py、script_tester.py、quality_scorer.py を順に呼び出すワークフロー YAML を生成します
engineering/changelog-generator	品質スコアの差分を変更履歴のエントリーに反映します	リリース間で quality_scorer.py の JSON 出力を比較し、品質の向上や低下を明らかにします
engineering/pr-review-expert	検証レポートをプルリクエストのレビューに添付します	skill_validator.py --json の出力を PR コメントとして投稿し、レビュー担当者の参考情報として提供します
engineering/performance-profiler	構造テストを実行時プロファイリングで補完します	script_tester.py が正常な実行を確認した後、performance-profiler が実行時間とリソース使用量を測定します
engineering/tech-debt-tracker	品質スコアの推移を経時的に追跡します	定期的に quality_scorer.py --json の出力を取り込み、スコアの低下を検出して技術的負債にフラグを付けます