Claude CodeやGitHub Copilot、Cursorなどのコーディングエージェントに「再利用可能なスキル」を読み込ませる仕組みが広がっています。SKILL.mdというMarkdownファイルにスキルの説明や手順を書き、エージェントが起動時に読み込む形式です。
この仕組みをCI/CDパイプラインに組み込んでいる、あるいはこれから組み込もうとしているインフラ・SRE寄りのエンジニアに向けて、静的解析ツールskillcheckの最近の修正内容から見えてくる落とし穴を整理します。SKILL.mdを複数チームで管理し始めた組織ほど、気づかないうちに影響を受けている可能性があります。
何が起きるか：スコアが不正確、CIが不透明にクラッシュする
skillcheckはSKILL.mdファイルを検証する静的解析ツールです。ネットワーク通信もLLM（大規模言語モデル）へのAPI呼び出しも行わず、ファイルを書き換えることもありません。CLIとして単体実行できるほか、GitHub Actionやpre-commitフック（コミット前に自動チェックを走らせる仕組み）としても組み込めます。
直近の更新で修正された問題は大きく2つです。1つ目は、スキルの説明文がエージェントに発見されやすいかどうかを採点する「discoverabilityスコア」が、実際より低く出ていたバグです。参照コーパス（検証用のサンプル集）でのスコア中央値は75から90へと跳ね上がりました。つまりこれまで低評価だったスキルの多くは、本来もっと良い説明文だった可能性があります。
2つ目は、壊れた入力ファイルに対する挙動です。以前はskillcheck.toml（設定ファイル）が不正なUTF-8だったり、履歴ログが壊れていたりすると、Pythonのトレースバック（エラー発生箇所を示す長いスタック情報）がそのまま出力されていました。CI上でこれが起きると、原因不明のジョブ失敗としてログに残り、調査に時間を取られる要因になります。
なぜ起きるか：スコアラーのロジックと設定探索の設計に原因がある
スコアが不正確だった原因は、説明文のパターンマッチングロジックにありました。良い説明文を書いていても、特定のパターンに一致しないと過小評価される欠陥があったということです。修正後は、内容の薄い説明文が28〜65点、しっかり書かれた説明文が85〜100点という分離が、実データで確認されています。
クラッシュの原因はもう少し構造的です。skillcheckはskillcheck.tomlの設定を探すとき、ディレクトリツリーを上へ上へとたどっていく仕組みになっています。この探索の途中にあるファイル1つでも壊れていると、そこから下のディレクトリすべてのスキャンが巻き込まれて失敗していました。
これはIaC（Infrastructure as Code、インフラをコードで管理する手法）を扱う人には馴染み深い構造です。TerraformでもStateファイルの探索パスやbackend設定の読み込み順序を誤ると、意図しない範囲まで影響が波及します。設定ファイルの探索範囲を意識せずに運用すると、1箇所の破損が広域障害につながるという点は共通しています。
信頼できない入力（ingest、履歴、設定の3種類）はすべて同じガード処理を通るように統一され、失敗の仕方も揃えられました。修正前は経路によってエラーの出方がバラバラだったということです。
もう1つの落とし穴はトークン数の見積もり誤差です。skillcheckはSKILL.mdのトークン予算（エージェントに読み込ませる際の上限）をチェックする機能を持ちますが、tiktoken（OpenAI製のトークナイザーライブラリ）を追加インストールしない場合、オフラインのヒューリスティック（簡易推定ロジック）で見積もります。
このヒューリスティックの精度は、これまで一度も実測されずに「だいたい合っている」という前提で運用されていました。実際にtiktokenのcl100k_baseエンコーディングと突き合わせたところ、61件のSKILL.mdファイル全件で、ファイル全体のトークン数が中央値23.0%、p95で30.7%の過大推定になっていたことが確認されています。frontmatter（メタデータ部分）は中央値25.9%、本文は22.7%、いずれも61件全てで過大推定という一方向のバイアスでした。
自分のプロジェクトが該当するか確認する方法
まず、SLO（Service Level Objective、サービスが満たすべき品質目標）の文脈でCIパイプラインを見直す観点から、以下を確認してください。
pip show skillcheckバージョンが古い場合は、スコアリングのバグやクラッシュの挙動が修正前のままの可能性があります。次に、tiktokenが入っているかを確認します。
pip show tiktoken入っていなければ、トークン予算チェックは過大推定の状態で動いています。予算上限ぎりぎりのSKILL.mdがある場合、実際は予算内でも「超過」と誤判定され、CIが落ちている可能性があります。
該当しそうな場合は、実際にスキャンして挙動を見てください。
skillcheck skills/ --explain-score--explain-scoreオプションを付けると、単なる点数だけでなく、どの評価パターンに一致・不一致だったかが表示されます。これまで低スコアだったスキルがある場合、この出力を見て、修正前のバグによる誤判定だったのかを切り分けられます。
対策の手順
以下の順番で対応することをおすすめします。
pip install -U "skillcheck[tiktoken]"このコマンドでskillcheck本体とtiktoken拡張を同時に更新・インストールします。Python 3.10以上が要件なので、CIのランタイム設定も確認してください。GitHub Actionsのワークフローでpython-versionが3.9以下に固定されている場合は更新が必要です。
次に、CI上でskillcheckを実行しているジョブのログを見直します。過去にトレースバックで落ちていた箇所がないか確認し、原因が壊れたskillcheck.tomlや履歴ファイルだった場合は、そのファイルを修正するか除外設定を追加します。
設定ファイルの探索パスについては、モノレポ（複数プロジェクトを1つのリポジトリで管理する構成）でskillcheckを使っている場合に特に注意が必要です。ディレクトリ階層のどこかにskillcheck.tomlを1つだけ置く運用にしているなら、そのファイルの整合性がリポジトリ全体のスキャン結果を左右します。定期的に単体でパースできるかを確認しておくと安全です。
skillcheck skills/ --explain-scoreこのコマンドを更新前と更新後の両方で実行し、スコアの変化を記録しておくと、CIのしきい値設定（何点以上を合格とするか）を見直す判断材料になります。中央値が75から90に変わったという事実は、既存のしきい値をそのまま使うと基準が甘くなりすぎる可能性を示しています。オブザーバビリティ（システムの内部状態を外部から観測できるようにする設計）の観点からも、スコアの推移をログやダッシュボードに残しておく価値はあります。
まとめ
SKILL.mdを使ったエージェント連携をCIに組み込んでいるなら、まずskillcheckとtiktokenのバージョンを確認してください。
pip show skillcheckとpip show tiktokenでバージョンを確認する--explain-scoreで既存スキルのスコアが妥当か再確認する- CIログで過去のクラッシュ原因が設定ファイルの破損でないか洗い出す
- モノレポ運用ではskillcheck.tomlの探索パスと整合性を定期チェックする
トークン予算のような一見小さな見積もり誤差でも、CIのしきい値判定に直結すると障害対応の手間を増やします。今回のような一方向バイアスの発見は、監視対象の指標を「実測せずに前提として使っていないか」を見直すきっかけになります。