Codex Skillsとは？skill.mdの作り方・使い方ガイド｜Claude Codeとの違い

「Skill.md って何？どう書けばいいの？Codex と Claude Code で書き方は同じ？」

AIコーディングツールの Skills 機能が急速に広がり、Skill.md の書き方を調べに来る人が増えています。OpenAI Codex も Claude Code も Agent Skills というオープン仕様に準拠していて、SKILL.md の必須フィールドは共通です。一方で置き場所と仕様外の拡張フィールドはツールごとに違うため、「結局どう書けばいいのか」で迷いやすいのが実情です。

この記事では、まず Skill.md とは何か を整理したうえで、Codex Skills の Skill.md フォーマット仕様を詳しく解説し、Claude Code Skills との違い、ツール横断で再利用できる書き方のベストプラクティスを紹介します。

この記事で学べること

• Codex SkillsのSkill.mdフォーマット仕様
• フロントマターの各フィールドの意味と書き方
• Claude Code Skillsとの具体的な違い
• ツール横断で再利用できるスキル設計パターン

前提条件

• Codex（Free / Go / Plus / Pro / Business / Edu / Enterprise のいずれかの ChatGPT プラン、または API キー）または Claude Code（Claude のサブスクリプション、または Anthropic Console アカウント）のアカウント
• ターミナルの基本操作
• Markdownの基本的な記法

Codex Skillsとは

Codex Skillsは、AIエージェントに再利用可能な手順やナレッジを教える仕組みです。

「毎回同じ指示を書くのが面倒」「チームで手順を統一したい」という課題を解決します。

スキルの構成

my-skill/
├── SKILL.md          ← 必須：スキル定義
├── scripts/          ← オプション：実行スクリプト
│   └── run.sh
└── references/       ← オプション：参照ドキュメント
    └── api-spec.md

スキルはディレクトリ単位で管理されます。最低限必要なのはSKILL.mdファイル1つだけです。

スキルの置き場所

Codex は以下のディレクトリを順に探索します（Build skills）。

置き場所	パス
カレントディレクトリ	$CWD/.agents/skills
リポジトリルート	$REPO_ROOT/.agents/skills
個人用（全プロジェクト共通）	$HOME/.agents/skills
システム管理者	/etc/codex/skills

Claude Code は別のパスを見ます（個人用は ~/.claude/skills/<name>/SKILL.md、プロジェクト用は .claude/skills/<name>/SKILL.md）。SKILL.md の中身は共通仕様で書けても、置き場所だけはツールごとに違うので、両方で使いたいスキルは symlink で両方のディレクトリに生やすのが実用的です。

Skill.mdフォーマット仕様

skill.md の書き方にはじめて取り組む場合は、まず skill.md / SKILL.md の基本的な書き方 でフォーマットの全体像を掴んでください。肥大化を抑える設計に踏み込むなら SKILL.md 設計パターン を合わせて参照してください。

基本構造

Skill.mdはYAMLフロントマター + Markdown本文で構成されます。

---
name: my-awesome-skill
description: |
  Describe what this skill does and when to use it.
  Use when: specific trigger conditions.
  Accepts args: <required-arg> [--optional-flag]
---

# Skill Title

Detailed instructions for the agent.

## Step 1: Do something

Instructions here...

フロントマターのフィールド

SKILL.md のフォーマットは Agent Skills というオープン仕様として公開されていて、Codex も Claude Code もこれに準拠しています。仕様が定義しているフィールドは6つだけです。

フィールド	必須	説明
name	✅	スキルの識別子。最大64文字。親ディレクトリ名と一致させる
description	✅	スキルのトリガー判定に使われる説明文。最大1024文字
license	❌	スキルのライセンス表記
compatibility	❌	実行環境の要件（最大500文字）
metadata	❌	任意のキーバリュー。仕様上の意味は持たない
allowed-tools	❌	事前承認するツールをスペース区切りで列挙（Experimental。対応は実装依存）

これ以外のフィールドは各ツールの独自拡張です。Claude Code は when_to_use / disallowed-tools / model / context など多数の拡張フィールドを持ちますが、仕様の6フィールドだけで書いておけばツールを跨いでそのまま動きます。

