AIエージェントを活用して繰り返しプロジェクト作業を自動化する

プロジェクトの内容をAIエージェントに何度も説明し直す手間を省く最速の方法は、その手順を一度だけClaude Codeスキルとして記録することです。これはリポジトリにコミットするディレクトリで、SKILL.mdファイルを含み、エージェントはそれを参照することで、アプリの起動方法・シード方法・デプロイ方法を毎回再調査せずに済みます。

シードされていないデータベースとコピーされていないenvファイルがなければアプリが起動しないことを、エージェントが10分かけて再発見するのを見たことがある人なら、この苦労はよくわかるでしょう。先週も、その前の週も、同じ手順を説明したはずです。本記事では具体的なパターンを紹介します。スキルがnpmスクリプトとどう違うのか、プロジェクトスコープのスキルはどこに配置するのか、そしてクリーンなチェックアウト状態からアプリを起動して動作を検証する実際の例を示します。主旨はシンプルです。忘れてしまうような使い捨てスクリプトを書くのをやめ、チーム全員とエージェントが共有できるプロジェクトスコープのエージェントスキルを導入しましょう。

忘れ去られるnpmスクリプトと陳腐化したセットアップドキュメントの真のコスト

古くなったセットアップ手順の本当のコストは、壊れたコマンドそのものではありません。人間またはエージェントが毎回その手順を再導出しなければならないことです。package.jsonには謎めいたエントリ（predev:seed、db:reset:ci、start:tunnel）が蓄積されていき、その実行順序と前提条件は特定のエンジニアの頭の中にしか存在しません。READMEの「Getting Started」セクションは、誰かが環境変数を追加してドキュメントへの反映を忘れた瞬間から陳腐化していきます。新しいコントリビューターは推測するしかなく、AIエージェントも同様に推測します。しかも両者の推測はたいてい食い違います。

スキルはこの問題を、エージェントがすでに参照している場所に手順を記録することで解決します。Claude Codeの公式ドキュメントでは、スキルを作成するタイミングを明確に定義しています。同じ指示・チェックリスト・複数ステップの手順を繰り返しチャットに貼り付けている場合、またはCLAUDE.mdのあるセクションが事実の記述ではなく手順書に成長してしまった場合が、スキルを作成するサインです。

スクリプトとスキルの違いは何か？

絶対に変えてはならないステップにはスクリプトを使い、解釈が必要なステップにはスキルを使いましょう。npmスクリプトは固定されたコマンドを所定の順序で実行します。一方スキルはモデルを使ってコンテキストを読み取り、変動要素を処理し、次に何をすべきかを判断した上で、決定論的な部分をコードに委ねます。両者は競合するものではなく、補完し合うものです。

Anthropicのエンジニアリングチームは、決定論的な処理をコードに委ねることの重要性を主張しています。特定の操作は従来のコード実行の方が適しています。リストのソートをトークン生成で行うのは、ソートアルゴリズムを実行するよりも遅く信頼性も低く、多くのワークフローではコードのみが提供できる再現性が必要です。重要な点として、バンドルされたスクリプトはコンテキストを節約できます。ファイルシステムとコード実行ツールを持つエージェントは、スキルの全内容をコンテキストウィンドウに読み込む必要がないため、スキルにバンドルできるコンテキストの量は事実上無制限です。

Claude Codeスキルとは何か、どこに配置するか？

Claude Codeスキルは、エージェントにいつ使用するかを伝えるYAMLフロントマターを持つSKILL.mdファイルを含むディレクトリです。Agent Skillsの概要によると、各スキルは指示・メタデータ・オプションのリソース（スクリプト、テンプレート）をパッケージ化し、Claudeが関連性を判断した際に自動的に使用します。これが正しいメンタルモデルです。スキルは単なるコマンドファイルではなく、ディレクトリです。

配置場所がスコープを決定します。プロジェクトスキルは、作業開始ディレクトリおよびリポジトリルートに向かう親ディレクトリ内の.claude/skills/から読み込まれます。そのため、プロジェクト内のどこで作業するエージェントもスキルを利用可能な状態で認識し、リクエストがdescriptionと一致すれば自動的に読み込まれます。個人スキルは~/.claude/skills/に配置します。Claude Code専用として、推奨されるのはdescriptionのみです。nameはオプションで、デフォルトはディレクトリ名となり、/の後に入力する名前にもなります。

構成要素は混同しやすいため、意図的に選択してください。

• スキル：ディレクトリ＋SKILL.md、オプションのバンドルスクリプト。descriptionによって自動検出され、/skill-nameで呼び出し可能。Claude.aiやClaude Desktopでも動作するため、チームはターミナル以外でも共有できます。
• スラッシュコマンド：従来は.claude/commands/内の単一の.mdファイル。カスタムコマンドはスキルに統合されました。.claude/commands/deploy.mdと.claude/skills/deploy/SKILL.mdはどちらも/deployを作成し、同じように動作します。名前が衝突した場合はスキルが優先されます。
• サブエージェント：.claude/agents/内の.mdファイルで、独自のコンテキストウィンドウで実行され、要約された結果を返します。タスクが読み取り量の多いもので、メインスレッドを汚染するほどの場合に活用します。

実践例：「クリーンなチェックアウトから起動して検証する」を記録する

セットアップの一連の手順をコミット済みのスキルに変換しましょう。.claude/skills/run-app/SKILL.mdを作成し、エージェントがマッチできるよう具体的なdescription、冒頭にインジェクトされるライブコマンド出力、そして番号付きのステップを記述します。

