MENU
3DCG・ゲーム開発の知見をゆるく深く
  1. ホーム
  2. AIエージェント解説
  3. Codex
  4. Codex Skills完全ガイド｜作業手順を再利用する方法

Codex Skills完全ガイド｜作業手順を再利用する方法

Codex
Codex Skills完全ガイド｜作業手順を再利用する方法

Codexを使い続けていると、「この作業、前にも同じ流れで頼んだな」と感じる場面が増えてきます。たとえば、記事ドラフトをGutenberg形式に整える、画像発注書を作る、スプレッドシートを検証する、リリースノートを作る、特定のテスト手順を回す、といった作業です。

こうした繰り返し作業を、毎回プロンプトだけで説明するのは大変です。そこで使えるのが Codex Skills です。本記事では、Skillsとは何か、SKILL.md に何を書くのか、どこに保存するのか、AGENTS.mdやMCPとどう違うのか、どのように安全に育てるのかを初心者向けに解説します。

夕宮たいだ

ふぁ……みんな〜、今日はSkillsだよぉ。何度も使う作業手順を、Codexに覚えさせる感じで見ていこ〜。

目次

1. Skillsとは何か

ひとことで：Skillsは、Codexに再利用させる作業手順のまとまりです。

CodexのAGENTS.md、MCP、Skills、プロンプトの役割分担を示す図
図1：Skillsは繰り返す作業手順を再利用するための仕組み

Skillsは、特定の作業をうまく進めるための手順、判断基準、必要な入力、期待する出力などをまとめたものです。毎回長いプロンプトを書かなくても、Codexが「この作業ではこの手順を使えばよい」と判断しやすくなります。

OpenAI公式の Codex Skills ページでは、Skillsを作る方法として、組み込みの $skill-creator を使う方法と、フォルダに SKILL.md を作って手動で作成する方法が説明されています。つまり、Skillsの中心は SKILL.md です。

たとえば、記事制作の作業なら、次のような手順をSkill化できます。

  • 記事本文のトーンを確認する
  • Gutenberg用HTMLへ変換する
  • SEOメタディスクリプションの文字数を確認する
  • 画像発注書を作る
  • WordPress下書き登録前にバックアップを取る

Skillsは「Codexに何でも任せるための魔法」ではありません。うまくいった作業手順を、次回も同じ品質で使いやすくするための再利用パッケージです。

仕組み主な役割
AGENTS.mdプロジェクト全体のルールを伝える
MCP外部ツールやデータへ接続する
Skills繰り返す作業手順を再利用する
プロンプト今回だけの具体的な依頼を伝える
夕宮たいだ

AGENTS.mdが「このプロジェクトの約束」、MCPが「外の道具」、Skillsが「作業の手順書」って分けると、かなり見通しがよくなるよぉ。

2. Skillsが向いている作業

ひとことで：同じ手順で何度も行う作業に向いています。

Skillsが向いているのは、作業の流れがある程度決まっていて、毎回似た確認が必要なものです。単発の相談や、まだ手順が固まっていない試行錯誤には向きません。

向いている例です。

作業Skill化しやすい理由
記事ドラフト作成構成、トーン、SEO確認が毎回似ている
WordPress下書き登録バックアップ、変換、タグ設定、検証の順番が決まっている
画像発注書作成サイズ、alt、キャプション、NG指定を毎回整理する
テスト追加対象確認、既存テスト参照、実行報告の型がある
リリースノート作成差分確認、変更分類、未確認事項の整理が必要
スプレッドシート検証入力、計算、書式、出力確認の手順がある

反対に、次のような作業はSkill化を急がなくて大丈夫です。

  • 1回しか使わない調査
  • 目的がまだ曖昧な相談
  • プロジェクト全体の恒常ルール
  • 外部ツールへの接続設定そのもの
  • 秘密情報や認証情報を含む作業

判断基準は、「同じ説明を3回以上したか」です。繰り返し説明しているなら、Skill化の候補です。

3. SKILL.mdの基本構造

ひとことで：名前、説明、手順を1つのMarkdownにまとめます。

Codex SkillのSKILL.mdに書くname、description、手順、入力、出力の構造図
図2：SKILL.mdは発動条件と作業手順をセットで書く

手動でSkillを作る場合、フォルダ内に SKILL.md を作ります。公式Docsでは、先頭に name と description を含むフロントマターを書き、その下にCodexが従う手順を書く形が紹介されています。

最小例です。

---
name: article-draft
description: Use when creating a Japanese blog article draft from a brief.
---

# Article Draft Skill

Follow these steps:

1. Read the article brief.
2. Confirm the target reader and tone.
3. Draft the article with clear headings.
4. Add SEO title and meta description.
5. List any missing information.

重要なのは、description です。ここには、そのSkillを「いつ使うべきか」「いつ使うべきでないか」を具体的に書きます。説明が曖昧だと、Codexが必要ない場面でSkillを使ったり、必要な場面で見落としたりします。

本文側には、作業手順、入力として必要な情報、出力形式、注意点を書きます。最初は短く作り、実際に使いながら育てます。

