Claude Code と Agent Skills SKILL.md で手順を載せる設計の入口（要公式確認）

AIとの対話が「チャット」から「エージェントによる実行」へと進化する中、Anthropicが提供する Claude Code は、開発現場にパラダイムシフトをもたらしています。単にコードを生成するだけでなく、ローカルリポジトリを直接操作し、テストを実行し、プルリクエストまで作成するこのCLIツールを使いこなす鍵は、「AIに対する手順の教え方」にあります。

本記事では、Claude CodeにおいてAIの振る舞いと実行能力を定義する CLAUDE.md や、拡張的な手順を格納する SKILL.md（およびそれに類するAgent Skillsの設計）について、実務的な設計の入口を徹底解説します。ドキュメントを「ただの読み物」から「AIが実行する指令書」へと変えるための完全ガイドです。

Claude Code × Agent Skills で実現する「自律型ドキュメント駆動開発」

これまでのDXにおけるドキュメント管理は、人間が読み、人間が手作業でツールを動かすためのものでした。しかし、Claude Codeを導入した環境では、「AIがドキュメントを読み、AIがツールを動かす」という逆転現象が起こります。

ここで重要になるのが、Anthropicの公式仕様やベストプラクティスに基づいた、エージェントへの「スキルの注入」です。具体的には、プロジェクトのコンテキストを伝える CLAUDE.md と、特定のタスク（例：特定のSaaSからのデータ抽出、複雑なビルド手順、定型レポートの生成）を覚えさせる SKILL.md の設計が、チームの生産性を左右します。

例えば、楽楽精算×freee会計の「CSV手作業」を滅ぼすアーキテクチャのような複雑なデータ加工フローも、Claude Codeにその「手順（Skill）」を明文化して渡すことで、CLI上で「月次の経理処理を実行して」と命じるだけで完結させることが可能になります。

Claude Code の基本構造とスキルの入口：CLAUDE.md と SKILL.md

Claude Codeをリポジトリで起動した際、エージェントはまず環境を理解しようとします。その際、最も優先的に参照されるのがプロジェクトルートに配置されたMarkdownファイル群です。

2.1. プロジェクト憲法としての CLAUDE.md

CLAUDE.md は、プロジェクト全体の「ルールブック」です。Anthropicの推奨では、以下の情報を記載することが期待されています。

• ビルド・テストのコマンド: npm run build や pytest など、AIが即座に実行すべきコマンド。
• コーディング規約: 「型定義は必ず行う」「命名規則はキャメルケース」といったスタイルガイド。
• アーキテクチャの概要: ディレクトリ構成の意味や、主要な技術スタック（Next.js, FastAPIなど）。

2.2. 実行手順のコンテナとしての SKILL.md

一方で、SKILL.md（または AGENTS.md）は、より動的な「手順」に特化します。これは、Claude Codeに搭載されている Agentic Workflow を拡張するための概念です。特定のビジネスロジックや、複数のツールをまたぐ複雑な操作を「スキル」として定義し、AIが迷わずに実行できるようにガイドします。

【公式準拠】Agent Skills を定義するための設計思想

Claude Codeにおける「スキル」とは、単なる自然文の羅列ではありません。エージェントが「今、自分はこのステップにいる」と認識できる構造化された情報が必要です。

3.1. スキル定義の3要素：名称、前提条件、ステップ

優れた SKILL.md は、以下の構造を持ちます。

1. Skill Name: エージェントがそのスキルを呼び出すための明確な名前。
2. Prerequisites: 実行に必要な環境変数（APIキー）、インストール済みツール、ファイル構成。
3. Execution Steps: 実行すべきシェルコマンドと、その期待される出力結果。

【重要】公式ドキュメントの確認事項

Claude Codeは、自身のターミナル実行能力（Shell execution）を活用します。スキルを定義する際は、抽象的な指示ではなく、cat, grep, curl, python などの具体的なコマンドライン操作と組み合わせることが、成功の近道です。

3.2. コンテキスト注入とローカル実行の仕組み

