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.md・SKILL.md設計パターン × 承認フローの必要レベル 早見表

前のセクションでClaude Codeのエンジニアと非エンジニアの役割分担と実務運用パターンを説明しましたが、「個人開発者」「スタートアップの小チーム」「中堅企業の開発部門」「エンタープライズのCOE（センターオブエクセレンス）」ではCLAUDE.mdとSKILL.mdの設計に求められる詳細度・ガバナンス設計・承認フローの厳格さが根本的に異なります。個人開発者向けのシンプルなCLAUDE.md設計をそのままエンタープライズに適用すると、セキュリティ要件と運用管理の観点から問題が発生します。チーム構成に合わせた段階的な設計指針を整理しました。

この表でClaude Code×CLAUDE.md×SKILL.md設計の最重要判断が「現在のチーム規模に適したガバナンスレベルを選び、過剰設計と過少設計の両方を避けること」です。スタートアップが「エンタープライズ級の厳格な承認フロー」を最初から設計すると開発速度が著しく低下し、逆にエンタープライズが「個人開発者向けのシンプル設計」のまま全社展開すると情報漏洩・コンプライアンスリスクが顕在化します。上記の表を参考に自社のフェーズに合った設計からスタートして、組織規模の拡大に応じて段階的にガバナンスを強化するロードマップを描くことがClaude Code活用の持続的な成功条件です。

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

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運用を目指しましょう。

SKILL.mdにSaaS連携や外部API呼び出しを定義する際は、APIトークンをMarkdown本文に書かず環境変数から読み出す構成と、書き込みを伴うスキルを読み取り専用スキルと明確に分離する設計がセキュリティの要点です。CLAUDE.md・SKILL.mdの設計やチーム展開の進め方は、Claude Code 導入支援でご相談いただけます。