夕宮たいだ

ほえ〜、Skillはまずdescriptionが大事なんだねぇ。使うタイミングが曖昧だと、手順が良くても迷っちゃうんだぁ。

4. Skillsをどこに保存するか

ひとことで：個人用、リポジトリ用、管理者用、システム用の置き場所があります。

公式Docsでは、Codexは複数の場所からSkillsを読み込むと説明されています。大きく分けると、リポジトリ、ユーザー、管理者、システムの4系統です。

スコープ置き場所の例向いている内容
Repository.agents/skillsそのリポジトリで使う作業手順
User$HOME/.agents/skills個人がどのプロジェクトでも使う手順
Admin/etc/codex/skills共有環境で配る標準手順
SystemCodexに同梱OpenAIが用意する組み込みSkills

リポジトリ内では、Codexを起動した作業ディレクトリからリポジトリルートまでの .agents/skills が探索対象になります。つまり、プロジェクト全体で使うSkillはリポジトリルートに置き、特定モジュールだけで使うSkillは近いディレクトリに置く、という設計ができます。

たとえば、次のような構成です。

project-root/
  .agents/
    skills/
      article-draft/
        SKILL.md
  apps/
    admin/
      .agents/
        skills/
          dashboard-review/
            SKILL.md

ただし、最初から階層を増やしすぎる必要はありません。初心者は、まずリポジトリ直下の .agents/skills か、個人用の $HOME/.agents/skills から始めると扱いやすいです。

5. skill-creatorで作る方法

ひとことで：最初は組み込みの $skill-creator で作るのが安全です。

公式Docsでは、Skillを作るときはまず組み込みの $skill-creator を使う方法が紹介されています。$skill-creator は、Skillが何をするのか、いつ発動するのか、手順だけでよいのか、スクリプトも含めるのかを確認しながら作成を助けます。

依頼のイメージです。

$skill-creator

日本語ブログ記事の下書きを作るSkillを作りたいです。
発注書を読み、本文、SEOメタ、画像発注仕様を作る手順を含めたいです。
最初はinstruction-onlyで作りたいです。

最初のSkillは、instruction-only、つまり手順だけのSkillがおすすめです。スクリプトや外部ツールを含めると便利ですが、検証すべきことも増えます。

Skillがうまく動くかを確認するには、そのSkillを使わせたい作業をいくつか試し、想定どおりに呼び出されるか、余計な場面で呼ばれないかを見ます。

6. instruction-onlyとスクリプト付きの違い

ひとことで：判断中心なら手順だけ、再現性が必要ならスクリプトを検討します。

Skillsは、手順だけで構成することも、スクリプトや補助ファイルを含めることもできます。公式Docsのベストプラクティスでは、決定的な処理や外部ツールが必要な場合を除き、まずは指示を優先する考え方が示されています。

使い分けの目安です。

種類向いている作業
instruction-only記事構成、レビュー観点、確認手順、判断基準
スクリプト付き変換、検証、ファイル生成、定型チェック
assets付きテンプレート、サンプル、参照画像、雛形

たとえば、記事の構成を考えるSkillは手順だけで十分です。一方、MarkdownをGutenbergブロックへ変換する、スプレッドシートを検証する、画像の形式をチェックする、といった作業はスクリプトを含める価値があります。

ただし、スクリプト付きSkillでは、実行権限、入力ファイル、出力先、失敗時の扱いを明確にします。Codexが何を実行するのか、人間がレビューできる状態にしておくことが大切です。

夕宮たいだ

スクリプト付きは強いけど、そのぶん確認も必要だよぉ。最初は手順だけで作って、必要になったら足すくらいが安心だねぇ。

7. AGENTS.md・MCP・Skillsの使い分け

ひとことで：ルール、外部接続、作業手順を混ぜないようにします。

ここまでの第2期記事で、AGENTS.md、MCP、Skillsを扱ってきました。3つは似て見えますが、役割は違います。

仕組み書くもの例
AGENTS.md常に守るプロジェクトルールテストコマンド、禁止事項、文体
MCP外部ツールへの接続設定Figma、Docs、Sentry、GitHub
Skills繰り返す作業手順記事作成、レビュー、変換、検証

記事制作を例にすると、次のように分けられます。

  • AGENTS.md：本文はです・ます調、ふきだしはゆるい口調、公開前に人間レビュー
  • MCP：WordPressやDocs、ブラウザ確認など外部ツールへの接続
  • Skill：発注書を読み、本文、SEOメタ、画像仕様、Gutenberg HTMLを作る手順
  • プロンプト：今回はCX-09の記事を作成してください

この分担ができると、Codexへの依頼がかなり安定します。何でも1つの場所に入れず、役割ごとに分けるのがコツです。

8. 目的別のSkill例

ひとことで：作業の入力と出力が明確なものからSkill化します。

Skillは、抽象的な作業よりも、入力と出力がはっきりしている作業から作ると成功しやすいです。

記事制作Skillの例です。

## Inputs

