Claude Codeのスキル機能でAWSアーキテクチャ図の自動生成を実現した話
はじめに
「AWSの構成図を作って」——このひと言で、正しいアイコン・正しい色・正しいレイアウトのDraw.ioファイルが生成されたら便利だと思いませんか？
Claude Codeの スキル（Skills） 機能を使って、AWSアーキテクチャ図を自動生成するaws-architecture-diagramを作りました。
本記事では、なぜスキルという形にしたのか、どんな課題をどう解決したのか、そしてスキル設計の哲学について書きます。
Claude Codeの「スキル」とは
Claude Codeには、.claude/skills/ ディレクトリに定義ファイルを配置することで、特定のタスクに対する専門知識をClaudeに持たせるスキル機能があります。
.claude/skills/<skill-name>/
├── SKILL.md # ワークフロー定義
├── references/ # 参照データ
└── templates/ # テンプレート
スキルは単なるプロンプトテンプレートではありません。複数の参照ファイルを持てるため、コンテキストウィンドウに収まりきらない大量の参照データを必要に応じて読み込ませることができます。これが「コマンド」との決定的な違いです。
なぜAWSアーキテクチャ図にスキルが必要だったのか
問題：アイコンが正しくない
LLMにDraw.ioのAWS構成図を生成させると、ほぼ確実にアイコンが壊れます。理由は明白で、Draw.ioのAWSアイコンは mxgraph.aws4.* という独自のシェイプ名体系を使っており、正確なシェイプ名を知らなければ正しいアイコンは表示されません。
例えば、Amazon Bedrockのアイコンは mxgraph.aws4.bedrock です。「bedrock」と推測できる場合もありますが、AWS Certificate Managerは certificate_manager_3、CloudWatchは cloudwatch_2 と、バージョン番号付きの名前がざらにあります。
さらに厄介なのが 2種類のアイコンパターン の存在です。
2つのアイコンパターン
Draw.ioのAWSアイコンには、 サービスレベルアイコン（resourceIcon） と リソースレベルアイコン（dedicated shape） の2パターンがあります。
サービスレベルアイコン（resourceIcon） は、色付き背景に白いグリフが乗ったおなじみのアイコンです。
shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.lambda;
fillColor=#ED7100;strokeColor=#ffffff;
ここで strokeColor=#ffffff が 必須 です。これを忘れるとグリフが白く表示されず、アイコンが崩壊します。これが最大のハマりポイントでした。
リソースレベルアイコン（dedicated shape） は、シルエット型の個別シェイプです。
shape=mxgraph.aws4.lambda_function;
fillColor=#ED7100;strokeColor=none;
こちらは strokeColor=none です。2つのパターンで strokeColor の値が逆なので、混同すると確実にアイコンが壊れます。
アイコンデータの権威あるソース
正しいシェイプ名をどこから取得するかが最も重要な問題でした。AWSの公式ドキュメントにはDraw.io用のシェイプ名は記載されていません。
答えは、Draw.ioのソースコードにありました。
jgraph/drawioリポジトリの src/main/webapp/js/diagramly/sidebar/Sidebar-AWS4.js（約234KB、2500行超）に、全AWSアイコンのパレット定義があります。このファイルから、全カテゴリ・全アイコンのシェイプ名と表示名を抽出しました。
カテゴリと公式カラー
Draw.ioのソースから確認した公式カラーは以下の通りです。
| カテゴリ | fillColor | 代表的なサービス |
|---|---|---|
| Compute & Containers | #ED7100 |
EC2, Lambda, ECS, Fargate |
| Storage | #7AA116 |
S3, EBS, EFS |
| Database | #C925D1 |
RDS, DynamoDB, Aurora |
| Networking & CDN | #8C4FFF |
VPC, CloudFront, Route 53 |
| App Integration | #E7157B |
API Gateway, SQS, SNS, Step Functions |
| AI / Machine Learning | #01A88D |
Bedrock, SageMaker |
| Security | #DD344C |
IAM, Cognito, WAF |
これらの色をカテゴリ間で混ぜて使うとAWSの公式デザインガイドラインに反するため、スキルのルールとして「fillColorはカテゴリに厳密に対応させる」と定義しました。
スキルの構成
最終的なスキルのディレクトリ構成はこうなりました。
.claude/skills/aws-architecture-diagram/
├── SKILL.md # ワークフロー定義（5ステップ + 12ルール）
├── references/
│ ├── aws-icons-compute.md # Compute & Containers（41アイコン）
│ ├── aws-icons-storage-database.md # Storage & Database（38アイコン）
│ ├── aws-icons-networking.md # Networking & CDN（68アイコン）
│ ├── aws-icons-app-integration.md # App Integration & Mgmt（52アイコン）
│ ├── aws-icons-analytics-ml.md # Analytics & AI/ML（70アイコン）
│ ├── aws-icons-security.md # Security（61アイコン）
│ ├── aws-icons-common.md # General resources, Groups, Arrows
│ └── layout-guidelines.md # レイアウトルール
└── templates/
└── base.drawio.xml # 最小限のDraw.ioスケルトン
参照ファイルをカテゴリごとに分割しているのがポイントです。全アイコンデータを1ファイルにまとめると巨大になりすぎますが、カテゴリ単位に分ければ、Claudeは必要なファイルだけを読み込めます。
SKILL.mdのワークフロー
スキルの中核である SKILL.md は、5ステップのワークフローを定義しています。
ステップ1: リクエストの理解と確認
- Identify which AWS services are needed
- Determine the architecture pattern
- **Assess the audience**: technical vs non-technical
- **Ask the user** for language preference (English or 日本語)
スキルは最初に言語を確認します。日本語と英語では、ラベルの長さやレイアウトの収まりが変わるためです。
また対象読者の判定も最初のステップに入れました。技術者向けとマネージャー向けでは、ラベルの粒度もエッジの説明も大きく変わります。
ステップ2: アイコンの参照
**CRITICAL**: Always look up icons before generating XML. Never guess icon names.
このルールが最重要です。「推測するな、参照しろ」。LLMは自信満々に間違ったシェイプ名を出力するため、必ず参照ファイルを読むことを強制しています。
ステップ3〜4: レイアウト → XML生成
レイアウトガイドラインに従って配置を決め、テンプレートXMLをベースに構成図を組み立てます。
ステップ5: 2つのファイルを出力
スキルは .drawio ファイルだけでなく、**コンパニオンガイド（Markdown）**も一緒に生成します。
docs/
├── rag-helpdesk-architecture.drawio # Draw.io構成図
└── rag-helpdesk-architecture.md # 読み解きガイド
ファイル名には図の内容を表す kebab-caseのslug を使います。architecture.drawio のような汎用名ではなく、rag-helpdesk-architecture のように内容が分かる名前にすることで、複数の図がある場合も混乱しません。
コンパニオンガイドには以下を含めます。
- 概要: このアーキテクチャが何をするか（1-2文）
- コンポーネント一覧: 各AWSサービスの役割と採用理由
- データフロー解説: 図のステップ番号に対応した詳しい説明
- 設計判断: なぜサーバーレスか、なぜこのDBか等の補足
- コスト・スケーリングメモ（任意）: 計画時に役立つ情報
図は「全体像を一目で伝える」もの、ガイドは「なぜそうなっているかを説明する」もの。この2つがセットになることで、図を見た人が自分で判断・議論できるようになります。
非技術者向けモード：ステップ番号とスイムレーン
スキルを実際に使い始めて最初にぶつかった課題が、「この図、エンジニア以外には伝わらない」でした。
技術的に正確な図と、ステークホルダーに伝わる図は別物です。そこでNon-Technical Audience Modeをスキルに追加しました。
ステップ番号付きエッジ
技術的なラベル（HTTPS、REST API等）の代わりに、丸数字でフローの順序を示します。
- フローA: ① → ② → ③ → ④（白丸数字）
- フローB: ❶ → ❷ → ❸ → ❹（黒丸数字）
複数フローがある場合、異なるスタイルの丸数字を使って視覚的に区別します。
簡略化ラベル
| 技術的な表現 | 簡略化 |
|---|---|
| REST API call | チケット取得 |
| チャンク分割・埋め込み | AI学習用に変換 |
| k-NNベクトルインデックス | 検索データベース |
| OpenSearch Serverless | OpenSearch |
| Site-to-Site VPN | VPN接続 |
ポイントは何をしているかを一言で表すことです。技術的にどう実現しているかは、この図の役割ではありません。
スイムレーンとフロー概要
複数のデータフローがある場合、レーンヘッダーにフロー全体の流れを記載します。
データ処理フロー: ① チケット取得 → ② データ保存 → ③ AI変換 → ④ 索引化
読者はレーンヘッダーを読むだけで全体像を把握でき、詳細は図の中で確認する、という2段階の情報設計になります。
PNG書き出しの罠
Draw.ioで図をPNG書き出しすると、グループやコンテナの外側の領域は黒背景になります。凡例やタイトルをグループの外に配置していた場合、書き出したPNGでは黒背景の上に乗ってしまい非常に見にくくなります。
解決策は単純で、図全体を覆う薄いグレー（#F5F5F5）の矩形を最背面に配置します。
rounded=1;whiteSpace=wrap;fillColor=#F5F5F5;strokeColor=#E0E0E0;arcSize=2;
タイトル、スイムレーン、凡例——すべてをこの背景矩形の中に収めることで、どんな書き出し設定でも読みやすい図が得られます。
スキル設計の哲学
このスキルを作る過程で見えてきた、Claude Codeスキル設計の原則をまとめます。
1. 参照データは推測させない
LLMは「それっぽい答え」を出すのが得意ですが、Draw.ioのシェイプ名のように1文字でも間違えるとまったく動かないものには通用しません。正確なデータを参照ファイルとして用意し、「必ず読め」とルールに書く。これが最も重要な設計判断でした。
2. 権威あるソースから機械的に抽出する
アイコンデータを手動でリストアップすると、漏れや誤りが発生します。今回はDraw.ioリポジトリの Sidebar-AWS4.js からPythonスクリプトで機械的に抽出しました。抽出スクリプト自体はスキルには含めていません。スキルに必要なのは抽出結果（参照データ）のみであり、抽出方法は一時的なものです。
3. ルールは具体的に書く
「アイコンを正しく使う」ではなく「strokeColor=#ffffff を使え」と書く。「レイアウトを整える」ではなく「アイコン間隔は80-120px、グループパディングは30px」と書く。具体的な数値やコードスニペットがあるルールだけが、LLMに確実に守られます。
4. 実際に使ってからスキルを更新する
最初に設計したスキルと、実際に図を作った後のスキルは大きく異なります。Non-Technical Audience Mode、PNG書き出し対策、単一AWS Cloudグループの推奨——これらはすべて、スキルを使って図を作った経験から追加されたルールです。
スキルは一度作って終わりではなく、使いながら育てるものです。
5. 参照データはカテゴリで分割する
全データを1ファイルにまとめるとコンテキストウィンドウを圧迫します。カテゴリ単位で分割すれば、「Lambdaの図を作りたい」ときは aws-icons-compute.md だけ読めばよく、効率的です。
使い方
スキルをリポジトリに配置した状態で、Claude Codeに以下のように指示するだけです。
RAGアーキテクチャの構成図を作って。
Bedrock、OpenSearch、Lambda、S3、API Gatewayを使う。
非技術者向けに分かりやすく。
Claudeはまず言語を聞いてきます。その後、自動的に参照ファイルからアイコンを調べ、レイアウトガイドラインに従ってDraw.ioファイルとコンパニオンガイドの2ファイルを生成します。
✅ docs/rag-helpdesk-architecture.drawio — Draw.ioで開いて確認
✅ docs/rag-helpdesk-architecture.md — 図の読み解きガイド
まとめ
Claude Codeのスキル機能を使って、AWSアーキテクチャ図の自動生成を仕組み化しました。
鍵となったのは以下の点です。
- 権威あるソース（Draw.ioリポジトリ）からアイコンデータを機械的に抽出
- 参照ファイルとしてカテゴリ別に整理し、推測ではなく参照を強制
- 実際に使った経験をスキルにフィードバックし、非技術者向けモードやPNG書き出し対策を追加
- 図だけでなくガイドも生成し、「見て分かる」と「読んで分かる」の両方をカバー
「構成図を作って」のひと言で、正しいアイコンの図と読み解きガイドがセットで出てくる——この体験は、スキル設計に手間をかける価値があります。
スキルのソースコードはGitHubで公開しています。自分のプロジェクトに合わせてカスタマイズしてみてください。
