AIエージェント（Claude Code）を使っていて、最近いちばん効いていると感じるのが「スキル」の手入れです。スキルとは、特定の作業の進め方をひとまとめにした指示書のこと。呼び出すだけで、AIがその手順どおりに動いてくれます。便利な反面、一度書いて放置すると、じわじわ実態とズレていきます。今日は、そのスキルをどう更新しているかを書いてみます。
なお以降の具体例は、私が普段使っている**「テスト仕様書を作成するスキル」**の話です。仕様書のもとになる資料を読み、項目を洗い出し、変換ツールで成果物（表計算ファイルなど）に落とす——この一連の手順をスキルにまとめてあります。以下の失敗談も、すべてこの作業の中で起きたものです。
使う → 気づく → 書き戻す
私のスキル更新は、この小さなループを回し続けることに尽きます。作業で使い、うまくいかない点や新しい発見に気づき、それを手順へ書き戻します。大きく作り直すのではなく、毎回ほんの一行ずつ育てていきます。
description は「入口」だと考える
スキルは本体の手順に加えて、名前と一行の説明（description）を持ちます。見落としがちですが、この一行はただの飾りではありません。AIが「今の作業にどのスキルを使うべきか」を判断する入口になるからです。
説明がぼんやりしていると、必要な場面で呼び出されず、逆に関係ない場面で選ばれてしまいます。なので更新のたびに、「どんな状況で・何のために使うか」が一文で伝わるかを見直します。手順そのものより、この一行の精度が使い勝手を左右します。
踏んだ落とし穴を、その場で書き戻す
いちばん価値があるのは、実際にハマった失敗を手順化することです。テスト仕様書づくりのスキルでも、こんな更新がありました。いずれも「もともとの手順では防げなかった失敗」を、一行のルールとして書き足したものです。
表1：もとの手順・つまずき・書き戻したルール| もとの手順 | つまずき（起きたこと） | 書き戻したルール |
|---|---|---|
| 資料のセルを読んで確定文言を拾う | 確定文言がセルではなく図形（テキストボックス）の中にあり、見落とした | 記載の有無は、セルだけでなく図形の中まで見てから判断する |
| 洗い出した項目を変換ツールで成果物に変換する | 3階層の採番（1-1-1 など）がツールに無言でスキップされ、件数が欠けた | 生成後に、入力の件数と成果物の件数が一致するか必ず確認する |
| データ取得APIを叩いて中身を確認する | 使うツール側の固有のクセを踏んだ（例：一覧APIは件数指定によってはエラーになる仕様だった） | ツール固有のクセは前提として手順に固定しておき、毎回そのやり方で叩く |
3つ目だけ少し毛色が違います。1・2は「読み方・確認の仕方」という汎用的な学びですが、3つ目は使っているツールやAPIの固有のクセです。この種の落とし穴は他人には想像しづらく、記憶にも残りにくい。だからこそ、一度踏んだら「そういうもの」として手順に埋め込んでしまうのが効きます。（具体的には、ある一覧APIで特定の件数指定がエラーになる仕様があり、それを避ける叩き方を手順に固定しました。）
一度言語化して書き戻せば、同じ失敗は繰り返しません。しかも人間が覚えておく必要がなくなり、AIが毎回その前提で動いてくれます。これが、スキル更新の最大の見返りです。
追加するだけでなく、時には分ける
ただし、気づくたびに足すだけでは手順は肥大化します。長すぎるスキルは、かえって読み違いや矛盾を生みます。更新時には「足す」と同じくらい「削る・分ける」を意識します。
まとめ
スキルは、作った瞬間がゴールではありません。作業のたびに新しい気づきが出て、環境やルールも動いていきます。だからこそ、使う → 気づく → 書き戻すを小さく回し続けることが大事です。AIに任せる範囲が広がるほど、その土台となる指示書の鮮度が成果を決めます。今日の作業でひとつでも「次はこうしよう」と思ったら、その場でスキルに追加するかを考えます。地味ですが、いちばん確実にAIの精度を上げてくれる習慣だと感じています。
