開発現場で避けては通れない「画面仕様書の作成」。手動でスクリーンショットを撮り、ExcelやWikiにコンポーネントを書き出す作業に疲弊していませんか？
今回は、Claude Codeの「Agent Skills」とブラウザ操作ツール「Playwright MCP」を組み合わせ、AIが自律的にサイトを巡回して仕様書を書き上げる「究極の自動化」を実現した全記録を公開します。
1. はじめに：AIが「自分のスキル」を作る時代へ
今回使用したのは、AIが自ら新しい能力を獲得する「Skill-Creator」という仕組みです。
単にAIに作業を頼むのではなく、「仕様書を生成するための専用ツール（Agent）」をAIに自作させ、そのツールを使って業務を完遂させるという、一段上の自動化プロセスに挑戦しました。
2. 環境構築：3つのステップで準備完了
まずは、AIに「手」と「知能」を与えるためのセットアップを行います。
① Agent Skillsのインストール
Claude Codeにスキルを扱うためのマーケットプレイスを追加します。
# スキルマーケットプレイスを追加 /plugin marketplace add anthropics/skills # 基本となるスキルセット（Skill-Creator含む）をインストール /plugin install example-skills@anthropic-agent-skills
② Playwright MCPのセットアップ
AIがブラウザを操作するためのツールを導入します。
# Playwright MCP の本体をインストール npm install -g @playwright/mcp
Claude Code の設定ファイル（~/.claude.json または .claude/settings.json）に設定を追記し、ClaudeがPlaywrightを認識できるようにします。
# JSON
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@playwright/mcp"]
}
}
3. スキル作成：AIとの「作戦会議」でAgentを形にする
準備ができたら、AI（Skill-Creator）に「仕様書を自動生成する専用スキル」を作らせます。ここで驚いたのは、AIがただ指示に従うだけでなく、「仕様の認識合わせ」を求めてきたことです。
① スキル作成
人間：skill-creatorを使って、playwright MCPを使って特定の画面から仕様を抜き出すスキルを作成して AI：⏺ Skill(example-skills:skill-creator) ⎿ Successfully loaded skill Recalled 1 memory (ctrl+o to expand) ⏺ スキル作成を始める前に、意図を正確に把握するためいくつか確認させてください。 確認事項 1. 「仕様を抜き出す」の具体的な意味は？ - a) 画面のUI構造（ボタン、フォーム、入力項目など）を文書化する - b) 画面の動作・フロー（クリック時の挙動、バリデーションなど）を記録する - c) 両方（UI構造 + 動作仕様） 2. 出力形式は？ - Markdown文書？ - JSON？ - 特定のフォーマット（例：機能仕様書テンプレート） 3. 入力はどのように指定する？ - URL直接指定？ - ローカルサーバーのルートパス指定？ - 複数画面をまとめて処理する？ 4. Playwright MCPはすでに設定済みですか？ - どのMCPサーバー名で登録されているか（例：mcp__playwright__*） 5. このプロジェクト（organo_kantan_ai_pack_front）用に特化したい？ - 汎用的なスキルとして使いたい？ - プロジェクト固有のフォーマットに合わせたい？ --- 大まかなイメージとして、こんなスキルを想定しています： ▎ ユーザーがURLや画面名を指定 → Playwrightで画面をブラウズ → UIコンポーネント・動作を自動解析 → 仕様書（Markdown等）を出力 方向性はこれで合っていますか？ 人間：c,Markdown文書,複数画面をまとめて処理する？,playwright MCPはまだ出来ていない,汎用的なスキルとして使いたい,方向性は合ってる ⏺ ありがとうございます。方向性が固まったので、スキルを作成します。 ・・・
②作成されたスキル
# Screen Specification Extractor
Playwright MCP を使って、指定された複数の画面を自動でブラウズし、
UI構造・コンポーネント・動作・フローを網羅したMarkdown仕様書を生成するコマンドです。
---
## Step 0: Playwright MCP の確認
まずPlaywright MCPが利用可能か確認します。
`browser_snapshot` や `browser_navigate` ツールが存在すれば利用可能です。
**未設定の場合は以下をユーザーに案内してください:**
---bash
# インストール
npm install -g @playwright/mcp
---
Claude Code の設定ファイル（`~/.claude.json` または `.claude/settings.json`）に追加:
---json
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@playwright/mcp"]
}
}
}
---
設定後、Claude Code を再起動してから再試行するよう伝えてください。
---
## Step 1: 情報収集
ユーザーに以下を確認してください（まだ聞いていない場合）:
1. **対象URLのリスト** — ローカル開発サーバー (`http://localhost:3000`) またはステージング環境など
2. **認証が必要か** — ログインが必要な場合、ID/パスワードまたは認証手順を確認
3. **特定のインタラクション** — 「フォーム送信」「モーダル開閉」など特に記録したい動作があるか
4. **出力ファイル名** — デフォルトは `screen-specs.md`
---
## Step 2: 各画面の解析
対象URLを1つずつ処理します。各画面で以下の手順を実行してください。
### 2-1. ナビゲーション & スナップショット
---
browser_navigate(url)
browser_snapshot() <- アクセシビリティツリーを取得（UI構造の主要情報源）
browser_screenshot() <- 視覚的参照用
---
### 2-2. 構造の解析
スナップショットから以下を抽出します:
- **ページタイトル・見出し構造**
- **ナビゲーション要素**（ヘッダーメニュー、サイドバー、パンくずなど）
- **主要コンテンツエリア**（セクション、カード、テーブルなど）
- **フォームとフィールド**（ラベル、型、必須/任意、プレースホルダー）
- **ボタン・リンク・インタラクティブ要素**
### 2-3. インタラクションのテスト
以下を順に試みてください（可能な範囲で）:
- **ドロップダウン・セレクト** → 選択肢の一覧を記録
- **フォーム送信** → バリデーションメッセージ、エラー表示を記録
- **ボタン** → クリック後の状態変化（モーダル開閉、ページ遷移など）
- **トグル・タブ・アコーディオン** → 展開後のコンテンツを記録
インタラクションごとに `browser_snapshot()` を再取得して変化を確認してください。
---
## Step 3: Markdown仕様書の生成
全画面の解析が完了したら、以下のテンプレート構造に従って
1つのMarkdownファイルにまとめてください。
**重要なポイント:**
- 推測で補完せず、実際にスナップショットで確認した情報のみ記載する
- 不明な動作は「要確認」とコメントする
- フォームのバリデーションルールは実際にテストして確認する
- テーブルのデータはサンプルベースで記述し、実データは含めない
---
### 出力テンプレート
---markdown
# 画面仕様書
**生成日時:** [YYYY-MM-DD HH:mm]
**対象環境:** [URL or 環境名]
**対象画面数:** [N]
---
## 目次
- [画面一覧](#画面一覧)
- [機能一覧](#機能一覧)
- [画面フロー図](#画面フロー図)
- [画面名1](#画面名1)
- [画面名2](#画面名2)
---
## 画面一覧
| # | 画面名 | URL | 目的 |
|---|--------|-----|------|
| 1 | [画面名] | `[URL]` | [この画面の目的を1文で] |
| 2 | [画面名] | `[URL]` | [この画面の目的を1文で] |
---
## 機能一覧
各画面を横断して提供される機能をカテゴリ別にまとめます。
| # | 機能名 | カテゴリ | 説明 | 関連画面 |
|---|--------|----------|------|----------|
| 1 | [機能名] | [認証/検索/作成/編集/削除/など] | [機能の説明] | [画面名] |
---
## 画面フロー図
画面間の遷移をMermaid記法で表現します。
---mermaid
flowchart TD
A[画面名1] -->|操作| B[画面名2]
B -->|操作| C[画面名3]
B -->|キャンセル| A
---
遷移の凡例:
- 実線矢印: ユーザー操作による遷移
- 条件があれば矢印ラベルに記載
---
## [画面名]
**URL:** `[URL]`
**目的:** [この画面が何をする画面か1〜2文で説明]
---
### レイアウト構造
[画面の主要エリアをテキストで説明。例: ヘッダー / 左サイドバー + メインコンテンツ / フッター]
---
### UIコンポーネント一覧
| # | コンポーネント名 | 種別 | 説明 | 備考 |
|---|----------------|------|------|------|
| 1 | [名前] | [ボタン/リンク/テキスト/アイコンなど] | [説明] | [備考] |
---
### フォーム
<!-- フォームが存在する場合のみ記載 -->
#### [フォーム名 / フォームの目的]
| フィールド名 | 型 | 必須 | バリデーション | デフォルト値 | プレースホルダー |
|-------------|-----|------|--------------|-------------|----------------|
| [label名] | [text/email/select/checkbox/etc] | ○/- | [ルール] | [値] | [テキスト] |
**送信後の動作:** [成功時の挙動 / エラー時の挙動]
---
### インタラクション・動作仕様
| 操作 | 条件 | 結果 |
|------|------|------|
| [ボタン名]をクリック | [前提条件があれば] | [何が起きるか] |
| フォーム送信（正常系） | 全項目入力済み | [成功メッセージ / 遷移先] |
| フォーム送信（異常系） | 必須項目未入力 | [エラーメッセージ表示] |
| [モーダル名]を開く | [トリガー] | [表示内容] |
---
### ナビゲーション
| 要素 | 遷移先 | 備考 |
|------|--------|------|
| [リンク名 / ボタン名] | `[URL or 画面名]` | [条件など] |
---
### 未確認・要確認事項
- [ ] [確認できなかった項目や、動的に変わる可能性のある部分]
- [ ] [認証が必要で確認できなかった箇所など]
---
---
---
## Step 4: 出力
生成した仕様書をユーザーが指定したファイル名（デフォルト: `screen-specs.md`）に保存し、
以下を報告してください:
- 処理した画面数
- 各画面で検出したコンポーネント数
- 確認できなかった項目（認証壁、動的コンテンツなど）
③作成したスキルの呼び出し
# 作成したカスタムスキルを呼び出し /screen-spec-extractor https://×××.com/
生成された仕様書の精度
わずか数分で、8画面分の詳細な仕様書（screen-specs.md）が完成しました。
- UIコンポーネント一覧: ボタン、入力欄、ドロップダウンを網羅。
- Mermaidによる画面フロー図: 画面間の遷移をビジュアル化。
- 緻密なフォーム定義: 型、必須項目、プレースホルダー、バリデーションルールを特定。
- 未確認事項の明示: 認証が必要な箇所など「AIが確認できなかったこと」をリストアップ。
5. まとめ：AIは「自律型エージェント」へ
今回最も大きな収穫は、Agent Skillsがこんなに簡単にかつ精度高く実装できたことです。
エンジニアの仕事は「ドキュメントを書くこと」から、「AIに適切なスキルを作らせ、その成果をレビューすること」へシフトし始めています。この効率化の波、乗り遅れる手はありません。
最後に: 最後まで読んでいただきありがとうございました。この自動化プロセスが、皆さんの開発現場の革命に役立てば幸いです。
簡単30秒