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
1# プロジェクトスキル
2mkdir -p .codex/skills/my-skill-name
3
4# グローバルスキル
5mkdir -p ~/.codex/skills/my-skill-name

Step 2: SKILL.md の作成

yaml
1---
2name: skill-identifier
3description: スキルの説明と使用タイミング。Use when [トリガーシナリオ].
4---
5
6# スキル名
7
8スキルの概要説明
9
10## When to Use This Skill
11
12- 使用シナリオ1
13- 使用シナリオ2
14
15## Instructions
16
171. ステップ1
182. ステップ2
19
20## Examples
21
22### 例1
23[具体例]

Step 3: 有効化確認

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

YAML Frontmatter 仕様

必須フィールド

name の命名規則

yaml
1# ✅ 良い例
2name: error-analyzer
3name: api-docs-writer
4name: db-migration-helper
5
6# ❌ 悪い例
7name: Error_Analyzer      # 大文字・アンダースコアNG
8name: my skill            # スペースNG
9name: スキル名             # 日本語NG

description のベストプラクティス

yaml
1# ✅ 良い例: 具体的でトリガーキーワードが豊富
2description: エラー/スタックトレース/ログを解析し、原因の切り分けと最小修正案、確認手順を提示する。Use when debugging errors, analyzing stack traces, or troubleshooting issues.
3
4# ✅ 良い例: 何をするか＋いつ使うかが明確
5description: CSV/TSV/JSONを要約して洞察を返すスキル。Use when analyzing data, summarizing CSV files, or working with tabular data.
6
7# ❌ 悪い例: 抽象的すぎる
8description: データ処理を手伝う
9
10# ❌ 悪い例: いつ使うかが不明
11description: このスキルはデータベースマイグレーションとスキーマ変更を処理します

推奨スキル構成

markdown
1---
2name: my-skill-name
3description: [機能説明]。Use when [使用シナリオ].
4---
5
6# スキル名
7
8簡潔な概要説明
9
10## When to Use This Skill
11
12- シナリオ1
13- シナリオ2
14- シナリオ3
15
16## 手順 / Instructions
17
18### Step 1: [ステップ名]
19[説明]
20
21### Step 2: [ステップ名]
22[説明]
23
24## Examples
25
26### 例1: [シナリオ]
27```[言語]
28[コード例]

Context / 補足情報

• 前提条件
• 制約事項

AI Assistant Instructions

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

1. まず〇〇を確認
2. 次に〇〇を実行
3. 最後に〇〇を提示

Always:

• 〇〇する
• 〇〇する

Never:

• 〇〇しない
• 〇〇しない

---

## スクリプトの活用

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

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

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

python
1# scripts/analyze.py
2#!/usr/bin/env python3
3import json
4import sys
5
6def main():
7    # 分析ロジック
8    result = {"status": "ok"}
9    print(json.dumps(result, indent=2))
10
11if __name__ == "__main__":
12    main()

SKILL.mdからの参照

markdown
1## 使用方法
2
3セットアップを実行:
4```bash
5bash scripts/setup.sh

分析を実行:

bash
1python3 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
1---
2name: doc-generator
3description: コードからドキュメントを自動生成する。Use when creating API docs, README files, or code comments.
4---
5
6# Document Generator
7
8## Instructions
9
101. 対象コードを読み込む
112. 構造を分析
123. テンプレートに沿ってドキュメント生成
134. 出力形式を確認

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

yaml
1---
2name: deploy-helper
3description: デプロイ手順をガイドする。Use when deploying to production, staging, or running release processes.
4---
5
6# Deploy Helper
7
8## Instructions
9
101. 現在のブランチ・状態を確認
112. チェックリストを提示
123. 各ステップを順番に実行
134. 結果を確認

トラブルシューティング

スキルが起動しない

原因1: features.skills が無効

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

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

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

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

yaml
1# ✅ 正しい形式
2---
3name: my-skill
4description: 説明文
5---
6
7# ❌ デリミタがない
8name: my-skill
9description: 説明文
10
11# ❌ タブを使用（スペースを使う）
12---
13name:	my-skill  # タブNG
14---

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

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

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

対策:

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

ベストプラクティス

1. 1スキル = 1機能

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

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

2. 具体例を含める

markdown
1## Examples
2
3### 例: TypeScriptの型エラー
4
5入力:

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

出力:

原因

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

修正案

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

3. コンテキストを節約

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

4. 明確な指示を書く

markdown
1## AI Assistant Instructions
2
31. **最初に**: 入力を確認し、不足があれば質問
42. **次に**: 分析を実行
53. **最後に**: 結果を構造化して出力
6
7Always:
8- ファイルパスと行番号を明示
9- 実行可能なコードを提供
10
11Never:
12- 推測だけで回答しない
13- 機密情報をログに出力しない

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

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

• ディレクトリ: .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
1---
2name: my-skill
3description: [何をするか]。Use when [いつ使うか].
4---
5
6# スキル名
7
8## When to Use This Skill
9- シナリオ1
10
11## Instructions
121. ステップ1
132. ステップ2
14
15## AI Assistant Instructions
16このスキルが起動されたら:
171. [指示]

フル構成

markdown
1---
2name: my-skill
3description: [詳細な説明]。Use when [シナリオ1], [シナリオ2], or [キーワード].
4---
5
6# スキル名
7
8概要説明
9
10## When to Use This Skill
11- シナリオ1
12- シナリオ2
13- シナリオ3
14
15## 前提条件
16- 必要な環境
17- 依存関係
18
19## Instructions
20
21### Step 1: [ステップ名]
22[説明]
23
24### Step 2: [ステップ名]
25[説明]
26
27## Examples
28
29### 例1: [シナリオ]
30```[言語]
31[コード]

Output Format

[出力フォーマット]

Context

• 補足情報
• 制約事項

AI Assistant Instructions

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

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

Always:

• [必須事項]

Never:

• [禁止事項]

関連リソース

• [リンク]