Skill は新しいプロンプトではなく、エージェントに職種マニュアルを提供するものです。

Skill とは一体何なのか

最も分かりやすい言葉で説明するなら、こう言います。ベテラン社員の頭の中にある熟練したやり方を、再利用可能で、トリガーでき、実際に実行できるマニュアルとしてまとめたものが Skill です。

OpenAI の公式ドキュメントの定義も非常に直接的です。Skill は特定のタスクに向けた能力パッケージの一種であり、指示（プロンプト）、参考資料、そしてオプションのスクリプトを格納できます。目的はモデルを「より賢くする」ことではなく、ある種のタスクにおいて固定されたワークフローに従って安定的に出力をさせることです。

何に最も近いか？

通常のプロンプトとは異なり、一度話して終わりではないからです。
MCP とも異なります。なぜなら、ツールやデータソースを接続する責任を持たないからです。
また、AGENTS.md のようなものでもないからです。全リポジトリで通用するルールではないからです。

むしろ、専門の SOP（標準作業手順書）や、職種マニュアルのようなものです。

例えば：

GitHub PR のコメントを処理する場合：まずどのコメントを処理すべきかを確認し、次にユーザーにどのコメントを処理するか尋ね、コードを修正し、最後に結果をフィードバックする。
CI の失敗を調査する場合：まず GitHub Actions のログを取得し、次に失敗した部分を抽出して要約し、修復計画を立て、承認されてから作業に取り掛かる。
ブログ記事を書く場合：まず固定の文体でタイトルを生成し、次に事実情報を補完し、さらにフロントマター（メタデータ）を追加し、最後に公開する。

これらの事柄に共通しているのは、「モデルがどう回答すべきか知らない」ということではなく、「モデルのやり方が毎回異なり、逸脱しやすい」という点です。ここで Skill の価値が出てくるのです。

Skill と MCP、結局どこが違うのか

これは実際のワークフローに当てはめて見ないと分かりにくいので、単なる説明だけでは誤解を招きやすいです。

MCP はインターフェース層のようなものです。

公式における MCP の定義は、「AI アプリケーションを外部システムに接続するためのオープンスタンダード」です。ファイル、ローカルデータベース、検索エンジン、デザイン稿、サードパーティサービスなど、これらすべてを MCP を通じて取り込むことができます。つまり、これが解決しているのは「取り込み（コネクション）」の部分です。

一方、Skill はプロセス層のようなものです。

OpenAI の Agent Skills ドキュメントには明確に書かれていますが、Skill は再利用可能なワークフローを記述するためのフォーマットです。一つの Skill には最低限 SKILL.md が必要で、さらに scripts/、references/、assets/ を含めることができます。Codex はまずその name と description を読み込み、実際に使用する必要があると判断した場合にのみ、完全な説明をコンテキストにロードします。これが公式が言う「プログレッシブ・ディスクロージャー（段階的開示）」です。

したがって、両者の役割分担は非常に明確です。

MCP: 能力を取り込む（コネクションする）
Skill: 行う手順の順序を定める

非常に分かりやすい例で言うと、「Figma からコードへの変換」のような作業です。もしエージェントがデザイン稿自体を読み取れていない場合、まず補うべきなのは MCP です。しかし、すでにデザイン稿を読み取れるようになったのに、毎回バラバラにコーディングしてしまう（今日はコンポーネントから書き始め、明日はページ分割から始め、明後日にはビジュアルチェックを忘れる）という状況であれば、補うべきは Skill なのです。

スキルの開発方法

これは思ったほど重くありません。 OpenAIの公式推奨では、まず組み込みの$skill-creatorを使用し、トリガー条件、範囲、スクリプトが必要かどうかといった骨格部分を構築してもらうことです。デフォルトではinstruction-only（指示のみ）が優先されるため、焦ってスクリプトを書くのではなく、まずは説明を明確にすることが重要です。手動で記述する場合でも、最小限の構造は非常にシンプルです：

my-skill/
├── SKILL.md
├── scripts/
├── references/
└── assets/

この中で真に必要なのはSKILL.mdだけです。そして、このファイルには最低限2つのメタデータが必要です：

---
name: skill-name
description: Explain exactly when this skill should and should not trigger.
---

私が考えるに、Skillを開発する上で最も重要なのは以下のステップです。

1. 「繰り返し現れるバイアス」を探す

すべてのタスクが Skill にする価値があるわけではありません。エージェントに単発で作業をさせるだけであれば、通常のプロンプトで十分です。真に Skill として抽出するのに適しているのは、通常以下のようなケースです：

同じことを何度も繰り返して指示している場合
エージェントには能力があるはずなのに、実行順序がいつも変わってしまう場合
間違いが発生する箇所が毎回似ている場合つまり、「能力不足」なのではなく、「手順（ノウハウ）が安定していない」ということです。

2. `description` をトリガー条件として記述し、宣伝文句にしないこと

