「Codex Skillsって、Claude Code Skillsと何が違うの？Skill.mdの書き方は同じ？」
AIコーディングツールのSkills機能が急速に広がっています。OpenAI CodexとClaude Codeの両方がSkill.mdベースの仕組みを採用し、開発者の関心が高まっています。
でも、Codex SkillsとClaude Code Skillsの違いが曖昧で「結局どう書けばいいの？」と迷っている方も多いのではないでしょうか。
この記事では、Codex SkillsのSkill.mdフォーマット仕様を詳しく解説し、Claude Code Skillsとの違いと、ツール横断で使えるスキル設計のベストプラクティスを紹介します。
この記事で学べること
- Codex SkillsのSkill.mdフォーマット仕様
- フロントマターの各フィールドの意味と書き方
- Claude Code Skillsとの具体的な違い
- ツール横断で再利用できるスキル設計パターン
前提条件
- Codex（ChatGPT Plus以上）またはClaude Code（Maxプラン推奨）のアカウント
- ターミナルの基本操作
- Markdownの基本的な記法
Codex Skillsとは
Codex Skillsは、AIエージェントに再利用可能な手順やナレッジを教える仕組みです。
「毎回同じ指示を書くのが面倒」「チームで手順を統一したい」という課題を解決します。
スキルの構成
my-skill/
├── SKILL.md ← 必須：スキル定義
├── scripts/ ← オプション：実行スクリプト
│ └── run.sh
└── references/ ← オプション：参照ドキュメント
└── api-spec.md
スキルはディレクトリ単位で管理されます。最低限必要なのはSKILL.mdファイル1つだけです。
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...
フロントマターのフィールド
| フィールド | 必須 | 説明 |
|---|---|---|
name | ✅ | スキルの一意識別子。フォルダ名と一致させる |
description | ✅ | スキルのトリガー判定に使われる説明文 |
allowed-tools | ❌ | 使用可能なツールの制限（Claude Code固有） |
nameフィールドのルール
# 良い例
name: deploy-to-staging
name: run-e2e-tests
name: generate-api-docs
# 悪い例
name: Deploy to Staging # スペース・大文字NG
name: my_skill # アンダースコアNG
name: a # 短すぎ
- 小文字のケバブケース（
kebab-case）を使う - フォルダ名と一致させる
- 意味が伝わる長さ（2〜5単語）
descriptionフィールドの書き方
descriptionはスキルの中で最も重要なフィールドです。
なぜなら、エージェントはdescriptionを常にコンテキストに保持（Level 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文で要約）
- いつ使うか（
Use when:で明示） - 引数（
Accepts args:で明示）
descriptionは約100語以内を目安にしてください。長すぎるとコンテキストウィンドウを圧迫します。
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 | name + description + allowed-tools |
| 本文 | Markdown | Markdown（同じ） |
| ツール制限 | なし | allowed-toolsで明示的に制限可能 |
| スキル連鎖 | 限定的 | Skill: other-skill で直接呼び出し |
| 共有方法 | openai/skills カタログ | Gitリポジトリ |
allowed-tools（Claude Code固有）
Claude Code Skillsでは、スキルが使えるツールを制限できます。
---
name: safe-deploy
description: |
Deploy to production with safety checks.
allowed-tools:
- Bash
- Read
- Grep
# Write/Editは含めない → 本番コードの変更を防止
---
この機能により、スキルの権限を最小限に抑えてセキュリティリスクを低減できます。Codex Skillsにはこの機能はありません。
スキル連鎖（Claude Code固有）
Claude Code Skillsでは、スキル内から別のスキルを呼び出せます。
## Step 3: Validate
Skill: dev-validate --fix
これにより、小さなスキルを組み合わせて複雑なワークフローを構築できます。
dev-kickoff
├── Skill: dev-issue-analyze
├── Skill: dev-implement
├── Skill: dev-validate
├── Skill: git-commit
└── Skill: git-pr
Claude Code Skillsの設計パターンについては Claude Code Skills設計思想と自作ガイド で詳しく解説しています。
Codex Skillsの強み
openai/skillsカタログ
OpenAIは公式スキルカタログをGitHubで公開しています。35以上のスキルがコミュニティで共有されており、すぐに利用可能です。
# カタログからスキルをクローン
git clone https://github.com/openai/skills.git
codex-mini-latestモデル
軽量なcodex-mini-latestモデル（$1.50/1M入力トークン、$6/1M出力トークン）でスキルを実行できるため、大量のスキル実行でもコストを抑えられます。
ツール横断のスキル設計パターン
パターン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
allowed-toolsを省略すれば、どちらのプラットフォームでも動作します。
パターン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は英語で書く: エージェントのマッチング精度は英語が最も高い。本文は日本語でもOK
- 1スキル1責務: 複数の責務を持たせると、トリガー精度が下がる
- テスト可能にする: スキルの出力が検証可能な形（テスト結果、ビルド結果）になるように設計する
- バージョン管理: スキルはGitで管理し、変更履歴を追えるようにする
まとめ
Codex SkillsとClaude Code SkillsはSKILL.mdを中心にした共通の設計思想を持っています。
主な違いはClaude Code Skillsのallowed-tools（ツール制限）とスキル連鎖の2点です。共通部分で書けば両プラットフォームで再利用でき、プラットフォーム固有の拡張は必要に応じて追加する、というアプローチが効率的です。
まずは1つ、自分のよくやる作業をスキル化してみてください。