nameフィールドのルール

# 良い例
name: deploy-to-staging
name: run-e2e-tests
name: generate-api-docs

# 仕様違反になる例
name: Deploy to Staging    # スペース・大文字NG
name: my_skill             # アンダースコアNG
name: -deploy              # ハイフンで開始・終了NG
name: deploy--staging      # ハイフン連続NG

Agent Skills 仕様上の制約は以下の通りです。

• 1〜64文字
• 小文字英数字（a-z、0-9）とハイフン（-）のみ
• ハイフンで開始・終了しない、ハイフンを連続させない
• 親ディレクトリ名と一致させる

仕様としては a のような1文字名も有効ですが、description と並んでトリガー判定の材料になるので、意味が伝わる長さ（2〜5単語程度）にしておくのが実務的です。

descriptionフィールドの書き方

descriptionはスキルの中で最も重要なフィールドです。

なぜなら、エージェントは name と description だけを起動時に読み込み、ユーザーの指示に合致するスキルを選んでから本文を読むからです。Agent Skills 仕様ではこれを progressive disclosure と呼び、(1) メタデータ（name + description、約100トークン）、(2) SKILL.md 本文、(3) scripts/ や references/ の中身、の3段階で読み込むと定義しています。descriptionはこの第1段階に載る唯一の説明文です。

# 良い例
description: |
  Run end-to-end tests for the web application.
  Use when: user asks to run tests, verify functionality, or check for regressions.
  Accepts args: [--browser chrome|firefox] [--headless]

# 悪い例
description: "Tests the app"  # 曖昧すぎる

descriptionに含めるべき情報:

1. 何をするか（1文で要約）
2. いつ使うか（Use when: で明示）
3. 引数（Accepts args: で明示）

descriptionの上限は Agent Skills 仕様で1024文字です。ただし上限まで書いていいわけではありません。Codex はスキル一覧全体を「コンテキストウィンドウの2%または8,000文字まで」に収め、Claude Code は1エントリあたり description + when_to_use を1,536文字で切り詰めます。スキルが増えるほど1本あたりの取り分は減るので、重要なユースケースを先頭に置いて簡潔に書いてください。

Markdown本文の設計

本文には、エージェントが実行すべき具体的な手順を書きます。

# E2E Test Runner

## Prerequisites

- Node.js 20+ installed
- Test server running on localhost:3000

## Execution Steps

### Step 1: Install dependencies

```bash
npm ci
```

### Step 2: Run tests

```bash
npx playwright test --reporter=html
```

### Step 3: Report results

Summarize test results to the user:
- Total tests run
- Pass/fail count
- Failed test details

本文の設計ポイント:

• 500行以内に収める。超える場合はreferences/に分割
• ステップバイステップで書く（エージェントは順番に実行する）
• コードブロックで実行コマンドを明示
• 判断基準を明記（「Xの場合はAを実行、Yの場合はBを実行」）

Claude Code Skillsとの比較

フォーマットの違い

項目	Codex Skills	Claude Code Skills
ファイル名	SKILL.md	SKILL.md（同じ）
必須フロントマター	name + description	仕様に合わせるなら同じ（Claude Code 単体では全フィールドが任意扱い）
本文	Markdown	Markdown（同じ）
配置ディレクトリ	.agents/skills/、$HOME/.agents/skills/ ほか	.claude/skills/、~/.claude/skills/ ほか
拡張フィールド	公式ドキュメントに記載なし	when_to_use / disallowed-tools / model / context: fork など多数
ツール制限	公式ドキュメントに記載なし	disallowed-tools でツールを外せる
共有方法	プラグイン（openai/plugins のマーケットプレイス）	リポジトリへのコミット / プラグイン / managed settings

allowed-tools は「制限」ではなく「事前承認」

ここは誤解されやすいところなので、はっきり書いておきます。allowed-tools は Agent Skills 仕様に含まれるオプションフィールドで（Claude Code 固有ではありません）、その意味は 「事前承認済みのツールを列挙する」 であって、列挙されていないツールを禁止するものではありません。