- Article brief
- Target keyword
- Series position

## Output

- Draft body
- SEO title and meta description
- Image brief
- Pre-publish checklist

## Rules

- Keep the body explanatory.
- Keep character dialogue soft.
- Do not invent official product details.

コードレビューSkillの例です。

## Review focus

1. Bugs and regressions
2. Missing tests
3. Security and permission risks
4. Maintainability issues

Report findings first.
Avoid style-only comments unless they affect behavior.

スプレッドシート検証Skillの例です。

## Spreadsheet QA

- Check formulas before formatting.
- Verify totals against source data.
- Render a preview when layout matters.
- Report any assumptions that could affect numbers.

このように、Skillには「何を入力として受け取り、何を出力するか」を書くと安定します。作業の型が決まるほど、再利用しやすくなります。

9. Skillsを有効化・無効化する

ひとことで：使わないSkillは削除せず、設定で無効化できます。

公式Docsでは、~/.codex/config.toml の [[skills.config]] を使って、Skillを削除せず無効化する方法が紹介されています。

例です。

[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

使わなくなったSkillを放置すると、Codexが必要ない場面で候補にしてしまうことがあります。特に、古いプロジェクト用のSkill、検証中のSkill、チームで合意していないSkillは、必要に応じて無効化します。

Skillを更新したあと反映されない場合は、Codexを再起動して確認します。公式Docsでも、更新が表示されない場合は再起動する流れが案内されています。

夕宮たいだ

古いSkillが残ってると、意図しない手順で動いちゃうことがあるよぉ。使わないものは無効化して、見通しよくしておこうねぇ。

10. Skillsを配布する方法

ひとことで：ローカル共有ならフォルダ、広く配るならプラグインを検討します。

公式Docsでは、直接Skillフォルダを置く方法はローカル作成やリポジトリ単位のワークフローに向いている一方、複数のSkillをまとめて配布したい場合や、アプリ連携と一緒に配りたい場合はプラグインとしてまとめる考え方が示されています。

初心者は、まず次の順番で考えると分かりやすいです。

  1. 自分だけが使うなら $HOME/.agents/skills
  2. そのリポジトリのチームで使うなら .agents/skills
  3. 複数プロジェクトに配るならプラグイン化を検討

チームでSkillを共有する場合は、SKILL.md もレビュー対象にします。作業手順が変わるということは、Codexの出力や検証方法も変わるためです。

また、Skillにスクリプトを含める場合は、誰がメンテナンスするか、実行前に何を確認するか、失敗したときにどう報告するかを決めておきます。

11. Skillsを育てるチェックリスト

ひとことで：使うたびに、説明・入力・出力・安全条件を見直します。

Codex Skillsを実務で使いながらSKILL.mdを更新して改善するループ図
図3：Skillsは実務で使いながら少しずつ育てる

Skillは、一度作って終わりではありません。実際に使ってみて、Codexが迷ったところ、出力がぶれたところ、人間が毎回補足しているところを更新していきます。

更新時のチェックリストです。

  • description は発動条件を具体的に書けているか
  • 使わない場面も説明できているか
  • 入力として必要な情報が明確か
  • 出力形式が具体的か
  • 作業の完了条件が書かれているか
  • スクリプトを実行する場合、入力と出力が明確か
  • 秘密情報や認証情報を書いていないか
  • AGENTS.mdやMCPに書くべき内容を混ぜていないか

Skillの改善は、失敗したプロンプトを責める作業ではありません。むしろ、よく使う作業の知識をチームや未来の自分のために残す作業です。

夕宮たいだ

うまくいった作業をSkillにしておくと、次の自分が助かるんだぁ。ちょっとした未来の引き継ぎだねぇ。

12. 次に読む記事

ひとことで：手順を再利用できたら、次は複数エージェントで分担する方法へ進みます。

本記事では、Codex Skillsについて、役割、SKILL.md の基本構造、保存場所、$skill-creator、instruction-onlyとスクリプト付きの違い、AGENTS.md・MCPとの使い分け、無効化や配布、育て方を解説しました。

次に読む記事は、CX-10「Codex Subagents入門｜複数エージェントで並列作業する方法」です。Skillsが作業手順を再利用する仕組みだとすると、Subagentsは複数のエージェントに調査、実装、レビューなどを分担させる考え方です。

公式情報としては、Agent Skills、Codex Best practices、Model Context Protocol を確認しておくと、Skillsと他の仕組みの役割分担を整理しやすくなります。

夕宮たいだ

ふぁ……これで作業手順も再利用しやすくなったねぇ。次は、複数のCodexに役割分担してもらう話に進もう〜。

この記事とあわせて読みたいCodex記事

ひとことで：この記事の理解を深めるための関連回です。

Codexシリーズ記事一覧

ひとことで：Codex編は、導入から専門機能まで順番に読めるシリーズです。

Codex
中級者向け 自動化
よかったらシェアしてね！
  • URLをコピーしました！
  • URLをコピーしました！

この記事を書いた人

怠惰のアバター 怠惰

関連記事

目次