生成AI関連
生成AIのSkillsとは？仕組み・MCPやカスタム指示との違い・デモまで
生成AIエージェントを業務で使い続けていると、「毎回同じ指示を書いている」と感じる場面が増えてきます。
たとえば、コーディング手順、コードレビューの観点、ドキュメントの表記ルール、社内テンプレートに沿った報告書作成などは、毎回プロンプトに貼り付けるよりも、再利用できる形でエージェントに渡したくなります。
このような場面で有効なのがSkillsです。Skillsの基本的な考え方については、以前の記事で整理しています。
また、SkillにPythonスクリプトを同梱する際の依存関係管理については、PEP 723を使った実装例を紹介しました。
本記事では、その続編として、コーディングエージェント向けのSkillsを作成する流れを紹介します。対象は、Codex CLI、Gemini CLI、Claude Codeのようなローカル開発環境で利用するコーディングエージェントです。
なお、本記事の内容は2026年5月26日現在の情報に基づいています。各エージェントのSkills対応状況や配置先は今後変更される可能性があるため、最新情報は各公式ドキュメントもあわせて確認してください。
前半では、Agent Skills形式の基本構造と作成時の考え方を整理します。そのうえで、後半のデモではCodexを使い、Markdown記事をレビューする blog-reviewer Skillを作成します。
Agent Skillsは、エージェントに特定の作業手順や専門知識を追加するための仕組みです。Agent Skillsの仕様では、Skillは少なくとも SKILL.md を含むディレクトリとして定義されています（Agent Skills「Specification」）。
代表的な構成は次のとおりです。
skill-name/
├── SKILL.md # 必須: メタデータと指示
├── scripts/ # 任意: 実行可能なコード
├── references/ # 任意: ドキュメント
├── assets/ # 任意: テンプレートやリソース
└── ... # その他のファイルやディレクトリ
必須なのは SKILL.md です。references/、scripts/、assets/ は任意ですが、実務で使うSkillではこれらを分けておくと保守しやすくなります。
| ディレクトリ | 役割 |
|---|---|
| SKILL.md | Skillのメタデータと、エージェントが従う基本手順を書く |
| references/ | スタイルガイド、API仕様、業務ルールなど、必要なときに読ませる資料を置く |
| scripts/ | 機械的に実行したい検査や変換処理を置く |
| assets/ | テンプレート、サンプル、出力例などを置く |
Skillsの重要な特徴は、段階的に読み込まれることです。Agent Skillsの仕様では、起動時に読み込まれるのは主に name と description であり、SKILL.md 本文や関連ファイルは必要になったときに読み込まれる設計として説明されています（Agent Skills「Specification」）。
このため、SKILL.md には毎回必要な判断基準と手順を置き、詳細なルールや長い参考資料は references/ に分離するのが基本方針です。
Skillsは手書きでも作成できますが、各コーディングエージェントには、Skills作成を支援するための Skill Creator が用意されています。
Skill Creatorは、新しいSkillのひな形を作るためのSkillです。作りたいSkillの目的、利用場面、出力形式、必要なスクリプトや参照資料を整理し、SKILL.md や関連ディレクトリの作成を支援します。
Skill Creatorは、Skillの新規作成だけでなく、既存Skillの改善や検証にも利用できます。実務で安定して使うためには、発動条件、業務固有のルール、出力形式、検証方法を調整しながら改善していくことが重要です。
利用方法はエージェントによって異なります。
| エージェント | Skill Creatorの使い方 | 補足 |
|---|---|---|
| Codex CLI | デフォルトで利用できます | Skillを作成したいことを依頼すると、Skill Creatorの手順に沿って作成を進められます |
| Gemini CLI | デフォルトで利用できます | Skill作成を依頼すると、組み込みの skill-creator によって作成が進められます |
| Claude Code | /plugin コマンドでSkill Creatorプラグインをインストールして利用します | インストール後、Skillの作成や改善を依頼できます |
各エージェントでの詳細な利用方法は、OpenAI Help CenterのSkills in ChatGPT、Gemini CLIのCreating Agent Skills、AnthropicのSkill Creatorを参照してください。
Skill Creatorを使う場合でも、最初から完成度の高いSkillができるとは限りません。対象範囲や発動条件が曖昧なままだと、期待した場面で呼び出されなかったり、関係のない場面で呼び出されたりすることがあります。Skillが適切に呼び出された場合でも、手順や参照ファイルの内容が業務の実態と合っていなければ、想定どおりの出力が得られないこともあります。
ここで陥りがちなのが、Skillを「完成させること」自体が目的になってしまうことです。SKILL.md の表現を磨き、references/ の分け方を整え、scripts/ を作り込む作業はそれ自体に達成感があります。ただ、それがエージェントの挙動に本当に効いているかは、実際に動かしてみるまで分かりません。動かす前の磨き込みは、評価関数のない最適化になりがちです。
そのため、実際は次のループを回すのが現実的だと考えています。
2の段階では、SKILL.md の表現や手順、references/ の構成まで踏み込んで修正したくなりますが、先に動作を確認するほうが、改善の根拠が実体験に基づくものとなり、的を外しにくくなります。一方で、危険な処理（外部通信、ファイル削除、認証情報の参照など）は事後では取り返しがつかないため、この観点は必ず実行前に確認します。
なお、Agent Skillsの説明最適化ガイドでは、description はエージェントがSkillを読み込むかどうかを判断する主要な仕組みであり、過度に曖昧でも広すぎても問題になると説明されています（Agent Skills「Optimizing skill descriptions」）。description の書き方は確かに重要ですが、最初から完璧に書くのは難しいため、これも「使ってみて発動しなかったら直す」のループに乗せるのが現実的です。
なお、ユーザーがSkill名を明示して依頼する場合は、エージェントが自動判定する必要がないため、description の重要度は下がります。description が特に効いてくるのは、通常の依頼文からエージェントに適切なSkillを選ばせたい場合です。
ここからは、Codexを使ったデモです。前章で整理した「作成 → 確認 → 実行 → 反映」のループを実践してみます。
今回作成するのは、Markdownで記載したブログ記事を公開前にレビューする blog-reviewer Skillです。レビュー観点は次のようにします。
| 観点 | 内容 |
|---|---|
| 構成 | はじめに、本文、まとめ、サービス紹介の流れになっているか |
| 文体 | 企業ブログとして適切な敬体になっているか |
| 表記 | 禁止したい口語表現や過度な強調がないか |
| 技術説明 | 事実と推測が混ざっていないか |
| Markdown | 見出し、コードブロック、内部リンク、画像パスが崩れていないか |
Codexには、作成するSkill名だけでなく、対象、確認観点、配置先、同梱するファイルまで明示して依頼します。なるべく具体的に記載したほうが、意図したSkillが作成されやすいです。
blog-reviewer というSkillを作成してください。
目的:
Markdownで書かれた技術ブログ記事を、公開前レビューするためのSkillです。
対象:
生成AIや開発に関する企業ブログ記事です。
確認したい観点:
記事構成、敬体、口語表現、技術説明の正確性、Markdown記法、内部リンク、画像パスです。
構成:
SKILL.md、references/style-guide.md、scripts/check_markdown.py を含めてください。
なお、スクリプトで必要なライブラリは、PEP 723形式のインラインメタデータ形式で記載し、実行コマンドは `uv run --script scripts/xx.py` として下さい。
配置先:
.codex/skills/blog-reviewer/ に作成してください。
Codexが生成したSkillは、次のような構成になりました。
.codex/skills/blog-reviewer/
├── SKILL.md
├── references/
│ └── style-guide.md
└── scripts/
└── check_markdown.py
SKILL.md の中身は次のとおりです。
この段階で行うのは、細部の作り込みではなく、次の2点の確認です。
今回の生成結果では、description に対象範囲（生成AIや開発に関する技術ブログ記事）と確認観点（構成、敬体、口語表現、技術説明、Markdown、内部リンク、画像パス）が記載されており、依頼内容と概ね一致していました。scripts/check_markdown.py は見出し階層、コードフェンス、内部リンク、画像パス、口語表現の機械チェックのみを行っており、レビュー対象ファイルの読み込み以外には、ファイルの書き込みや削除、外部通信は含まれていませんでした。
なお、SKILL.md の本文や references/style-guide.md の内容は、今回はブログ掲載用に日本語で生成しています。Skill Creatorに作成を依頼した場合、デフォルトでは英語で生成される傾向がありますが、日本語で記述しても多くの場面で問題なく利用できます。チームの運用や対象読者に合わせて、いずれかの言語に統一して記述してください。
また、本文ではレビュー手順を短く保ち、詳細な表記ルールは references/style-guide.md に分けています。Agent Skillsのベストプラクティスでも、SKILL.md に何でも詰め込むのではなく、詳細な資料は参照ファイルに分け、必要なときに読ませる設計が推奨されています（Agent Skills「Best practices for skill creators」）。
Skillを配置したら、実際の記事に対してレビューを依頼します。
blog/posts/sample-agent-article.md を公開前レビューしてください。
レビュー観点や手順は SKILL.md と references/style-guide.md に書かれているため、依頼側で毎回明示する必要はありません。description が機能していれば、Codexは依頼内容から blog-reviewer Skillを読み込み、SKILL.md の手順に従って references/style-guide.md を参照し、scripts/check_markdown.py を実行したうえでレビュー結果を返します。
出力は、たとえば次のようになります。
## 指摘事項
- High: blog/posts/sample-agent-article.md:191 - 画像参照先が存在しません。
- Low: blog/posts/sample-agent-article.md:36 / blog/posts/sample-agent-article.md:113 / blog/posts/sample-agent-article.md:157 -
コードフェンスの言語指定が Inline script metadata、show_excel.py、SKILL.md になっています。シンタックスハイライトとMarkdown処理系の互換性を考えると、順に
python、python、markdown などにするのが無難です。
## 確認結果
- Markdownチェッカー: failed
画像パス不備が1件、160文字超過の警告が複数、敬体・常体混在の警告が1件出ています。敬体混在はコードブロックや引用も含んだ機械判定の可能性が高く、本文全体は概ね
です・ます 調で統一されています。
- 技術情報の確認元:
PEP 723はFinalで、現在の正規仕様はPyPAのInline script metadata仕様です。uv run がインライン依存を読み取り環境を作る説明、pipxのPEP 723対応、Agent SkillsのSelf-
contained scripts説明は確認できました。
参照: PEP 723 (https://peps.python.org/pep-0723/), PyPA Inline script metadata (https://packaging.python.org/en/latest/specifications/inline-script-metadata/),
uv Running scripts (https://docs.astral.sh/uv/guides/scripts/), pipx Run Scripts (https://pipx.pypa.io/stable/how-to/run-scripts/), Using scripts in skills
(https://agentskills.io/skill-creation/using-scripts), openpyxl PyPI (https://pypi.org/project/openpyxl/)
Skillを作成してレビューを実行した後も、人間によるレビュー結果の確認は欠かせません。観点に入っていない不足や、Skillが返した指摘自体の誤りが残ることもあるためです。
今回のレビュー結果を人間が確認したところ、Tech Funのブログ固有のルールである「記事末尾に『生成AI活用支援サービスのご紹介』セクションを必ず含める」が確認対象に入っておらず、当該セクションの有無がチェックされていないことに気づいたと仮定します。これは、最初の依頼でTech Funのブログ固有のルールを伝えていなかったことが原因です。
本来はテンプレートとの内容一致まで確認したいところですが、今回は簡易的に ## 生成AI活用支援サービスのご紹介 という見出しの章が末尾に存在するかどうかだけを確認対象としました。
完成度の高い初稿を最初から目指すよりも、不足している観点が実際のレビュー結果から具体的に明らかになった段階で追加するほうが、必要な内容を的確に整理できます。Codexに次のように依頼し、Skillを更新します。
blog-reviewer Skillを更新してください。
追加したい観点:
- 記事の末尾に `## 生成AI活用支援サービスのご紹介` の見出しを持つ章が存在するか
更新後は、references/style-guide.md の記事構成セクションに該当見出しのルールが記載された状態になります。次回以降の実行では、支援サービス紹介セクションの欠落が指摘されるようになります。
このように、ループを一周実施するだけでも、初稿の段階では曖昧だった業務ルールが具体的なかたちでSkillに蓄積されていきます。最初から完成度を求めず、ループを前提として初稿を作成するほうが、結果的に実態に合ったSkillを構築しやすくなります。
この状態で実行すると、「指摘事項」箇所に「## 生成AI活用支援サービスのご紹介」の章がない指摘が追加されました。
## 指摘事項
- High: blog/posts/sample-agent-article.md:191 - 画像参照先が存在しません。
- High: blog/posts/sample-agent-article.md:248 - スタイルガイドで必須の ## 生成AI活用支援サービスのご紹介 章がありません。公開テンプレート要件なら末尾に追加が必要です。
- ...（略）
今回のデモはCodexを前提に進めましたが、SkillsはCodexだけの仕組みではありません。Agent Skills形式は複数のコーディングエージェントで利用可能で、同じSkillを複数のエージェントから使いたい場面が出てきます。
ただし、Skillの読み込み先はエージェントごとに異なります。本記事執筆時点での代表的な配置先は次のとおりです。
| エージェント | 配置先 | 参考ドキュメント |
|---|---|---|
| Codex CLI | .agents/skills/<skill-name>/ または .codex/skills/<skill-name>/ | OpenAI Developers「Agent Skills」 |
| Gemini CLI | .gemini/skills/<skill-name>/ または .agents/skills/<skill-name>/ | Gemini CLI「Agent Skills」 |
| Claude Code | .claude/skills/<skill-name>/ | Claude Code「Extend Claude with skills」 |
※ Codex CLIについては、公式ドキュメント上では .agents/skills/ が明示されています。一方で、.codex/skills/ も本記事執筆時点の動作確認では利用できるため、ここでは実運用上の選択肢として併記しています。
同じSkillを複数のエージェントで共有するには、主に次の2つの方法があります。
最も単純なのは、Skillディレクトリを各エージェントの配置先にコピーする方法です。
cp -r .codex/skills/blog-reviewer .gemini/skills/
cp -r .codex/skills/blog-reviewer .claude/skills/
エージェントごとにファイルが独立するため、特定エージェント向けに微調整を入れたい場合は扱いやすくなります。一方で、Skillを更新するたびに各コピー先へ反映する必要があり、ファイル間の差分管理が必要になります。
実体を1箇所に置き、各エージェントの配置先からシンボリックリンクを貼る方法です。本記事では Codex CLI 用に作成した .codex/skills/blog-reviewer を実体とし、他のエージェントの配置先からリンクを貼ります。リポジトリルートで次のコマンドを実行します。
mkdir -p .gemini/skills .claude/skills
ln -s ../../.codex/skills/blog-reviewer .gemini/skills/blog-reviewer
ln -s ../../.codex/skills/blog-reviewer .claude/skills/blog-reviewer
実体が1つしかないため、Skillを更新すると各エージェントから自動的に最新版が読み込まれる状態になり、保守しやすくなります。
Skillは、エージェントに新しい作業手順を渡す仕組みです。そのため、通常のドキュメントよりも実行時の影響を意識する必要があります。
特に注意したいのは、外部から取得したSkillの扱いです。AnthropicのAgent Skillsドキュメントでは、Skillには指示やコードが含まれるため、信頼できないSkillを使う場合は内容を確認し、データ漏えいや意図しないツール実行のリスクに注意する必要があると説明されています（Claude Docs「Agent Skills」）。
自作Skillであっても、次の点は確認しておくと運用しやすくなります。
| 観点 | 確認内容 |
|---|---|
| 発動条件 | description が広すぎず、狭すぎないか |
| 手順 | 毎回必要な作業だけが SKILL.md に書かれているか |
| 参照資料 | 長いルールが references/ に分離されているか |
| スクリプト | 引数、終了コード、エラーメッセージが明確か |
| 権限 | ファイル削除、外部通信、認証情報参照などの危険な処理が含まれていないか |
| 更新 | 実行結果を見て、指示や参照資料を改善する運用になっているか |
Skillは一度作って終わりではありません。実際の依頼で使い、エージェントが迷った箇所や期待と違う出力をした箇所を、SKILL.md や references/ に反映していくことで品質が安定します。
本記事では、コーディングエージェント向けSkillsを作成する流れを紹介し、デモとしてCodexでブログレビュー用Skillを作成しました。
今回のポイントは次のとおりです。
Skillsは、単なるプロンプトの保存場所ではなく、チームの作業手順をエージェントが再利用できる形にするための単位です。コーディング、レビュー、ドキュメント作成など、繰り返し発生する業務から小さくSkill化していくと、コーディングエージェントの活用範囲を広げやすくなります。
Tech Funでは、お客様のフェーズに合わせ、生成AI活用に向けた支援を3つのパックでご提供しています。
生成AIに限らず、Web・業務システム開発やインフラ設計など、技術領域を問わずご相談を承っています。「何から始めれば良いか分からない」という段階でも構いませんので、ぜひお気軽にお問い合わせください。
