Build skills / Skills & Plugins

概要

指示・リソース・任意のスクリプトをまとめて、特定タスクの手順を確実に踏ませる仕組み。open agent skills standard に基づく。skill は再利用可能なワークフローのオーサリング形式で、他人に配布したい場合は plugin としてパッケージする。

仕様

提供範囲

standalone skill は ChatGPT desktop app、Codex CLI、IDE extension で使える
plugin にバンドルされた skill は、ChatGPT Work on the web を含む対応 plugin サーフェスでも使える
ChatGPT desktop app ではサイドバーの Skills で、プロジェクト横断で作った skill を閲覧できる

progressive disclosure とコンテキスト予算

最初は各 skill の name と description だけを持ち、使うと決めたときに SKILL.md の全内容を読む
Codex では初期リストに各 skill のファイルパスも含まれる
プロンプトの残りを圧迫しないよう、この初期リストはモデルのコンテキストウィンドウの最大 2%、コンテキストウィンドウが不明な場合は 8,000 文字を使う
skill が多い場合、まず description を短縮する。非常に多い場合は一部を初期リストから省き、警告を表示する
この予算は初期リストにのみ適用される。 skill を選んだ後は、その SKILL.md の全文を読む

呼び出し方法

明示的な呼び出し: ChatGPT では @、Codex CLI / IDE extension では /skills または $ で skill を指定する
暗黙的な呼び出し: タスクが skill の description に一致すると自動で選ばれうる

暗黙のマッチングは description に依存するため、範囲と境界を明確にした簡潔な説明を書く。description が短縮されてもマッチできるよう、主要なユースケースとトリガー語を先頭に置く

skill の構造

SKILL.md を含むディレクトリ（＋任意のスクリプトと参照資料）
SKILL.md は name と description を必須とする

作り方

既にやり方が分かっていて説明より実演が容易なら Record & Replay を使う。録画から再利用可能な skill を起こす
説明で作るなら組み込みの creator を使う。ChatGPT Work では @skill-creator、Codex では $skill-creator
- creator は何をする skill か、いつ発動すべきか、instruction-only にするかスクリプトを含めるかを尋ねる。既定は instruction-only
手動で SKILL.md を含むフォルダを作ってもよい
Codex は skill の変更を自動検出する。 反映されない場合は Codex を再起動する

ローカル skill の読み込み場所

repository / user / admin / system の各場所から読む。リポジトリでは、現在の作業ディレクトリからリポジトリルートまでの各ディレクトリの .agents/skills を走査する。

スコープ	場所	用途
`REPO`	`$CWD/.agents/skills`	作業フォルダに関係する skill をチェックインする
`REPO`	`$CWD/../.agents/skills`（Git リポジトリ内で起動したとき CWD より上のフォルダ）	共有領域に関係する skill
`REPO`	`$REPO_ROOT/.agents/skills`	リポジトリ利用者全員向けのルート skill
`USER`	`$HOME/.agents/skills`	どのリポジトリでも使うユーザー個人の skill
`ADMIN`	`/etc/codex/skills`	マシン／コンテナ共通の場所。SDK スクリプトや既定の admin skill
`SYSTEM`	Codex に OpenAI がバンドル	skill-creator や plan skill など、起動すれば誰でも使えるもの

同じ name の skill が 2 つあってもマージされない。 どちらも skill セレクタに現れうる
symlink された skill フォルダに対応し、走査時に symlink 先をたどる
これらの場所はオーサリングとローカル発見のためのもの。単一リポジトリを超えて配布したい場合は plugin を使う

有効・無効

~/.codex/config.toml の [[skills.config]] で、削除せずに無効化できる。変更後は Codex を再起動する。

任意のメタデータ（`agents/openai.yaml`）

ChatGPT desktop app 向けの UI メタデータ、invocation policy、ツール依存関係を宣言する
interface: display_name、short_description、icon_small、icon_large、brand_color、default_prompt
policy.allow_implicit_invocation（既定 true）: false にすると、ユーザーのプロンプトに基づく暗黙の呼び出しをしなくなる。明示的な $skill 呼び出しは引き続き動く
dependencies.tools: type / value / description / transport / url を持つツール依存

curated skill のインストール

$skill-installer で組み込み以外の curated skill を追加する（例: $skill-installer linear）
他のリポジトリから skill をダウンロードさせることもできる
新しくインストールした skill は自動検出される。 出てこない場合は再起動する
これはローカルのセットアップと実験向け。自分の skill を再利用可能な形で配布するなら plugin を使う

skill と plugin の使い分け

skill: 特定タスク向けの再利用可能な指示
plugin: skill、connector、またはその両方を含むインストール可能なバンドル。connector は MCP サーバーに支えられ、任意でカスタムの ChatGPT UI を含みうる
plugin は 1 つ以上の skill を含められ、登録済み MCP サーバー接続、バンドルされた MCP サーバー設定、表示用アセットを 1 パッケージにまとめられる
ChatGPT と Codex は単一の共通 plugin ディレクトリを共有する
再利用可能な skill を配布したい、2 つ以上の skill をまとめたい、connector と一緒に出したい場合は plugin にする

設定

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

Skill instructions for ChatGPT or Codex to follow.

[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

# agents/openai.yaml
interface:
  display_name: "Optional user-facing name"
  short_description: "Optional user-facing description"
  icon_small: "./assets/small-logo.svg"
  brand_color: "#3B82F6"

policy:
  allow_implicit_invocation: false

dependencies:
  tools:
    - type: "mcp"
      value: "openaiDeveloperDocs"
      description: "OpenAI Docs MCP server"
      transport: "streamable_http"
      url: "https://developers.openai.com/mcp"

制約・注意点

公式が挙げるベストプラクティス:

1 つの skill は 1 つの仕事に絞る
決定的な挙動や外部ツールが必要な場合を除き、スクリプトより指示を優先する
入力と出力を明示した命令形の手順で書く
正しく発動するか、skill の description に対してプロンプトを試す