OpenAI Skillsの説明およびインストール・使用法

Codex Skillsの概念および使用法説明
Tags:

Skillsとは？

AIツールを使っていると、同じプロンプトを繰り返し入力する瞬間が必ず来る。コードレビュー依頼、テストコード生成、ログ分析など、毎回同じ作業を説明し直すのは思ったより非効率である。

この問題を解決する核心が「Skills」である。簡単にいえば、よく使う作業を一つの再利用可能なコマンドとして作っておく機能である。

一度うまく作っておけば、毎回長く説明しなくても短いトリガーだけで同じ結果を得られる。

つまり、Skillsは再利用可能なワークフローを書くためのフォーマットであり、Codex CLIだけでなくIDE拡張プログラムやCodexアプリでも使用できる。

核心構造

Skillは複雑に見えるが構造は単純である。核心は「入力 -> 処理 -> 出力」の流れである。

  • 入力: ユーザー要求（例: 「このコードのテストを作って」）
  • 処理: 定義されたプロンプトロジック
  • 出力: 成果物（テストコード、説明など）

重要なのは、単にプロンプトを保存するのではなく、「役割 + ルール + 出力形式」まで含む点である。

一般要求:

  • 「このコードのテストコードを作って」

Skill:

  • 役割: テストコード専門家
  • ルール: Kotest使用、WebFlux考慮
  • 出力: すぐ実行可能なコード

この違いだけで結果の品質が大きく変わる。

Skillsのインストール

スキルはコマンドで使うか、直接ファイルを入れて簡単にインストールできる。

方法1: 公式カタログからインストール

OpenAI Codexの公式スキルカタログは、AIエージェントが特定作業を反復実行できるよう、指示、スクリプト、リソースをまとめたフォルダー構造のモジュールである。

公式リポジトリ（GitHub）のopenai/skillsでCodex用スキルカタログを確認できる。

CodexでSkillをインストールするには$skill-installerを実行する。

$skill-installer {スキル名}

たとえば、screenshotというskillをインストールする方法は次のとおりである。

$skill-installer screenshot

実行すると、~/.codex/skills/フォルダーにMarkdown形式の仕様（SKILL.md）などのファイルが作成される。

次のファイルはscreenshotというSkillをインストールして生成されたファイルである。

.codex
└── skills
    └── screenshot
        ├── agents
        │   └── openai.yaml
        ├── assets
        │   ├── screenshot-small.svg
        │   └── screenshot.png
        ├── LICENSE.txt
        ├── scripts
        │   ├── ensure_macos_permissions.sh
        │   ├── macos_display_info.swift
        │   ├── macos_permissions.swift
        │   ├── macos_window_info.swift
        │   ├── take_screenshot.ps1
        │   └── take_screenshot.py
        └── SKILL.md

インストール後にCodexを再起動すると、すぐに使用できる。

方法2: GitHub URLを入力してインストール

GitHub URLを直接入力してインストールすることもできる。

$skill-installer https://github.com/openai/skills/tree/main/skills/.curated/{スキル名}

方法3: プロジェクトルートに直接追加

プロジェクトルートに.agents/skills/フォルダーを作り、スキルフォルダーを入れればよい。 これをGit pushすると、チームメンバー全員がすぐに使用できる。

CodexでSkillを使用する

Codexは二つの方式でスキルを使用できる。

明示的呼び出し（Explicit invocation）

CLI/IDEでは、プロンプトに${スキル名}を入力してスキルを指定し、直接呼び出せる。

たとえば、screenshotというskillを使用する方法は次のとおりである。

$screenshot https://www.devkuma.com --fullpage

または/skillsコマンドで使用可能なスキル一覧を確認して選択する。

暗黙的呼び出し（Implicit invocation）

作業内容を説明すると、Codexが自動で適切なスキルを探して実行する。

たとえば、「このPRのコメントを反映して」と言うと、gh-address-commentsスキルが自動実行される。

  • 作業内容がスキルのdescriptionと一致すると、Codexが自動選択する。

暗黙的マッチングはskills/SKILL.mdファイル内のdescriptionに依存する。

Skillの基本ファイル構造

Codexはまず各スキルの名前、説明、ファイルパスだけを参照し、実際にそのスキルを使用すると判断したときだけSKILL.md全体をロードする。

