Anthropic 社が提供する skill-creator は、コーディングエージェントに対して skill を追加する際に必須とも言えるツールです。この skill はユーザーの入力テキストから精度の高い skill を生成することができます。さらに、skill の評価や改善、比較することも可能です。

しばらく使っていく中で、skill-creator で作成やレビューした skill の中で、処理が途中で停止してしまうものがあることに気づきました。

この記事では、その不具合の原因と対応方法として追加した skill について紹介します。

複数 step で長時間処理する skill で発生した問題

Claude Code 用に GitHub 上の Issue やローカルの仕様ファイルをベースに実装を行う task skill を作成し使用していました。 仕様を Issue または仕様書 Markdown で作っておいて実装するための skill です。

  1. GitHub 上の Issue またはローカルのファイルパスを受け取る
  2. 実装方法を検討し計画する
  3. 実装を実施
  4. codex でコードレビューを実施、必要に応じて修正を行う
  5. Pull Request を作成する

この skill のうち、4 のコードレビューの部分でなぜか処理停止してしまう問題が発生していました。

処理が停止する原因

Claude Code とともに処理内容を確認したところ、4 のコードレビューの部分に問題があることがわかりました。

  • 修正前
    1. 指摘事項を自動修正すべき項目と人間の判断が必要な 2 グループに分類
    2. 自動修正
    3. 人間の判断が必要な項目をユーザーに提示
  • 修正後
    1. 指摘事項を自動修正すべき項目と人間の判断が必要な 2 グループに分類
    • 指摘事項が0 件の場合は 2,3 を skip し次の処理へ進む
    1. 自動修正
    2. 人間の判断が必要な項目をユーザーに提示

指摘事項 0 件の場合に、次の処理に進んでも処理対象がない。これが原因で処理が停止していることがわかりました。

対応方法: レビュー用 skill の追加

task skill は内部で他 skill を参照していたり、複数 step にわたって条件分岐付きの処理を行っていたため実装時に見落としていました。 この分岐に漏れがないかチェックするための skill を追加しレビュー時に使用することにしました。

この skill 自体も skill-creator で作成しています。

[!NOTE] 現在、この skill は会社のプライベートリポジトリで管理しているため 1 部のみ抜粋しています。

# audit-skill-branches コマンド

skill ドキュメント（`SKILL.md` と `references/*.md`）を静的に読み、
**条件分岐の網羅性と後続処理の記述**に絞って診断する skill。
診断主体は **ホストエージェント自身**。スクリプトは引数解析と対象 md の列挙のみを担い、
判定はホスト LLM が観点プロンプトを Read して内製で行う。

## なぜこの skill が必要か

skill が条件分岐を持つとき、片方のアームの後続処理が記述されていないと、
agent はその分岐に入った瞬間に「次に何をすべきか」を失う。例えば次のような書き方:

```markdown
- markdown ファイル: 本文を翻訳して frontmatter を保持する
- text ファイル: TODO
```

`text ファイル` を渡された agent は `TODO` 以降の手順を持たないため、応答が止まりやすい。
また「`else` / それ以外」の fallback が無い列挙、空の見出しセクション、
参照先が存在しない `下記参照` も同種の事故を生む。

これらは skill-creator の eval（実プロンプトを流して品質を測る動的評価）では拾いにくい。
**入力がその分岐に入って初めて顕在化する**ため、すべての分岐を流し切る 
eval を組まない限り見逃される。
本 skill は md を静的に読んで網羅性を確認することで、事故が起きる前に検出する。

その他の残った問題

skill-creator は skill を追加するための道具なので、その他の細かい問題についてはユーザー側で対応する必要があります。

今回紹介した分岐の問題に加え次のような問題が発生することがわかっています。

  • コーディングエージェントに用意されているコマンドや skill 名と重複した skill を作ってしまう
  • 複数ファイルを参照する場合に、skill-creator ベースでレビューを実施した場合に漏れる場合がある

人間のレビューには原因があるので随時 skill や linter ツールを追加して対応していくことで改善が可能です。