この記事は playpark Blog からの転載です。
この記事で分かること
- Skill.mdフォーマットの仕様と各フィールドの役割
- CodexとClaude Codeで同じフォーマットを採用している設計理由
- どちらにも対応できるスキルの書き方の判断基準
背景: こういう課題があった
AIコーディングツールでスキル（再利用可能な手順定義）を使い始めると、ツールが増えるにつれて「このスキル、別のツールでも動かないか」という疑問が出てくる。
OpenAI CodexとClaude Codeはどちらも SKILL.md を中心にしたスキル機能を持っているが、フィールド構成や機能の差があり、「どこまで共通化できるか」の判断が難しい。
特に困るのは、Codex用に書いたスキルをClaude Codeで流用しようとしたとき、または逆方向の移植をしようとしたときだ。
選択肢の検討
スキルをどう管理するかの選択肢を整理する。
| アプローチ | メリット | デメリット |
|---|---|---|
| ツールごとに別フォーマットで作る | 各ツールの機能を最大活用できる | メンテナンスコストが2倍になる |
| 共通フォーマットで書き、拡張は別管理 | 一度書けば両ツールで使える | 固有機能は別ディレクトリが必要 |
| Codexのみ or Claude Codeのみに絞る | シンプル | ツールの選択肢が固定される |
結論として「共通フォーマットで書き、拡張は別管理」が最も現実的だ。その前提でフォーマット仕様を理解する必要がある。
なぜこのアプローチを選んだか
CodexとClaude Codeは、SKILL.md の必須フィールドが共通している。
---
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.
name と description の2フィールドだけが必須で、この部分は両ツールで完全に互換性がある。
Claude Code固有の機能として allowed-tools があるが、これは省略可能だ。省略すれば、Codexでもそのまま動く。
| フィールド | Codex | Claude Code | 互換性 |
|---|---|---|---|
name |
必須 | 必須 | ✅ 完全互換 |
description |
必須 | 必須 | ✅ 完全互換 |
allowed-tools |
非対応 | オプション | ⚠️ 省略で互換 |
| スキル連鎖 | 限定的 | Skill: other-skill |
⚠️ Claude Code固有 |
この構造から、「allowed-tools を省略した共通スキルを基盤にする」という判断が自然に導かれる。
実装例: ツール横断で動くスキル
---
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 を省略しているため、CodexでもClaude Codeでも動く。
Claude Code固有機能が必要な場合
allowed-tools（権限の最小化）やスキル連鎖が必要な場面では、拡張スキルを別ディレクトリで管理する。
skills/
├── lint-and-format/ ← 共通スキル（両ツールで動く）
│ └── SKILL.md
└── claude-extensions/
└── lint-and-format/
└── SKILL.md ← allowed-tools追加版
まとめ: どういう場面で使うべきか
スキルを書くときの判断基準は次の通りだ。
共通フォーマット（allowed-tools 省略）で書くケース:
- Codex / Claude Code どちらでも使いたいスキル
- チームで共有・配布したいスキル（Codex公式カタログへの登録も視野に入れる場合）
Claude Code固有構文を使うケース:
- 本番デプロイなど、権限を最小化したいスキル（
allowed-toolsを明示） - 複数スキルを連鎖させる複雑なワークフロー（
Skill: other-skill形式）
description の書き方が最もスキル起動に直結するため、Use when: と Accepts args: を明示することが最初の優先事項だ。
さらに深掘りしたい方へ
この記事ではCodex / Claude Code共通のSkill.mdフォーマット仕様と設計判断を解説しました。
Skill.md 書き方ガイド — Codex Skills と Claude Code Skills の違いと設計パターン ではさらに：
- ツール横断スキル設計の3パターン（互換性重視・プラットフォーム別拡張・参照ファイル共有）の詳細比較
- コミットメッセージ生成スキルの完全実装例（Conventional Commits対応）
- Codex公式スキルカタログ
openai/skillsのクローンと活用方法
を扱っています。
playpark について
playpark LLC - 業務自動化・AI活用・Web開発