このステップは非常に重要です。公式ドキュメントでは、Codex がどの Skill を暗黙的に呼び出すかについて、description に大きく依存すると強調しています。「これはとても便利なスキルだ」といった表現ではなく、「いつ使うべきか、いつ使ってはいけないか」を記述してください。例えば、gh-fix-ci の公式スキルの説明は非常に明確です：「ユーザーが GitHub PR チェックの失敗をデバッグまたは修正してほしい場合に使用する」というものです。重要なのは、ログを確認し、失敗の原因を要約し、修正計画を提示することであり、そして明示的な承認を得てから実行することです。これを見るだけで、その境界線がどこにあるかがわかります。

3. 説明で対応できるなら、まずスクリプト化しない

OpenAIのドキュメントでも非常に実用的なアドバイスをしています。明確な決定論的動作や外部ツールが必要でない限りは、いきなりスクリプトにするのではなく、まずは説明（プロンプト）を使うべきです。なぜか？スクリプトが増えれば増えるほど、メンテナンスコストが上がってくるからです。多くのSkillは、最初は単に手順を明確に説明するだけで十分です：

何から始めるか
次に何をするか
出力形式はどうするか
どのような状況でユーザーに確認を求めるべきかこれだけでも大半の問題は解決します。あるステップが非常に安定していて、非常に機械的で、自動化に適している場合にのみ、scripts/に落とし込むようにしましょう。

4. 資料、テンプレート、リソースを分離する

Skill は書き進めるうちに、非常に長い説明文になりがちです。そんな時は分割すべきです。

SKILL.md はルールと手順を担当する
references/ には背景ドキュメントや参照資料を置く
assets/ にはテンプレート、アイコン、サンプルを置く
scripts/ には安定して実行できるアクションを置くこのようにすることで、2つの利点があります。第一に、メインファイルが肥大化しすぎるのを防げます。第二に、モデルが必要なときだけ詳細を読み込む形になり、「プログレッシブ・ディスクロージャー（段階的開示）」という考え方に沿えます。

5. ローカルで先に使い、プロジェクトをまたいで配布する

公式ドキュメントでもこの点は明確に分けられています。もしご自身の現在のリポジトリでのみ使用するのであれば、.agents/skills/ に配置するだけで十分です。Codex はリポジトリ、ユーザー、システムなどの場所からスキルディレクトリをスキャンします。しかし、この仕組みが単一のリポジトリだけでなく複数の場所で使えることに気づいた場合や、複数のスキルをまとめてパッケージ化して配布したい場合は、skill folderの層に留まらず、plugin を検討すべきです。OpenAI公式ドキュメントの記述も非常に明確で、Skill はワークフローそのものであり、真にインストールおよび配布に適した単位は plugin です。

スキルが適しているシナリオ

Skill は多ければ良いというものではなく、以下の種類のタスクに最も適しています。

高頻度で繰り返すタスク

毎週行う、そして毎回手順がほぼ同じもの。例えば：

PRレビューコメントの処理
ブログ記事の執筆とフロントマターの追記
CI失敗の調査
リリース前のチェックこのような作業は、モデルができないことよりも、毎回説明し直さなければならないことが一番面倒です。

固定フローのタスク

ある事柄には、生まれながらにして順序があるものがあります。例えば問題の調査をする場合、まずログを確認し、次に範囲を絞り込み、それから計画を立て、そして修正するという流れになります。このような場面では、Skill が特に適しています。なぜなら、順番を固定できるため、モデルがその場しのぎで対応するのを減らせるからです。

専門的な文脈に紐づける必要があるタスク

手順が固定されているだけでなく、強い制約を伴うタスクもあります。例えば：

公式ドキュメントのみを参照すること
特定のレビュー形式で出力しなければならないこと
チーム内の既存の用語を保持しなければならないこと
特定のリポジトリの記述または開発規約を遵守しなければならないことこのような作業は、毎回プロンプトに頼って一時的に指示を出すだけでは、漏れが生じやすいです。

ツールとプロセスを併用するタスク

このシナリオは特に典型的なものです。単に「GitHubに接続する」だけで終わるのではなく、接続した後も、何らかの方法でログを確認し、問題を分類し、修正が必要かどうかを判断し、最後にどのようにフィードバックするかという一連の作業が必要です。つまり、外部接続と内部プロセスが組み合わさって機能しなければなりません。このような場合、しばしば MCP + Skill が組み合わさって登場します。

スキルとして実装する必要がないシナリオ

逆に、どこまでを「スキル」とするのかを明確に伝える必要があります。そうしないと、何でもかんでもSkillにしようとしてしまいがちです。

一回限りの気軽なタスク

ユーザーが一時的に質問する場合、通常のプロンプトで十分なことが多いです。

あなたが望んでいるのは「外部システムへの接続」だけだ

その場合は、Skill ではなく MCP を優先的に検討してください。

リポジトリ全体の長期的な振る舞いを制約したい場合

これは Skill の仕事というよりは、AGENTS.md の仕事に近いです。したがって、簡単にまとめると以下のようになります：

接続が不足している場合、MCP を使う
プロセスが不足している場合、Skill を使う
グローバルなルールが不足している場合、AGENTS.md を使う

代表的な事例をいくつか

概念をどれだけ説明しても、実際の事例を見る方が良いです。

1. `roll-dice`：最小限の入門ケース