Claude Codeが SKILL.md を読み取ると、内部的なプロンプトにその内容が組み込まれます。ユーザーが「〇〇の作業をお願い」と入力した際、エージェントは SKILL.md のステップと現在のファイル状況を照らし合わせ、不足している要素があれば自ら ls や read_file を使って補完します。

実務での運用：誰が何を書き、Claude Code がどう動くか

具体的な業務シーンとして、「SaaSから出力された複雑なCSVを、特定の会計ソフト形式に変換し、Gitにコミットする」タスクを想定します。

4.1. 【事例】データ整形スキルを定義する

この運用では、プロジェクトのリポジトリに以下のような SKILL.md を配置します。

例えば、ミロク(MJS)からfreeeへの移行ガイドで求められるような、特殊な「単一行CSV」のAI変換などは、Claude Codeが得意とする領域です。スクリプトによる厳密な変換と、AIによる例外処理の推論を組み合わせた「スキル」を定義することで、エラーの少ない自動化が実現します。

4.2. ツール・エージェント比較：Claude Code vs 一般的なチャットAI

なぜ一般的なチャットWeb UIではなく、Claude Code（CLI）でスキルを管理すべきなのでしょうか。その違いを下表にまとめます。

エンジニアと非エンジニアの役割分担：Markdown を介した協調

Claude Codeの真価は、エンジニア以外が書いた「業務手順のMarkdown」を、エンジニアが「AIが実行可能なスキル」へと昇華させるワークフローにあります。

非エンジニアのメンバーが process_guide.md に日本語で業務フローを書きます。エンジニアは Claude Code を開き、次のように命じます。

「process_guide.md を読んで、これを自動化するための SKILL.md と Pythonスクリプトを作成して。ディレクトリ構成は CLAUDE.md の規約に従って。」

これにより、ビジネスロジックの知識（非エンジニア）と実装技術（エンジニア）が、Claude Codeという実行主体を通じてシームレスに統合されます。これは、Excelと紙の限界を突破するAppSheet活用のような、市民開発者とプロ開発者の協調に近いモデルを、コーディングの領域で実現するものです。

セキュリティとガバナンス：スキルの実行承認フロー

Claude Codeは強力なツールであるため、セキュリティ設定は慎重に行う必要があります。特に SKILL.md に定義された手順が、システムに致命的な変更を加える可能性がある場合、以下の運用を徹底してください。

• 許可制の維持: Claude Codeには、コマンド実行前にユーザーの承認を求めるプロセスがあります。--yes フラグによる完全自動化は、CI/CD環境などの限定された場所を除き、推奨されません。
• Read-Onlyスキルの活用: データの読み取りや分析のみを行うスキルと、書き込みを伴うスキルを SKILL.md 内で明確に分離します。
• 環境変数の保護: スキル内で必要なトークン類は、必ず .env やシステムの環境変数から読み出すように設計し、Markdownファイル自体には記述しないでください。

まとめ：Claude Code で「動くドキュメント」を資産化する

Claude Codeにおける SKILL.md や CLAUDE.md の設計は、単なるドキュメント作成ではなく、「AIエージェントのOS」を構築する作業に似ています。手順をリポジトリ内に構造化して配置することで、新しくチームに加わったメンバー（または新しく立ち上げたClaude Codeインスタンス）は、即座にベテランと同じ精度で業務を遂行できるようになります。

まずは、現在のプロジェクトに CLAUDE.md を作成し、ビルドコマンドを1行書くところから始めてみてください。それだけで、AIはあなたのプロジェクトの「良き理解者」から「頼れる実務担当者」へと進化するはずです。

詳細な仕様については、Anthropicの公式ドキュメント（Claude Code Documentation）を常に参照し、最新のAgent Skillsのアップデートを確認することをお勧めします。料金体系や利用制限についても、公式の「Billing」ページで最新情報を確認し、コストパフォーマンスの高いAI運用を目指しましょう。

3. **追記するHTMLだけ**（通常は `