CodexのSkillsとは?繰り返す開発手順をSKILL.mdにまとめて再利用する方法

Codexでプログラムの修正を頼むとき、「最初に既存コードを調べて」「変更するファイルを一覧にして」「修正後はテストを実行して」と、毎回同じ指示を書くことがあります。指示を書き忘れると、ある日はテストまで行い、別の日は修正だけで終わる、というように作業の質がそろいません。

そこで調べたのが、CodexのSkills(スキル)です。この記事では、仕組みの基本と、SKILL.mdの書き方、広告分析システムなどでの使いどころを整理します。

この記事で分かること

  • CodexのSkillsの仕組みと、プロンプト・AGENTS.mdとの違い
  • SKILL.mdの基本的な書き方と呼び出し方
  • 最初に作るSkillの選び方と注意点
目次

CodexのSkillsとは

Skillsは、特定の仕事の手順や判断基準をまとめて、AIが必要なときに読めるようにしておく仕組みです。OpenAIの公式ドキュメントでは、「SKILL.mdというファイルを入れたフォルダ」が1つのSkillと説明されています。必要に応じて、参考資料(references)や、決まった処理を行うプログラム(scripts)も一緒に入れられます。

注意したいのは、SkillsはAIに新しい知識を覚えさせる仕組みではない、という点です。決めておいた手順を、仕事のたびに読み込んで使う「再利用できる業務マニュアル」と考えると分かりやすいです。

方法役割例
プロンプト今回の仕事を指示するCPAの計算機能を追加して
AGENTS.mdプロジェクト全体で守るルール重要な変更は承認を得る
Skills特定の仕事の手順を使い回すコードレビューの進め方

たとえば広告分析システムなら、AGENTS.mdには「既存機能を壊さない」「認証情報を公開しない」といった共通ルールを書き、レビューの確認項目やテストの方法はSkillに書く、という分け方ができます。

SKILL.mdの書き方

SKILL.mdの冒頭には、name(名前)とdescription(説明)を必ず書きます。その下に、目的・手順・守るルール・出力の形を書きます。最初はSKILL.mdだけで十分です。

---
name: python-code-review
description: Pythonコードの変更内容、既存機能への影響、テスト状況を確認するレビュー手順。
---

# 目的
変更内容を確認し、既存機能への悪影響を見つける。

# 手順
1. 変更されたファイルを確認する
2. 既存機能への影響を調べる
3. 既存テストを実行する
4. 必要な追加テストを提案する

# ルール
- レビュー中はコードを変更しない
- 確認できた事実と推測を分ける
- 実行していないテストを成功扱いしない

# 出力
変更内容/問題点/テスト結果/修正提案/未確認事項

特に大事なのがdescriptionです。公式ドキュメントによると、Codexは最初に各Skillの名前と説明だけを読み、使うと決めたときに本文を読み込みます。依頼内容が説明と合えば自動で選ばれることもあるため、「どんな仕事で使うか」が一目で分かる説明にします。

置き場所と呼び出し方

公式ドキュメントでは、プロジェクト用のSkillはリポジトリ内の「.agents/skills」、自分用のSkillはホームフォルダの「.agents/skills」に置くと説明されています。CLIやIDE拡張では、「$」に続けてSkill名を書くか、「/skills」で一覧から選んで呼び出します。

$python-code-review を使って、今回変更したPythonコードをレビューしてください。
特に既存のKPI計算機能への影響を確認してください。

自動で選ばれる仕組みもありますが、最初は名前を指定して呼び出し、想定した手順で動くかを確かめるほうが分かりやすいと考えています。また、Codexには「skill-creator」というSkillを作るためのSkillが最初から入っていて、何をするSkillか、いつ使うかを質問しながら下書きを作れます。

最初に作るSkillの選び方

Skillにする候補は、何度も繰り返している仕事です。一度しか行わない作業なら、通常のプロンプトで十分です。広告やデータ分析の仕事なら、次のような例が考えられます。

Skillの例中身
変更前チェック既存コード・変更対象・影響範囲・テストの有無を調べる
広告CSVの品質確認必要な列・日付の形式・数値に文字が混ざっていないか・重複・欠損を確認する
API追加前の調査認証方式・権限・取得できるデータ・利用制限・保存先の形を調べる

似たSkillをたくさん作ると、どれを使えばよいか分かりにくくなり、同じルールを複数の場所で直す手間も増えます。まずは「変更前チェック」「実装後テスト」「コードレビュー」の3つ程度から始め、使いながら足していく方法が取り組みやすそうです。

なお、私はCodexではまだSkillを作っていませんが、Claude Codeでは同じ考え方のSkillを、LPの分析や広告クリエイティブの記録などに使っています。追記を重ねると内容がずれてくるため、毎月1回点検する運用にしています。

使うときの注意点

1つ目は、手順どおりに動くとは限らないことです。AIが手順を誤って読み取ることもあるため、結果は人間が確かめます。重要な変更では、Gitやバックアップ、テスト、人間の承認と組み合わせます。

2つ目は、古い情報を残さないことです。APIの仕様などは変わるため、仕様そのものを書き込むより「公式資料を確認する」という手順を書いておくほうが安全です。

3つ目は、中身の確認です。パスワードやAPIキーはSkillに書きません。また、外部で公開されているSkillを使う場合は、危険なコマンドや操作が含まれていないか、事前に中身を読みます。

※記事作成時点(2026年11月)の情報です。機能や置き場所は変わることがあるため、最新の情報はOpenAIの公式ドキュメントをご確認ください。

まとめ

CodexのSkillsは、繰り返す仕事の手順をSKILL.mdにまとめ、必要なときにAIへ読ませる仕組みです。毎回の指示の書き忘れを防ぎ、作業の質をそろえる助けになります。

大切なのは、Skillを増やすことより、実際の仕事で見つかった漏れや失敗を手順に書き足していくことです。まずは繰り返している仕事を1つ選んでSkillにし、使いながら直していく、という順番で考えています。

よかったらシェアしてね!
  • URLをコピーしました!
  • URLをコピーしました!

この記事を書いた人

目次