Claude Code のドキュメントも明示的にこう述べています — allowed-tools は「使えるツールを制限しない。すべてのツールは引き続き呼び出し可能」であり、承認をスキップできるのはスキルを起動したそのターンの間だけです。

---
name: safe-deploy
description: |
  Deploy to production with safety checks.
# 事前承認（このターンだけ許可プロンプトを省略する）
allowed-tools: Bash(git:*) Read Grep
# 実際に外したいツールはこちら（Claude Code の拡張フィールド）
disallowed-tools: Write Edit
---

「本番コードの変更を防ぎたい」なら、allowed-tools から Write / Edit を外すだけでは不十分です。Claude Code なら disallowed-tools を使うか、そもそもパーミッション設定の deny ルールで縛るのが正しい対処になります。Codex 側にツールを制限するフロントマターは公式ドキュメントに見当たりません。

スキルの組み合わせ

Claude Code では、スキルは Skill ツールを通じて呼び出されます。ユーザーが /skill-name と打つほかに、Claude 自身が関連するスキルを判断して起動できるため、あるスキルの本文から別のスキルを起動させる構成が組めます。

## Step 3: Review & fix

Skill ツールで `pr-iterate` を起動し、レビュー指摘が解消するまで反復させる。

Skill: xxx のような専用ディレクティブが仕様として定義されているわけではありません。本文に自然文で「このスキルを起動する」と書いておくと、Claude がその指示に従って Skill ツールを呼ぶ、という挙動です。これにより、小さなスキルを組み合わせて複雑なワークフローを構築できます。

dev-flow
  ├── dev-issue-analyze
  ├── git-commit
  ├── git-pr
  └── pr-iterate

Codex 側でスキルからスキルを呼ぶ仕組みについては、公式ドキュメントに記載がありません。

Claude Code Skillsの設計パターンについては Claude Code Skills設計思想と自作ガイド で詳しく解説しています。

Codex Skillsの強み

公式のプラグイン／スキル配布

OpenAI は Codex 向けのプラグイン例を openai/plugins で公開しており、マーケットプレイス経由でインストールできます。かつて公式スキルカタログだった openai/skills は現在 deprecated（非推奨）で、リポジトリ自身が openai/plugins を参照するよう案内しています。過去の記事やブックマークから git clone https://github.com/openai/skills.git を辿ってきた場合は、こちらに読み替えてください。

Agent Skills 標準への準拠

Codex は SKILL.md をオープン仕様の Agent Skills として扱っています。Claude Code をはじめ複数のツールが同じ仕様に乗っているため、仕様の6フィールドの範囲で書いたスキルはツールを跨いで使い回せます。なお、利用可能なモデルや料金は更新されるため、最新情報は Codex 公式ドキュメント を参照してください。

ツール横断のスキル設計パターン

同じスキルを複数ツールで動かすなら、書き方だけでなく「1つの実体をどう各ツールに配るか」までセットで決めておくと後が楽です。~/.claude/skills・~/.codex/skillsなどをsymlinkで1つのリポジトリに束ねる方法は、複数のAIコーディングツールでSkillsを共有するにまとめています。

パターン1: 互換性重視の基本構造

CodexでもClaude Codeでも動くスキルを書くには、共通部分だけを使います。

---
name: lint-and-format
description: |
  Run linting and formatting checks on the codebase.
  Use when: user asks to check code quality, fix formatting, or run lint.
---

# Lint & Format

## Step 1: Run linter

```bash
npm run lint
```

## Step 2: Auto-fix

```bash
npm run lint -- --fix
```

## Step 3: Report

Report the results:
- Files checked
- Issues found
- Issues auto-fixed

Agent Skills 仕様の6フィールドだけで書いておけば、どちらのプラットフォームでもそのまま動作します（allowed-tools は仕様に含まれますが Experimental 扱いで、対応は実装依存です）。

パターン2: プラットフォーム別の拡張

共通スキルを基盤にして、プラットフォーム固有の拡張を追加します。

skills/
├── lint-and-format/          ← 共通スキル
│   ├── SKILL.md
│   └── scripts/
├── claude-extensions/        ← Claude Code固有
│   └── lint-and-format/
│       └── SKILL.md          ← allowed-tools追加版
└── codex-extensions/         ← Codex固有
    └── lint-and-format/
        └── SKILL.md          ← カタログ公開用