---
name: run-app
description: Get this app running from a clean checkout and verify it boots. Use when setting up the project, onboarding, or checking the app still starts after a change.
allowed-tools: Bash(npm *) Bash(./scripts/verify.sh *)
---

## Environment
```!
node --version
npm --version
```

## Steps
1. Install dependencies with `npm ci`.
2. If `.env` is missing, copy `.env.example` to `.env`; ask before overwriting.
3. Start the app with `npm run dev`.
4. Run `./scripts/verify.sh` and report PASS or FAIL.

Expected output: a single PASS/FAIL line and the local URL the app serves on.

フェンスされた```!ブロックは動的コンテキストインジェクションを使用します。Claude Codeはそれらのコマンドを実行し、エージェントがスキルを読む前に出力をインライン展開します。これにより、手順は推測ではなく実際のツールチェーンに基づいた内容として届きます。「アプリを起動して」と伝えればエージェントがdescriptionからスキルを読み込み、/run-appと入力すれば強制的に実行できます。

Claude Codeはこのパターンをバンドルスキルとして提供しています。/run-skill-generatorはクリーンな環境からアプリを起動し、うまくいった内容（インストールコマンド・環境変数・起動スクリプト）を記録して、.claude/skills/run-<name>/にプロジェクト固有のスキルとしてコミットします。その後は/run・/verify・リポジトリ内の他のエージェントが、再発見することなく記録済みの手順に従います。/run・/verify・/run-skill-generatorにはClaude Code v2.1.145以降が必要です。

スキルを信頼できるものにしてからコミットする

各スキルはアトミックに保ち、期待される出力を明示的に記述してください。1スキル・1ジョブ・1つの明確に定義された結果、これをプルリクエストでレビューできるようにします。曖昧な指示はドリフトを生み、出力形式を定義することで実行の一貫性が保たれ、後続の処理でのパースも安全になります。

変更不可なステップはバンドルされたscripts/verify.shに押し込め、SKILL.md本体には解釈の部分を担わせましょう。検証が失敗した理由のレポートや、欠落している環境変数の検出などです。この分離こそが、ワークフローを確率論的ではなく再現可能なものにします。

一つの実際の制限についても正直に述べておきます。自動呼び出しは完全にdescriptionに依存しており、常に発火するとは限りません。ドキュメントのトラブルシューティングの最初のステップは、descriptionにユーザーが自然に使うキーワードが含まれているか確認することです。確実な手動トリガーが必要な場合（副作用を伴う操作）は、disable-model-invocation: trueを設定して、/nameと入力した場合のみスキルが実行されるようにしましょう。

そして.claude/skills/をバージョン管理にコミットしてください。この一つの行為でループが閉じます。手順がバージョン管理され、レビュー可能になり、共有されます。次のコントリビューターも、次のエージェントセッションも、手順を再構築する代わりに動作する手順を引き継げます。スキルはClaude.ai・Claude Code・APIで利用可能であり、Anthropicのサポートドキュメントによると、Claude Codeユーザーとコード実行ツールを使用するすべてのAPIユーザー向けにベータ提供中です。コミットされたプロジェクトスキルは、誰か一人のシェル履歴に留まることなく、リポジトリとともに移動します。

最もよく繰り返されるタスク（クリーンチェックアウトからの起動・リリースチェンジログ・シードとリセット）から始めましょう。SKILL.mdを書き、決定論的な部分をスクリプトとしてバンドルし、コミットする。次に誰か（またはエージェント）がその手順を必要とするとき、すでに記録されています。

よくある質問

Claude Codeスキルは手動で呼び出すこともできますか？それとも自動トリガーのみですか？

両方できます。デフォルトでは、あなたもClaudeもスキルを呼び出せます。/skill-nameと入力して直接実行するか、descriptionがリクエストと一致した場合にClaudeが自動的に読み込みます。スキルを手動で実行できないと主張する古いガイドは情報が古くなっています。副作用のあるスキルに手動のみの動作が必要な場合は、disable-model-invocationをtrueに設定することで、名前を入力した場合のみ実行されるようになります。

スラッシュコマンドとスキルが同じ名前を持つ場合はどうなりますか？

スキルが優先されます。カスタムコマンドはスキルに統合されました。.claude/commands/deploy.mdと.claude/skills/deploy/SKILL.mdはどちらも同じ/deployコマンドを作成し、同じように動作します。同じ名前で両方が存在する場合、Claude Codeはコマンドファイルではなくスキルを読み込みます。そのため、1つのコマンドのために両方を維持する必要はありません。

スキル内にバンドルされたスクリプトはコンテキストウィンドウのトークンを消費しますか？

消費しません。スキルの指示が実行可能なスクリプトを参照している場合、ClaudeはBashでそれを実行し、出力のみを受け取ります。スクリプトのコード自体はコンテキストウィンドウに入りません。これが、決定論的な処理をスクリプトとしてバンドルする方が、モデルに推論させるよりも安価で信頼性が高い理由であり、スキルにバンドルできるリソースのサイズが事実上無制限である理由でもあります。

Claude Codeスキルを使用するためにプランへの加入が必要ですか？

いいえ。Anthropicのサポートドキュメントによると、スキルはFree・Pro・Max・Team・Enterpriseプランで利用可能であり、コード実行が有効になっている必要があります。Claude Code専用としてはベータ版で利用可能であり、コード実行ツールを使用するすべてのAPIユーザーでも動作します。利用可能条件は頻繁に変わるため、Anthropicの最新サポートドキュメントで確認してください。