Codexは適切なスキルを選択できるよう、初期コンテキストに使用可能なスキル一覧を含める。 この一覧はプロンプト空間を過度に占有しないよう制限され、全体コンテキストの約2%または最大8,000文字程度である。 スキルが多い場合は説明が先に短縮され、非常に多い場合は一部スキルが一覧から除外され警告が表示される。

この制限は初期スキル一覧にだけ適用される。Codexが特定スキルを選択すると、そのスキルのSKILL.md全体を読む。

一つのスキルはSKILL.mdファイルと、任意のスクリプトおよびリソースで構成されるディレクトリである。

my-skill/
├── SKILL.md        # 必須: 指示 + メタデータ
├── scripts/        # 任意: 実行コード
├── references/     # 任意: 文書
├── assets/         # 任意: テンプレート、リソース
└── agents/
    └── openai.yaml # 任意: UIおよび依存関係設定
  • SKILL.md
    • 必須ファイルで、name、description、Codexが従うべき核心手順が入る。
  • scripts/
    • 任意で、同じコードを繰り返し書くことになる場合に入れる。
    • 変更ファイル一覧収集、PRメタデータ整理、特定テスト実行のように、決定的に同じ動作が必要な場合に適している。
  • references/
    • 任意で、参考資料を入れる場所である。
    • RLSポリシー点検基準、チームのAPI契約、デプロイポリシーなどの文書がよく合う。
  • assets/
    • 任意で、出力物に使うテンプレートやリソースを置く。
    • レビューコメントテンプレート、PR説明テンプレート、報告書形式ファイルなどである。

Skillを作る

公式スキルだけでは不足する場合がある。自分またはチームのワークフローのためにカスタムスキルが必要になることがある。

カスタムスキルを作るには、上で述べたSKILL.mdファイルを作成する必要がある。

SKILL.mdの書き方:

---
name: skill-name
description: このスキルがいつ実行され、いつ実行されるべきでないかを明確に説明
---

Codexが従うべきスキル指示を書く

ここでdescriptionが最も重要である。暗黙的マッチングはこのdescriptionに依存するため、明確かつ簡潔に書く必要がある。

  • 核心ユースケースを前に配置
  • トリガーキーワードを明確に記述
  • 説明が切れてもマッチできるように書く
  • 韓国語と英語キーワードを両方含める
  • 実際に入力しそうな表現を列挙
  • このスキルがしないことも明示（誤ったマッチング防止）

description例:

description: "PRレビューコメントを自動で反映する。'리뷰 반영', 'PR 코멘트', 'address comments', 'fix review'などに反応する。コードレビュー自体は実行しない。"

基本生成器で作る

直接SKILL.mdファイルを書いてもよいが、基本生成器の使用を推奨する。

$skill-creator

この生成器は次を質問する。

  • スキルが行う作業
  • いつ実行されるべきか
  • スクリプトを含めるかどうか（デフォルトはinstruction-only）

Codexはスキル変更を自動で検知する。変更が反映されない場合はCodexを再起動すればよい。

Skillの保存場所

Codexは複数の場所からSkillをロードする。

範囲 場所 用途
REPO $CWD/.agents/skills 現在の作業ディレクトリだけにスキル適用
REPO $CWD/../.agents/skills 上位ディレクトリだけに適用されるスキル
REPO $REPO_ROOT/.agents/skills リポジトリ全体の共有スキル
USER $HOME/.agents/skills ユーザー個人スキル（すべての自分のプロジェクトに適用）
ADMIN /etc/codex/skills システム全体の共有スキル
SYSTEM Codex標準提供 標準内蔵スキル（$skill-installer, $skill-creatorなど）

Codexはシンボリックリンクされたスキルフォルダーもサポートする。

これらの場所はローカル開発および探索用である。外部配布したい場合はpluginを使う方がよい。

任意メタデータ

agents/openai.yamlを追加すると、UIおよびポリシー設定が可能である。

interface:
  display_name: "ユーザーに表示される名前"
  short_description: "簡単な説明"
  icon_small: "./assets/small-logo.svg"
  icon_large: "./assets/large-logo.png"
  brand_color: "#3B82F6"
  default_prompt: "デフォルトプロンプト"

policy:
  allow_implicit_invocation: false