パターン3: 参照ファイルの共有

手順やナレッジはreferences/に分離し、複数のスキルから参照します。

shared-references/
├── coding-standards.md
├── api-conventions.md
└── testing-guidelines.md

skill-a/
├── SKILL.md  ← "See ../shared-references/coding-standards.md"
└── ...

skill-b/
├── SKILL.md  ← "See ../shared-references/coding-standards.md"
└── ...

実践: スキルを作ってみよう

例: コミットメッセージ生成スキル

---
name: smart-commit
description: |
  Generate a conventional commit message from staged changes.
  Use when: user asks to commit, create a commit message, or save changes.
  Accepts args: [--scope <scope>] [--breaking]
---

# Smart Commit

## Step 1: Analyze staged changes

```bash
git diff --cached --stat
git diff --cached
```

## Step 2: Generate commit message

Based on the changes, generate a commit message following Conventional Commits:

Format: `<type>(<scope>): <description>`

Types:
- `feat`: New feature
- `fix`: Bug fix
- `refactor`: Code restructuring
- `docs`: Documentation
- `test`: Test additions/changes
- `chore`: Build/config changes

## Step 3: Confirm and commit

Show the generated message to the user and ask for confirmation.

```bash
git commit -m "<generated message>"
```

注意点・Tips

• descriptionは英語で書く: 公式に「英語が有利」と明記されているわけではありませんが、公式サンプルが英語で統一されていることもあり、私たちは英語で揃える運用にしています。日本語で頼まれる想定なら、起動ワードを日本語のまま description に併記しておくと取りこぼしが減ります。本文は日本語でOK
• 1スキル1責務: 複数の責務を持たせると、トリガー精度が下がる
• テスト可能にする: スキルの出力が検証可能な形（テスト結果、ビルド結果）になるように設計する
• バージョン管理: スキルはGitで管理し、変更履歴を追えるようにする

まとめ

Codex SkillsとClaude Code SkillsはSKILL.mdを中心にした共通の設計思想を持っています。というより、Agent Skills という同じオープン仕様に両方が乗っています。

主な違いは配置ディレクトリ（.agents/skills/ と .claude/skills/）と、仕様外の拡張フィールドの充実度です。仕様の6フィールド（name / description / license / compatibility / metadata / allowed-tools）だけで書けば両プラットフォームで再利用でき、プラットフォーム固有の拡張は必要に応じて追加する、というアプローチが効率的です。

なお allowed-tools は「事前承認」であって「制限」ではありません。ツールを実際に禁止したい場合は Claude Code の disallowed-tools やパーミッション設定を使ってください。

書き方が固まったら、次は運用です。Claude Code と Codex を同じプロジェクトで併用するときの worktree による作業ディレクトリ分離とタスクの振り分けは、Claude Code × Codex 統合ワークフローで扱っています。

まずは1つ、自分のよくやる作業をスキル化してみてください。

AIコーディングツールの導入支援・課題診断

「自社チームに Skill.md ベースの運用を取り込みたいが、どこから着手すべきか整理したい」「Codex と Claude Code をどう併用するか棚卸ししたい」という方向けに、playpark では小さな課題診断と導入支援を提供しています。 課題を相談する ｜ AIコーディングツール完全比較を読む

---

関連記事

• SKILL.md の設計パターン・ベストプラクティス完全ガイド — SKILL.md 肥大化を87%削減したスクリプト化戦略と設計の全体像（本記事の上位ガイド）
• Claude Code・Codex・Antigravity の設定スクリプトを冪等にする4つのパターン — symlink 管理と config.toml の冪等化。Skills 共有環境を整備した後に読むと参考になります
• 複数のAIコーディングツールでSkillsを共有する — symlink で 4 ツールに 1 つの実体を配る構成
• Claude Code × Codex 統合ワークフロー — 書いたスキルを実プロジェクトで併用するときの運用設計
• Claude Code Skills入門ガイド
• Claude Code Skill Orchestration

AIコーディングツール比較・選定ガイド — この記事を含む11本の記事で、AIコーディングツールの比較・選定・共存運用を体系的に解説しています。