WEBアプリにAgent Skillsを組み込んだら、爆速で機能拡張できた話

Last updated at 2026-02-10Posted at 2026-02-10

はじめに

Claude Code の「スキル」機能をご存知でしょうか？

PDF をスライドに変換する、Excel レポートを生成する、コードレビューを自動化する──こうした専門タスクを、Markdown ファイルを1つ追加するだけで LLM にこなせるようにする仕組みです。

そしていま、このスキルのエコシステムは急速に拡大しています。Anthropic 公式のスキルに加え、コミュニティが作成したスキルがマーケットプレイスに16万件以上公開されており、2025年12月には Agent Skills の仕様がオープン標準として公開され、OpenAI の Codex CLI や ChatGPT でも同じフォーマットが採用されました。

これだけ多くのスキルが揃っているなら、自分の Web アプリにも同じ仕組みを組み込めたら、どれだけ楽に機能拡張できるだろう？ 実際にサンプルアプリ（Skill Agent Chat）を作ってみました。

結果、新しい AI 機能を追加するのにコードの変更が一切不要になりました。Markdown で指示書を書いてフォルダに置くだけ。エンジニアでなくてもスキルを作れるという状態が実現できたのです。

この記事では、スキルの仕組みを概念レベルで分解し、自分の LLM アプリにどう活かせるかをコードを書かずにわかりやすく解説します。

こんな方におすすめ:

LLM を使ったアプリの設計に興味がある方
Claude Code のスキル機能の裏側を理解したい方
技術的な詳細よりも「考え方」を知りたい方

コード付きの詳細な実装ガイドは、別記事「WEBアプリにAgent Skillsを組み込んだら、爆速で機能拡張できた話【実装編】」をご覧ください。

スキルの正体 ── たった3つの要素でできている

スキルは、特別な技術ではありません。3つのシンプルな要素の組み合わせです。

1. 指示書（SKILL.md）

スキルの「頭脳」にあたる部分です。

LLM に対して「あなたは今からこの専門家として振る舞ってください」という業務マニュアルを渡すイメージです。Markdown で書かれたテキストファイルで、以下のような内容が含まれます。

このタスクをどんな手順で進めるか
出力するファイルのフォーマットやデザイン方針
エラーが起きたときの対処方針
品質基準やスタイルガイド

たとえば「PDF をスライドに変換するスキル」の指示書には、「各ページの画像を分析して、忠実に HTML/CSS で再現すること」「レイアウトパターンは15種類から最適なものを選ぶこと」といった具体的な指示が書かれています。

ポイント: この指示書の品質がスキルの品質を決めます。曖昧な指示だと汎用的な回答しか得られませんが、具体的で詳細な指示を書けば、専門家レベルの出力が得られます。

2. ツール（補助スクリプト）

LLM は「考える」ことは得意ですが、実際に手を動かすことはできません。ファイルの読み書き、PDF の変換、データベースへのアクセスなどは、外部のプログラムに任せる必要があります。

この「LLM の手足」となるのがツールです。

LLM は「今、PDF を画像に変換したい」と判断すると、ツールの呼び出しをリクエストします。実際の変換処理はアプリ側のプログラムが行い、その結果を LLM に返します。

3. リファレンス資料

デザインパターンやテンプレート、コーディング規約など、LLM が参照する補助的な知識です。

LLM は膨大な一般知識を持っていますが、「あなたの会社のスタイルガイド」や「このプロジェクト固有のルール」は知りません。リファレンス資料を提供することで、LLM はプロジェクト固有のルールに従った出力を生成できるようになります。

3つの要素を LLM アプリに組み込むには？

Claude Code のスキル要素を、一般的な LLM アプリ（Azure OpenAI、OpenAI API、Azure Anthropic など）で再現するには、以下のように対応させます。

スキルの要素	LLM アプリでの実現方法
指示書（SKILL.md）	システムメッセージとして LLM に渡す
ツール（補助スクリプト）	Function Calling で LLM から呼び出せるようにする
リファレンス資料	システムメッセージに含める、または検索（RAG）で動的に取得

加えて、もう一つ重要な仕組みがあります。それが エージェントループ です。

エージェントループ ── スキルの「心臓部」

普通の LLM 呼び出しとの違い

通常の LLM 利用は「1回の質問 → 1回の回答」で終わります。ChatGPT に質問して回答をもらう、あの流れです。

しかし、スキルが行うような複雑なタスクは 1回のやり取りでは完了しません。

たとえば「PDF をスライドに変換して」というタスクを分解すると：

PDF を画像に変換する（ツール呼び出し）
画像の一覧を確認する（ツール呼び出し）
各画像を見て HTML を生成する（Vision + ツール呼び出し）
全スライドをまとめて最終確認する
ユーザーに完了を報告する

この「考える → 行動する → 結果を見る → また考える」のサイクルを繰り返す仕組みが エージェントループ です。

