Claude CodeのSkills、23件全部削除した
2025年10月16日、Anthropic は Agent Skills を発表した。Claude Code を含む Claude 製品に、指示、スクリプト、参考資料を一つのフォルダとして追加できる仕組みだった。
その71日後、12月26日に、私は最初の SKILL.md を自分のリポジトリへ追加した。登壇資料とブログ記事を作るための、113行の手順書だった。2日後には日次運用とリポジトリ同期にも広げた。それから約8か月で、skills は23件になった。
2026年8月27日、私はその23件をすべて削除し、.claude/skills/ を空にした。
この記事では、自然言語で Coding Agent を拡張するための優れた入口だった skills が、同じ仕事を繰り返すうちに固定費として見えるようになった過程を書く。そして、定型処理をコードへ移し、情報の流れを組み直した結果、本当に速く安くなったのかを実測で確かめる。
Coding Agent はソフトウェア設計を不要にしなかった。繰り返す処理はコードにし、そのコードを agent が迷わず使える形にする。どこまでをコードにし、どこからを agent に任せるのか。その境界を、実際の待ち時間と繰り返しから見極める必要がある。
私にとって skills は何だったのか
skills は私にとって革命的であった。数ヶ月の間、ソフトウェア開発が民主化するという夢を信じさせてくれた。
skills とは、Claude に仕事のやり方を教えるための仕組みである。中心には SKILL.md というマニュアルを置く。必要なら、見本、参考資料、コードも一緒に入れられる。Claude は最初にスキルの名前と短い説明を見て、依頼に合うものを選び、その時になってマニュアルを読む。
衝撃的だったのは、そのマニュアルを普段の言葉で書けたことだ。「日報はこの順序で作る」「この資料を作るときは、まず情報を集め、次に構成を決める」。それだけで、次の session の Claude も同じ仕事の進め方を使える。プラグインや API を実装する必要はない。プログラムを書けない人でも、自分の仕事を説明できれば agent を自分用に拡張できた。
Anthropic は発表時、skill を新入社員向けのオンボーディングガイドになぞらえ、誰でも手続き知識を記録・共有することで agent を専門化できると説明した。同じ日、Django の共同開発者 Simon Willison は 「Claude Skills are awesome, maybe a bigger deal than MCP」 と題し、skills の「カンブリア爆発」を予想した。
私も MCP よりはるかに裾野が広がると期待した。最初に作った skill は、登壇資料を作った経験を「情報収集、インタビュー、構成決定、執筆、PDF化」という再利用可能な流れにしたものだった。それまで自分の頭にしかなかった仕事の進め方を文章にすれば、Claude Code と共有できた。
2日後には日次運用とリポジトリ同期へ広げた。その後も、タスク管理や週次レビューなど、Claude Code に任せたい仕事が見つかるたびに skill を増やした。うまくいかなければ手順を書き足した（もちろん Claude Code 経由で）。一度きりだった仕事の工夫が、agent の再利用可能な能力になっていくように見えた。
業務の型を言語化する。agent がそれに従い自分と同等の仕事をする。フィードバックをすると agent 自身が skills を育てる。理想的な仕事のスタイルが始まると思っていた。
日報を作るだけで、なぜ数十秒も待つのか
最初のうちは、処理が一から生成される時間も魔法の一部に見えた。自分がコードを書かなくても、日本語のマニュアルを書くだけで思った通りに仕事をしてくれる。だが、同じ操作を毎日繰り返す段階になると話が変わった。
私の業務基盤には、1日の開始と終了、タスクの作成と完了、リポジトリの同期、週次レビューといった繰り返しがある。日報の作成はテンプレートからファイルをコピーするだけである。タスクのステータス更新も GitHub API を叩くだけだ。それなのに数十秒待つ。正しい結果も返るのだが、遅い。この程度のことで、なぜこんなに時間がかかるのか？
二つの原因があった。
同じ処理を、毎回作り直していた
最初は skill に手順を書き、Claude Code に対象を探させ、日付を計算させ、必要なコマンド列や API を呼ぶプログラムをその場で作らせていた。つまり、前にも解いた処理を毎回推論し、実装し直していた。そのたびにトークンと時間を使い、ときには結果も揺れた。
skills の強みは、仕事を言葉で説明するだけで動かせることだった。だが、言葉のままでも動くからこそ、一度コードにすればよい処理を毎回生成している非効率に気づきにくい。
そこで、毎回同じ結果でよい部分を Python や shell script に移し、Taskfile のコマンドとして定義していった。LLM には「何をすべきか」という判断を任せ、ファイル更新や日付計算、GitHub との同期はテスト可能なコードに任せる。これは以前書いた 「LLMに計算させるな」 と同じ境界の引き方である。
一度コードに落とせば、agent が処理方法を毎回推論し、コードを生成する必要はない。決まったコマンドを呼べば、速く、同じ結果が返る。一つ目の無駄はこれで消えた。
処理をコードにしても、説明書が残った
この時点の構成は、次のようになっていた。
人の依頼
↓
SKILL.md が手順を説明する
↓
task コマンドを選ぶ
↓
script が処理する処理の本体はコードになった。ところが、agent がそのコマンドへたどり着くための SKILL.md は、自然言語だけで仕事をさせていた時期のまま残った。
さらに、skill の動きに問題があってフィードバックすると、Claude Code は改善として SKILL.md に新しいルールを書き足した。その瞬間の問題は場当たり的に解決する。そうして、気付かないうちに肥大していった。
象徴的だったのが、日次・週次・月次の運用を一つにまとめた skill である。気づいたときには SKILL.md が約1万トークンに育っていた。「そんなに大きいなら分割しろよ」というのはもっともな指摘だ。だが、元はシンプルな SKILL.md だった。じわじわとスコープが広がり、事例が追加され、気づけばこんなことになっていた。
日報に必要なのはその一部だけなのに、週次・月次運用の説明まで毎回一緒に読み込んでいた。
どれほどの負担なのかを確かめるため、過去8週間、1,068セッションの transcript を機械集計した。repo 内の skills が呼ばれたのは189回。読み込みに伴って増えた入力は、合計 1,476,419トークンだった。1回呼ぶたび、平均で約 7,800トークンを追加で読んでいた計算になる。skill を呼ぶだけでこれだけコンテキストが増えてしまう状態になっていた。
| 呼ばれた場面 | 回数 | 1回あたり | 8週間の累計 | 全体比 |
|---|---|---|---|---|
| タスクの開始・完了・中断 | 65回 | 8,019 tok | 521,235 tok | 35.3% |
| 1日の開始・終了 | 57回 | 12,418 tok | 707,826 tok | 47.9% |
| 複数のタスクを複数の agent に分けて進める | 28回 | 6,009 tok | 168,252 tok | 11.4% |
| その他 | 39回 | — | 79,106 tok | 5.4% |
| 計 | 189回 | 平均7,812 tok | 1,476,419 tok | 100% |
タスク管理、日報管理、複数の agent に仕事を分けるための主要3件だけで、全体の94.6%を占めた。これらは毎日使うため、効率化が消費トークンや待ち時間に直結する。
手順書からコマンドを探す流れを、逆転させる
現在、業界では progressive disclosure、すなわち必要なときに必要な情報だけを読み込む設計が主流になっている。
Anthropic は context engineering の指針 で、最小限の高シグナルな context と just-in-time な取得を勧めている。OpenAI の tool search も、最初から全ツール定義を載せず、関連するものだけを実行時に読み込む。Anthropic の skill 作成ガイド は、決定論的な処理には説明文より script を使うよう明記している。
私の SKILL.md は、複数の task コマンドの使い方を一つに集約したため、使わない説明まで最初に読み込むアンチパターンになっていた。そこで、コマンド一覧、コマンドごとの短い説明、詳しい docs へと分け、段階的に情報を開示できるようにした。
変更前
厚い手順書を読む → 該当する操作を探す → コマンドを実行する
変更後
薄いカタログ → 短いヘルプ → 実行 → 必要なときだけ docs
task --list --summary stdout 長い背景・例外常時読み込む層には「どこを見ればよいか」だけを置く。コマンドの一覧から候補を選び、短い summary で使い方を確認する。実行後は stdout が次の操作を案内し、長い規約や設計背景が必要なときだけ docs/ を開く。仕事を始める前に万全の知識を与えるのではなく、進めながら必要な情報へ到達させる。
今の agent は、薄い案内さえあればコマンドの一覧を調べ、ヘルプを読み、必要な docs へ進める。私の定型業務では、Anthropic が用意した skills の自動ロードに頼る必要はなくなっていた。Taskfile を共通の入口にすることで、skills で目指した再現性を、より少ない context と実行可能なコードで支えることにした。副次的に、この業務基盤は provider 非依存になった。
skills を卒業して、何が変わったか
仕事量の違いを効果と取り違えないよう、同じ日次処理と、条件をそろえた複数 agent の業務で前後を比較した。
| 測ったもの | before | after | 変化 |
|---|---|---|---|
| 1日の開始・終了処理の入力 | 119,175 tok | 56,960 tok | -52.2% |
| 同処理の往復 | 2ターン | 1ターン | -1ターン |
| 同処理の所要時間 | 9.6秒 | 3.8秒 | -60.4% |
| 複数 agent で同じ仕事を進めたときの往復 | 5ターン | 3ターン | -2ターン |
| 同じ仕事にかかった費用 | $13.72 | $6.99 | -49.1% |
日報管理では入力トークンが52%、時間が60%減った。複数の agent に仕事を分けるテストシナリオでも、ターン数と費用はほぼ半分になった。効率が大幅に向上した。
skills 卒業後は1週間の様子見をした。緊張しながら仕事をしていたが、タスク管理、日報管理、複数の agent を使う業務で不都合は発生しなかった。人間から再指示する必要も、コマンドが見つからない場面もなかった。
全業務の出力が卒業前と同じ精度だと証明したわけではないが、速く安くなり、確認した範囲では使い勝手も失われていなかった。
Coding Agent は、ソフトウェア設計を不要にしなかった
skills はソフトウェア開発の入口を広げた。その先で私がたどり着いたのは、ソフトウェア設計が不要な世界ではなかった。
日報を作るなら、一つのコマンドで完結させる。引数の意味に agent が迷うなら、引数を減らすか、目的の違うコマンドに分ける。毎回同じファイルを探し、日付を計算し、同じ API を呼んでいるなら、その処理を script にする。作った部品にはテストを置き、失敗したら検知できるようにする。求められるのは、従来のソフトウェア開発と同じ設計である。
ただし、すべての部品をコードで固くつなぐ必要はなくなった。人の依頼を読み、必要なコマンドを選び、複数の部品を組み合わせる部分は Coding Agent に任せられる。一度しか現れない例外なら、その場でコードを書かせてもよい。何度も現れる処理だけを、速く、迷いなく使える部品にすればよい。
新しい仕事でも、私はもう SKILL.md を起点にはしない。自然言語で仕事を探るために、その試行錯誤を自動ロードされる手順書へ積み上げる必要はないからだ。まず Coding Agent と実際に仕事をする。同じコードを二度、三度と生成していることに気づいたら、コマンドにする。コマンドの使い方で迷うなら、インターフェースを直す。説明が長くなったら、一覧、短いヘルプ、必要なときだけ読む docs に分ける。
どこまでをコードにし、どこからを推論に任せるかは、一般論だけでは決められない。同じコードを何度も生成していないか、agent が引数で迷っていないか、使わない説明まで毎回読ませていないか。モデルが変われば、その境界も変わる。日々の仕事でそれらを観察し、繰り返す部分をコードへ移していく。
Coding Agent を使いこなすとは、指示書を増やすことではない。agent が使う道具を、通常のソフトウェアと同じように設計し、計測し、直し続けることだ。