dependencies:
  tools:
    - type: "mcp"
      value: "openaiDeveloperDocs"
      description: "OpenAI Docs MCPサーバー"
      transport: "streamable_http"
      url: "https://developers.openai.com/mcp"
  • allow_implicit_invocationのデフォルト値: true
  • falseに設定すると自動呼び出しが無効化される（明示的呼び出しは可能）。

Skillの有効化/無効化

不要なスキルがある場合、削除せずに~/.codex/config.tomlで有効化 여부を設定できる。

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

設定変更後はCodexの再起動が必要である。

プラグインとしてスキルを配布

ローカルスキルフォルダーは開発とテストに適している。

次のような場合はpluginとしてパッケージングするのがよい。

  • 再利用可能なスキル配布
  • 複数スキルを一つにまとめる
  • アプリ連携を含める

プラグインには次を含められる。

  • 複数のスキル
  • アプリマッピング
  • MCPサーバー設定
  • UIアセット

Claude SkillsをCodexで活用

Claude、Codexツールはいずれも同じAgent Skillsオープン標準（agentskills.io）に従うため、同じSKILL.mdフォーマットを使い、AnthropicのSkillsリポジトリをCodexでも活用できる。

方法は簡単である。

  1. Claude Skillsリポジトリを.agents/skills/に複製する。
  2. list-skillsスクリプトを追加する。
    • skillsフォルダーのSKILL.mdを読み、JSONを出力する。
  3. AGENTS.mdに「list-skillsを実行して使用可能なskillsを確認せよ」という指示を追加する。

こうすると、Claude Code用に作ったスキルをCodexでもそのまま活用できる。 ただし、この方法はコミュニティで発見された活用法であり、OpenAI/Anthropicが公式にサポートする相互運用機能ではない。

基本的なスキルは相互互換が可能である。ただし、各ツールの拡張機能（Claude Codeのallowed-tools、Codexの.systemディレクトリなど）は互換しない場合がある。

Claude Code Skills vs Codex Skills比較

Claude Code Codex
定義ファイル SKILL.md SKILL.md
インストール方式 /plugin install + 手動コピー $skill-installer
公式カタログ あり 35+ キュレーション
暗黙的呼び出し サポート サポート
チーム共有 Gitコミット Gitコミット
実行環境 CLI + IDE拡張 CLI + アプリ + IDE

実務での生産性向上

スキルはCodex CLI、IDE拡張プログラム、Codexアプリで使用できる。

単に作ることより重要なのは「どこに使うか」である。実際に効果が大きかった事例をいくつか共有する。

  1. ログ分析自動化
    • WebFluxログは非同期フローのため分析が難しい。Skillで「ログ解釈専門家」を作っておくと、複雑なログも構造的に説明してくれる。
  2. テストコード標準化
    • チームごとにテストスタイルが異なる問題をSkillsで解決できる。ルールを強制すると、すべてのコードが同じスタイルで生成される。
  3. 反復業務の除去
    • API文書生成
    • エラーメッセージ分析
    • コードリファクタリング提案

このような作業はSkillsとして作っておくと、ほぼ自動化レベルで処理される。

核心は「よく行う作業は必ずSkillにする」という基準を立てることである。

まとめ: Codex Skillsは開発生産性の核心ツール

Codex Skillsは単純なプロンプト保存機能ではない。反復作業を自動化し、結果の品質を標準化する強力なツールである。

最初は一つ作るだけでも十分である。テストコード生成、ログ分析、コードレビューのうち、最も頻繁に行う作業から始めてみよう。

一度慣れると、「なぜ今まで使わなかったのか」と思うほど開発フローが変わる。

FAQ

Q1. Codex Skillsはいつ使うのがよいか？

同じ要求を3回以上繰り返すなら、すぐSkillにするのがよい。特にテストコード生成、文書化、ログ分析のような作業に効果的である。

Q2. Skillが多くなると管理が難しくならないか？

そのため、命名と目的定義が重要である。“test-webflux”、“log-analyzer"のように明確に区分すると管理しやすい。

Q3. 初心者でもすぐ使用できるか？

可能である。複雑なロジックなしにRole、Rules、Outputだけ明確に定義すればよい。むしろ初心者ほど反復作業を減らすのに大きな助けになる。