エージェントループの流れ

ポイント: LLM が「もうツールを呼ぶ必要はない」と判断したら、ループは自然に終了します。LLM 自身がタスクの完了を判断するのです。

会話履歴が「作業メモリ」になる

エージェントループでは、LLM の応答もツールの実行結果もすべて会話履歴に蓄積されます。

これが LLM にとっての「作業メモリ」の役割を果たし、「さっき PDF を変換したから、次はその画像を見て HTML を作ろう」という文脈を踏まえた判断が可能になります。

安全弁の設定

エージェントループには必ず繰り返し回数の上限を設けます。LLM が無限にツールを呼び続けるバグを防ぐためです。タスクの複雑さに応じて 10〜30 回程度が目安です。

スキルのディレクトリ構成 ── 整理のコツ

スキル対応のアプリを作るとき、ファイルをどう整理するかも大切です。推奨する構成はこちらです。

my-agent-app/
├── src/           → アプリ本体（エージェントループ、ツール定義など）
├── skills/        → スキル定義ファイル（.md）
├── tools/         → 補助スクリプト
└── references/    → リファレンス資料

なぜスキル定義を分けるのか

スキル定義（.md ファイル）をアプリのコードと分離しておくと、こんなメリットがあります。

コード変更なしでスキルを追加・改善できる ── Markdown ファイルを編集するだけ
エンジニアでなくてもスキルを作れる ── Markdown が書ける人なら誰でもスキル定義を作成可能
バージョン管理しやすい ── Git でプロンプトの改善履歴を追跡できる
テストしやすい ── 同じアプリコードに異なるスキルを差し替えて検証できる

OpenAI と Anthropic ── API は違っても設計は同じ

スキル機能を実装する際、Azure OpenAI（GPT 系）と Azure Anthropic（Claude 系）のどちらを使うかで API の書き方は異なります。しかし、設計パターンは完全に同じです。

主な違いの早見表

概念	OpenAI（GPT）	Anthropic（Claude）
指示書の渡し方	会話履歴の中に `system` ロールで含める	`system` パラメータとして別途渡す
ツール定義のキー名	`parameters`	`input_schema`
ツール結果の返し方	`tool` ロールで返す	`user` ロール + `tool_result` で返す
完了の判定	ツール呼び出しが無い	`stop_reason` が `end_turn`

違いはあくまで「API のお作法」の違いであり、スキルの設計思想（指示書 + ツール + エージェントループ）はプロバイダーに依存しません。

複数スキルの切り替え ── 万能アシスタントへの道

実用的なエージェントでは、1つのアプリが複数のスキルを持ち、ユーザーの依頼に応じて適切なスキルを自動選択するケースがあります。

これを実現するのが「スキルルーター」という仕組みです。

スキルルーター自体も LLM に判断させることができます。「この依頼にはどのスキルが最適？」と聞くだけです。

実践ユースケース集

スキル機能を使えば、さまざまな専門エージェントを構築できます。

PDF → スライド変換エージェント

PDF の各ページを画像に変換し、LLM の Vision 機能で画像を読み取って HTML スライドを生成します。デザインパターンのリファレンス資料を参照することで、プロ品質のスライドが自動生成されます。

ドキュメント自動生成エージェント

ソースコードを読み取り、API ドキュメントを自動生成します。コードの変更に追従して常に最新のドキュメントが維持されるため、ドキュメントの陳腐化を防げます。

データ分析レポート生成エージェント

CSV データを読み込み、統計分析とグラフ生成を行い、整形されたレポートを自動出力します。非エンジニアでも「この CSV を分析して」と依頼するだけで使えます。

コードレビュー支援エージェント

Git の差分を読み取り、セキュリティ・パフォーマンス・可読性の観点からレビューコメントを自動生成します。PR が作成された時点で一次レビューが自動実行され、レビュアーの負担を軽減します。

社内ナレッジ検索＆回答エージェント

社内ドキュメントをベクトル検索（RAG）で検索し、出典付きで質問に回答します。新入社員のオンボーディングや FAQ 対応を効率化できます。

本番運用で気をつけること

トークン制限に注意

スキルの指示書が長すぎると、それだけで大量のトークンを消費します。指示書は必要最小限に絞るか、長いリファレンス資料は RAG（検索拡張生成）で必要な部分だけ取得する工夫が必要です。

コスト管理

エージェントループは、1回のユーザーリクエストに対して複数回の API 呼び出しが発生します。

1回のタスクのコスト = ループ回数 × (入力トークン + 出力トークン)

繰り返し回数の上限設定、トークン使用量のログ記録、コスト上限の設定などで管理しましょう。

エラーハンドリング

ツールの実行が失敗した場合、エラー情報を LLM にそのまま返すのが効果的です。LLM はエラー内容を読んで、リトライや代替手段を自律的に判断できます。