このケースはOpenAI公式のAgent Skillsドキュメントからのものです。非常に小さく、ディレクトリ内にはほとんどSKILL.mdしかなく、エージェントがユーザーからサイコロを振るよう要求された際に、PowerShellの乱数コマンドを呼び出すようにします。なぜこの例が良いのか？それはSkillの最も核となる骨格を直接示しているからです：

明確なトリガー条件がある
明確な実行方法がある
明確な境界線があるこれは、Skillが必ずしも大きくなくて良いことを示しています。あることが繰り返し発生し、モデルに無作為な振る舞いをさせたくない場合、それをSkillとして実装できるということです。

2. `gh-address-comments`：GitHub コメント処理のワークフロー例

このケースは、OpenAI 公式の openai/skills リポジトリから来ました。目的は「GitHubに接続する」ことではなく、「現在のブランチのPRのコメントを処理する」という一連のプロセスを固定化することです。公式バージョンでの手順が非常に典型的です：

まずghが認証済みか確認する
次に、現在のPRのコメントとレビュースレッドを取得する
これらのコメントに番号を振り、要約する
ユーザーにどのコメントを処理するか明確に選択させる
その後で初めて処理を開始するこの例は、Skill の価値を特に示しています。多くのエンジニアリングタスクにおいて、難しさは「モデルがGitHubとは何かを知っているか」という点ではなく、「正しい順序で物事を処理できるか」という点にあります。gh-address-comments が解決しているのは、まさにこのような順序の問題です。

3. `gh-fix-ci`：CI 失敗のエンジニアリングケースの調査

これも openai/skills リポジトリ内の公式スキルです。これは別の非常に典型的なエンジニアリングタスクを対象としています。それは、PR のチェックが失敗したとき、「直すべきか」「どう直すか」というものです。この Skill で定義されているワークフローも非常に代表的です：

まず gh のログイン状態を確認する
現在の PR を見つける
GitHub Actions の失敗したチェックとログを取得する
失敗した部分を抽出する
まず修正計画を立てる
承認を得てから実行するこれは、「CI がなぜ失敗したか見て」という単なるプロンプトでは安定して対応できないシナリオです。なぜなら、権限、ログ、外部ツール、承認の境界線、実行順序など、これらすべてを定義する必要があるからです。

4. リポジトリ固有のスキル：チーム独自のノウハウを蓄積する

公式なサンプル例以外で、私が考える Skill のより大きな価値は、実はプライベートリポジトリ内にあります。例えば、目の前のブログリポジトリにある blog-writer は、本質的には非常に典型的な repo-scoped skill です。これは「モデルに中国語の書き方を学ばせる」ことを担当しているのではなく、このリポジトリで既に固定された文体、構造、ファクトチェック、出力パス、データ保存形式などをワークフローとして記述したものです。このような Skill は、最も現実的な価値を持つことが多いです。なぜなら、すべての人に向けられているわけではなく、「あなたはこのリポジトリで、どのような種類の作業が繰り返し発生し、かつ逸脱しやすいか」という点に特化して解決するものだからです。

実際に「Skill」を使うべき時

そこで、最後に最も実用的な問題に戻ります。いつ真剣に Skill を作るべきでしょうか？私の答えは以下の通りです。それは、問題がもはや「モデルの能力不足」ではなく、「毎回同じ行動が安定しない」と感じたときです。この段階でプロンプトを積み重ねても、得られる利益は通常低くなる一方です。今日一文追加し、明日また一文追加するうちに、プロンプトはまるで出来事の羅列になり、モデルはやはりミスを犯します。むしろ、それを Skill として整理し、トリガー条件、手順、境界線、スクリプト、資料などを分けて管理する方が、効果が安定しやすく、再利用性も高まります。 MCP は外部世界と接続し、Skill は内部のノウハウを固定化します。前者は「できるかどうか」を解決し、後者は「どうすれば安定してできるか」を解決します。これが私が今理解している Skill です。それは新しいプロンプトでも、新しいプロトコルでもありません。むしろ、エージェントに職種マニュアルを渡すようなものです。

参考資料

作成上の注記

元のプロンプト

プロンプト：AI大規模言語モデルによるプログラミングについて、まずMCPが登場し、次にSkillが登場しました。平易な言葉で、Skillが何か、どのようにSkillを開発するか、どのようなシナリオに適しているか、それぞれ具体的な代表的な事例を挙げて説明してください。

ライティングの骨子まとめ

「MCP と Skill の概念レビュー」として繰り返し書くのではなく、重点を Skill の役割と使用範囲に置いた。
「職種マニュアル」「特定作業手順書（SOP）」といった平易な比喩を用いて、抽象的な定義を実際のワークフローに落とし込んだ。
開発部分は公式ドキュメントの実構造に沿って記述し、description、progressive disclosure、instruction-only といった重要な点を保持した。
ケーススタディは可能な限り公式ソースを選定し、それぞれ公式ドキュメント内の roll-dice、および openai/skills リポジトリ内の gh-address-comments と gh-fix-ci を使用した。
最後に、読者が読み終えた後も混同しないよう、MCP、Skill、AGENTS.md の三者の境界線を改めて整理した。