Codex Skill Generator

Codex CLI用のスキル作成ガイド。YAML frontmatter、ディレクトリ構造、ベストプラクティスを解説。Use when creating new Codex skills, updating existing skills, or learning about Codex skill development.

majiayu000 1438f6a 2 files · 11.4 KB Updated Sep 9, 2026 567 repo stars

Coding & Dev Tools

Install

Press C to copy

$ npx skillmds add majiayu000/codex-skill-generator

Installs into ~/.claude/skills (or .claude/skills inside a project). Restart Claude Code to pick it up.

＋ Add to collection

README badge

[![SkillMD](https://skillmd.com/badge/majiayu000/codex-skill-generator.svg)](https://skillmd.com/skills/majiayu000/codex-skill-generator)

Trust & safety

Audits pending

Not yet audited · commit 1438f6a

Permissions this skill uses

Documentation only
No scripts, network access, or credentials are involved.

Works with: Claude Code Claude.ai OpenAI Codex +

File contents

Codex Skill Generator

Codex CLI用の効果的なスキルを作成するためのガイドです。

When to Use This Skill

新しいCodexスキルを作成する時
既存のスキルを更新する時
スキルの構造やベストプラクティスを学びたい時
スキルが正しく動作しない時のトラブルシューティング

スキルとは？

スキルはCodex CLIの機能を拡張するための組織化されたフォルダです。指示、リファレンス、スクリプトを含むことができます。

特徴:

モデル呼び出し型（ユーザーのリクエストに基づいて自動的に起動）
プロジェクト固有またはグローバルに配置可能
再利用可能なワークフロー・知識を定義

ディレクトリ構造

配置場所

# グローバルスキル（全プロジェクトで使用可能）
~/.codex/skills/skill-name/SKILL.md

# プロジェクトスキル（リポジトリ内で使用）
.codex/skills/skill-name/SKILL.md

基本構造

skill-name/
├── SKILL.md              # メインスキルファイル（必須）
├── scripts/              # ユーティリティスクリプト（オプション）
│   ├── setup.sh
│   └── analyze.py
├── templates/            # テンプレートファイル（オプション）
│   └── template.md
└── reference.md          # 追加リファレンス（オプション）

スキルの作成手順

Step 1: ディレクトリ作成

# プロジェクトスキル
mkdir -p .codex/skills/my-skill-name

# グローバルスキル
mkdir -p ~/.codex/skills/my-skill-name

Step 2: SKILL.md の作成

---
name: skill-identifier
description: スキルの説明と使用タイミング。Use when [トリガーシナリオ].
---

# スキル名

スキルの概要説明

## When to Use This Skill

- 使用シナリオ1
- 使用シナリオ2

## Instructions

1. ステップ1
2. ステップ2

## Examples

### 例1
[具体例]

Step 3: 有効化確認

# ~/.codex/config.toml
[features]
skills = true

YAML Frontmatter 仕様

必須フィールド

フィールド	説明	制約
`name`	スキル識別子	小文字、数字、ハイフンのみ。最大64文字
`description`	スキルの説明	最大1024文字。トリガーキーワードを含める

name の命名規則

# ✅ 良い例
name: error-analyzer
name: api-docs-writer
name: db-migration-helper

# ❌ 悪い例
name: Error_Analyzer      # 大文字・アンダースコアNG
name: my skill            # スペースNG
name: スキル名             # 日本語NG

description のベストプラクティス

# ✅ 良い例: 具体的でトリガーキーワードが豊富
description: エラー/スタックトレース/ログを解析し、原因の切り分けと最小修正案、確認手順を提示する。Use when debugging errors, analyzing stack traces, or troubleshooting issues.

# ✅ 良い例: 何をするか＋いつ使うかが明確
description: CSV/TSV/JSONを要約して洞察を返すスキル。Use when analyzing data, summarizing CSV files, or working with tabular data.

# ❌ 悪い例: 抽象的すぎる
description: データ処理を手伝う

# ❌ 悪い例: いつ使うかが不明
description: このスキルはデータベースマイグレーションとスキーマ変更を処理します

推奨スキル構成

---
name: my-skill-name
description: [機能説明]。Use when [使用シナリオ].
---

# スキル名

簡潔な概要説明

## When to Use This Skill

- シナリオ1
- シナリオ2
- シナリオ3

## 手順 / Instructions

### Step 1: [ステップ名]
[説明]

### Step 2: [ステップ名]
[説明]

## Examples

### 例1: [シナリオ]
```[言語]
[コード例]

Context / 補足情報

前提条件
制約事項

AI Assistant Instructions

このスキルが起動されたら:

まず〇〇を確認
次に〇〇を実行
最後に〇〇を提示

Always:

〇〇する
〇〇する

Never:

〇〇しない
〇〇しない


---

## スクリプトの活用

### シェルスクリプト（単純な操作向け）

```bash
# scripts/setup.sh
#!/bin/bash
echo "Setting up environment..."
npm install

Pythonスクリプト（複雑なロジック向け）

# scripts/analyze.py
#!/usr/bin/env python3
import json
import sys

def main():
    # 分析ロジック
    result = {"status": "ok"}
    print(json.dumps(result, indent=2))

if __name__ == "__main__":
    main()

SKILL.mdからの参照

## 使用方法

セットアップを実行:
```bash
bash scripts/setup.sh

分析を実行:

python3 scripts/analyze.py <path>


---

## スキルパターン

### パターン1: 分析スキル

```yaml
---
name: code-analyzer
description: コードを分析し、問題点と改善案を提示する。Use when reviewing code, finding bugs, or improving code quality.
---

# Code Analyzer

## Instructions

1. 対象ファイル/ディレクトリを確認
2. 分析観点を明確化
3. 問題点を優先度順にリスト化
4. 具体的な修正案を提示

パターン2: 生成スキル

---
name: doc-generator
description: コードからドキュメントを自動生成する。Use when creating API docs, README files, or code comments.
---

# Document Generator

## Instructions

1. 対象コードを読み込む
2. 構造を分析
3. テンプレートに沿ってドキュメント生成
4. 出力形式を確認

パターン3: ワークフロースキル

---
name: deploy-helper
description: デプロイ手順をガイドする。Use when deploying to production, staging, or running release processes.
---

# Deploy Helper

## Instructions

1. 現在のブランチ・状態を確認
2. チェックリストを提示
3. 各ステップを順番に実行
4. 結果を確認

トラブルシューティング

スキルが起動しない

原因1: features.skills が無効

# ~/.codex/config.toml
[features]
skills = true  # ← 確認

原因2: ファイル名が間違っている

✅ SKILL.md（大文字）
❌ skill.md
❌ Skill.md

原因3: YAML frontmatter の構文エラー

# ✅ 正しい形式
---
name: my-skill
description: 説明文
---

# ❌ デリミタがない
name: my-skill
description: 説明文

# ❌ タブを使用（スペースを使う）
---
name:	my-skill  # タブNG
---

原因4: description にトリガーキーワードがない

ユーザーが使う言葉をdescriptionに含める
「Use when」で使用シナリオを明示

スキルが意図しないタイミングで起動する

対策:

descriptionをより具体的にする
他のスキルとキーワードが重複していないか確認

ベストプラクティス

1. 1スキル = 1機能

✅ error-analyzer: エラー解析専用
✅ doc-generator: ドキュメント生成専用

❌ dev-helper: 何でもやる（曖昧）

2. 具体例を含める

## Examples

### 例: TypeScriptの型エラー

入力:

error TS2339: Property 'foo' does not exist on type 'Bar'


出力:

原因

Bar 型に foo プロパティが定義されていません

修正案

interface Bar に foo を追加
または foo へのアクセスを削除

3. コンテキストを節約

基本的な説明は省略（Codexは既に知っている）
500行以下を目安に
詳細情報は別ファイルに分離

4. 明確な指示を書く

## AI Assistant Instructions

1. **最初に**: 入力を確認し、不足があれば質問
2. **次に**: 分析を実行
3. **最後に**: 結果を構造化して出力

Always:
- ファイルパスと行番号を明示
- 実行可能なコードを提供

Never:
- 推測だけで回答しない
- 機密情報をログに出力しない

クイックリファレンス: チェックリスト

新しいスキルを作成したら確認:

ディレクトリ: .codex/skills/skill-name/ または ~/.codex/skills/skill-name/
ファイル名: SKILL.md（大文字）
YAML frontmatter: --- で囲まれている
name: 小文字・ハイフンのみ、64文字以内
description: 機能＋使用シナリオ、トリガーキーワード含む
「When to Use」セクションがある
具体的な手順・例がある
AI Assistant Instructions がある
features.skills = true が有効

テンプレート

最小構成

---
name: my-skill
description: [何をするか]。Use when [いつ使うか].
---

# スキル名

## When to Use This Skill
- シナリオ1

## Instructions
1. ステップ1
2. ステップ2

## AI Assistant Instructions
このスキルが起動されたら:
1. [指示]

フル構成

---
name: my-skill
description: [詳細な説明]。Use when [シナリオ1], [シナリオ2], or [キーワード].
---

# スキル名

概要説明

## When to Use This Skill
- シナリオ1
- シナリオ2
- シナリオ3

## 前提条件
- 必要な環境
- 依存関係

## Instructions

### Step 1: [ステップ名]
[説明]

### Step 2: [ステップ名]
[説明]

## Examples

### 例1: [シナリオ]
```[言語]
[コード]

Output Format

[出力フォーマット]

Context

補足情報
制約事項

AI Assistant Instructions

このスキルが起動されたら:

[指示1]
[指示2]
[指示3]

Always:

[必須事項]

Never:

[禁止事項]

関連リソース

[リンク]

---name: codex-skill-generatordescription: Codex CLI用のスキル作成ガイド。YAML frontmatter、ディレクトリ構造、ベストプラクティスを解説。Use when creating new Codex skills, updating existing skills, or learning about Codex skill development.--- # Codex Skill Generator Codex CLI用の効果的なスキルを作成するためのガイドです。 ## When to Use This Skill - 新しいCodexスキルを作成する時 - 既存のスキルを更新する時 - スキルの構造やベストプラクティスを学びたい時 - スキルが正しく動作しない時のトラブルシューティング --- ## スキルとは？スキルはCodex CLIの機能を拡張するための組織化されたフォルダです。指示、リファレンス、スクリプトを含むことができます。 **特徴:** - モデル呼び出し型（ユーザーのリクエストに基づいて自動的に起動） - プロジェクト固有またはグローバルに配置可能 - 再利用可能なワークフロー・知識を定義 --- ## ディレクトリ構造 ### 配置場所 ``` # グローバルスキル（全プロジェクトで使用可能） ~/.codex/skills/skill-name/SKILL.md # プロジェクトスキル（リポジトリ内で使用） .codex/skills/skill-name/SKILL.md ``` ### 基本構造 ``` skill-name/ ├── SKILL.md # メインスキルファイル（必須） ├── scripts/ # ユーティリティスクリプト（オプション） │ ├── setup.sh │ └── analyze.py ├── templates/ # テンプレートファイル（オプション） │ └── template.md └── reference.md # 追加リファレンス（オプション） ``` --- ## スキルの作成手順 ### Step 1: ディレクトリ作成 ```bash # プロジェクトスキル mkdir -p .codex/skills/my-skill-name # グローバルスキル mkdir -p ~/.codex/skills/my-skill-name ``` ### Step 2: SKILL.md の作成 ```yaml --- name: skill-identifier description: スキルの説明と使用タイミング。Use when [トリガーシナリオ]. --- # スキル名スキルの概要説明 ## When to Use This Skill - 使用シナリオ1 - 使用シナリオ2 ## Instructions 1. ステップ1 2. ステップ2 ## Examples ### 例1 [具体例] ``` ### Step 3: 有効化確認 ```toml # ~/.codex/config.toml [features] skills = true ``` --- ## YAML Frontmatter 仕様 ### 必須フィールド | フィールド | 説明 | 制約 | |-----------|------|------| | `name` | スキル識別子 | 小文字、数字、ハイフンのみ。最大64文字 | | `description` | スキルの説明 | 最大1024文字。トリガーキーワードを含める | ### name の命名規則 ```yaml # ✅ 良い例 name: error-analyzer name: api-docs-writer name: db-migration-helper # ❌ 悪い例 name: Error_Analyzer # 大文字・アンダースコアNG name: my skill # スペースNG name: スキル名 # 日本語NG ``` ### description のベストプラクティス ```yaml # ✅ 良い例: 具体的でトリガーキーワードが豊富 description: エラー/スタックトレース/ログを解析し、原因の切り分けと最小修正案、確認手順を提示する。Use when debugging errors, analyzing stack traces, or troubleshooting issues. # ✅ 良い例: 何をするか＋いつ使うかが明確 description: CSV/TSV/JSONを要約して洞察を返すスキル。Use when analyzing data, summarizing CSV files, or working with tabular data. # ❌ 悪い例: 抽象的すぎる description: データ処理を手伝う # ❌ 悪い例: いつ使うかが不明 description: このスキルはデータベースマイグレーションとスキーマ変更を処理します ``` --- ## 推奨スキル構成 ```markdown --- name: my-skill-name description: [機能説明]。Use when [使用シナリオ]. --- # スキル名簡潔な概要説明 ## When to Use This Skill - シナリオ1 - シナリオ2 - シナリオ3 ## 手順 / Instructions ### Step 1: [ステップ名] [説明] ### Step 2: [ステップ名] [説明] ## Examples ### 例1: [シナリオ] ```[言語] [コード例] ``` ## Context / 補足情報 - 前提条件 - 制約事項 ## AI Assistant Instructions このスキルが起動されたら: 1. まず〇〇を確認 2. 次に〇〇を実行 3. 最後に〇〇を提示 Always: - 〇〇する - 〇〇する Never: - 〇〇しない - 〇〇しない ``` --- ## スクリプトの活用 ### シェルスクリプト（単純な操作向け） ```bash # scripts/setup.sh #!/bin/bash echo "Setting up environment..." npm install ``` ### Pythonスクリプト（複雑なロジック向け） ```python # scripts/analyze.py #!/usr/bin/env python3 import json import sys def main(): # 分析ロジック result = {"status": "ok"} print(json.dumps(result, indent=2)) if __name__ == "__main__": main() ``` ### SKILL.mdからの参照 ```markdown ## 使用方法セットアップを実行: ```bash bash scripts/setup.sh ``` 分析を実行: ```bash python3 scripts/analyze.py <path> ``` ``` --- ## スキルパターン ### パターン1: 分析スキル ```yaml --- name: code-analyzer description: コードを分析し、問題点と改善案を提示する。Use when reviewing code, finding bugs, or improving code quality. --- # Code Analyzer ## Instructions 1. 対象ファイル/ディレクトリを確認 2. 分析観点を明確化 3. 問題点を優先度順にリスト化 4. 具体的な修正案を提示 ``` ### パターン2: 生成スキル ```yaml --- name: doc-generator description: コードからドキュメントを自動生成する。Use when creating API docs, README files, or code comments. --- # Document Generator ## Instructions 1. 対象コードを読み込む 2. 構造を分析 3. テンプレートに沿ってドキュメント生成 4. 出力形式を確認 ``` ### パターン3: ワークフロースキル ```yaml --- name: deploy-helper description: デプロイ手順をガイドする。Use when deploying to production, staging, or running release processes. --- # Deploy Helper ## Instructions 1. 現在のブランチ・状態を確認 2. チェックリストを提示 3. 各ステップを順番に実行 4. 結果を確認 ``` --- ## トラブルシューティング ### スキルが起動しない **原因1: features.skills が無効** ```toml # ~/.codex/config.toml [features] skills = true # ← 確認 ``` **原因2: ファイル名が間違っている** ``` ✅ SKILL.md（大文字） ❌ skill.md ❌ Skill.md ``` **原因3: YAML frontmatter の構文エラー** ```yaml # ✅ 正しい形式 --- name: my-skill description: 説明文 --- # ❌ デリミタがない name: my-skill description: 説明文 # ❌ タブを使用（スペースを使う） --- name: my-skill # タブNG --- ``` **原因4: description にトリガーキーワードがない** - ユーザーが使う言葉をdescriptionに含める - 「Use when」で使用シナリオを明示 ### スキルが意図しないタイミングで起動する **対策:** - descriptionをより具体的にする - 他のスキルとキーワードが重複していないか確認 --- ## ベストプラクティス ### 1. 1スキル = 1機能 ``` ✅ error-analyzer: エラー解析専用 ✅ doc-generator: ドキュメント生成専用 ❌ dev-helper: 何でもやる（曖昧） ``` ### 2. 具体例を含める ```markdown ## Examples ### 例: TypeScriptの型エラー入力: ``` error TS2339: Property 'foo' does not exist on type 'Bar' ``` 出力: ``` ## 原因 `Bar` 型に `foo` プロパティが定義されていません ## 修正案 1. interface Bar に foo を追加 2. または foo へのアクセスを削除 ``` ``` ### 3. コンテキストを節約 - 基本的な説明は省略（Codexは既に知っている） - 500行以下を目安に - 詳細情報は別ファイルに分離 ### 4. 明確な指示を書く ```markdown ## AI Assistant Instructions 1. **最初に**: 入力を確認し、不足があれば質問 2. **次に**: 分析を実行 3. **最後に**: 結果を構造化して出力 Always: - ファイルパスと行番号を明示 - 実行可能なコードを提供 Never: - 推測だけで回答しない - 機密情報をログに出力しない ``` --- ## クイックリファレンス: チェックリスト新しいスキルを作成したら確認: - [ ] ディレクトリ: `.codex/skills/skill-name/` または `~/.codex/skills/skill-name/` - [ ] ファイル名: `SKILL.md`（大文字） - [ ] YAML frontmatter: `---` で囲まれている - [ ] `name`: 小文字・ハイフンのみ、64文字以内 - [ ] `description`: 機能＋使用シナリオ、トリガーキーワード含む - [ ] 「When to Use」セクションがある - [ ] 具体的な手順・例がある - [ ] AI Assistant Instructions がある - [ ] `features.skills = true` が有効 --- ## テンプレート ### 最小構成 ```markdown --- name: my-skill description: [何をするか]。Use when [いつ使うか]. --- # スキル名 ## When to Use This Skill - シナリオ1 ## Instructions 1. ステップ1 2. ステップ2 ## AI Assistant Instructions このスキルが起動されたら: 1. [指示] ``` ### フル構成 ```markdown --- name: my-skill description: [詳細な説明]。Use when [シナリオ1], [シナリオ2], or [キーワード]. --- # スキル名概要説明 ## When to Use This Skill - シナリオ1 - シナリオ2 - シナリオ3 ## 前提条件 - 必要な環境 - 依存関係 ## Instructions ### Step 1: [ステップ名] [説明] ### Step 2: [ステップ名] [説明] ## Examples ### 例1: [シナリオ] ```[言語] [コード] ``` ## Output Format ``` [出力フォーマット] ``` ## Context - 補足情報 - 制約事項 ## AI Assistant Instructions このスキルが起動されたら: 1. [指示1] 2. [指示2] 3. [指示3] Always: - [必須事項] Never: - [禁止事項] ## 関連リソース - [リンク] ```

majiayu000/claude-skill-registry-data/tree/main/data/codex-skill-generator commit 1438f6abb7

Frequently asked questions

npx skillmds add majiayu000/codex-skill-generator