セキュリティ

LLM がツールを通じてファイル操作やコマンド実行を行うため、以下の対策が重要です。

サンドボックス化 ── ツールがアクセスできる範囲を制限する
入力バリデーション ── LLM が生成した引数（ファイルパスなど）を検証する
実行前確認 ── 破壊的な操作はユーザーの承認を得てから実行する

フレームワーク	特徴	おすすめの場面
LangChain	最も広く使われる LLM フレームワーク	汎用的な LLM アプリ全般
Semantic Kernel	Microsoft 公式。Azure との統合が手厚い	企業向け・Azure ベースのアプリ
Vercel AI SDK	Next.js/React との統合に優れる	Web アプリへの組み込み
Mastra	TypeScript ファーストで型安全	型安全を重視した開発
AutoGen	マルチエージェント構成に強い	複数エージェントの協調

デモアプリ：Skill Agent Chat

この記事で解説してきたスキル機能の考え方を、実際に動作する Web チャットアプリとしてまとめました。

GitHub: https://github.com/nogataka/skill-agent-chat

どんなアプリ？

サイドバーからスキルを切り替えながら LLM と会話できるチャットアプリです。この記事で紹介した 指示書（SKILL.md）→ システムプロンプト注入、ツール → Function Calling、エージェントループ の3つの設計パターンがすべて組み込まれています。

主な特徴:

スキル切替 — サイドバーからスキルを選ぶだけで、AI の振る舞いが切り替わる
ツール呼び出し — テキスト分析、Web 検索（デモ）、日時取得などのツールを AI が自動で使用
エージェントループ — 最大10ステップまで「思考 → ツール実行 → 結果確認」を自動で繰り返す
HTMLライブプレビュー — AI が生成した HTML コードをサイドパネルで即座にプレビュー表示
会話履歴の永続化 — SQLite に会話を自動保存。ページをリロードしても復元可能
マルチプロバイダー — OpenAI / Azure OpenAI / Azure Anthropic（Claude）を環境変数で切替

プリセットスキルの紹介

アプリには3つのプリセットスキルが付属しており、スキルの効果をすぐに体験できます。

スキル	何ができるか
デフォルトアシスタント	汎用的な質問応答・タスク支援。テキスト分析・Web検索・日時取得のツールを自動活用
frontend-design	プロダクション品質の HTML/CSS/JS を生成。「ありがちな AI デザイン」を避け、タイポグラフィ・配色・モーションにこだわった独創的な UI を設計。生成した HTML はサイドパネルでライブプレビュー確認可能
文章校正・要約	日本語テキストの校正・要約・改善提案。まず `analyzeText` ツールで文字数・段落数を自動計測し、その結果を踏まえて修正案を提示

ポイントは、これらのスキルがすべて Markdown ファイル1つで定義されているということです。frontend-design のような高度なスキルも、その中身はプロンプト（指示書）でしかありません。

記事の内容とアプリの対応

記事で解説した概念	アプリでの実現箇所
指示書（SKILL.md）	`skills/` ディレクトリの Markdown ファイル → システムプロンプトとして注入
ツール（Function Calling）	`src/lib/tools.ts` に3つのデモツールを定義
エージェントループ	チャット API でループ上限付きの自動ステップ実行
プロバイダー切替	`src/lib/providers.ts` で環境変数に応じた LLM 切替
スキルの分離管理	`skills/` ディレクトリにファイルを置くだけで追加可能（コード変更不要）

動かし方

git clone https://github.com/nogataka/skill-agent-chat.git
cd skill-agent-chat
npm install
cp .env.example .env.local
# .env.local を編集してAPIキーを設定
npm run dev

ブラウザで http://localhost:3000 を開くと、すぐに試せます。

スキルの追加は Markdown を書くだけ

skills/ ディレクトリに Markdown ファイルを追加するだけで、新しいスキルがサイドバーに表示されます。コードの変更は一切不要です。これが「スキル定義をコードと分離する」設計の実践例です。

詳しい実装解説やコードの全体像は、詳細版の記事をご覧ください。

まとめ

スキル機能を自分の LLM アプリに組み込むには、3つの要素 + 1つの仕組みを理解すれば十分です。

要素	役割	たとえるなら
指示書（SKILL.md）	LLM に専門知識を与える	業務マニュアル
ツール	LLM に実行能力を与える	手足
リファレンス資料	LLM にプロジェクト固有の知識を与える	参考書
エージェントループ	LLM に自律的に動く能力を与える	思考→行動→観察のサイクル

スキルの本質は、「LLM に対して、特定の専門領域で高品質な成果を出すための知識・道具・行動パターンを一式提供する仕組み」 です。

この設計パターンは、Azure OpenAI でも Azure Anthropic でも OpenAI でも、あるいは他の LLM API でも同じです。API の書き方は違っても、スキルの考え方はプロバイダーに依存しません。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up