Codexに「自分の仕事のルール」を覚えさせるSkills機能を、まだ使っていないなら損している

Codexを使っていて、こんな経験はないだろうか。

「いつも最初に説明することが決まっている。コーディング規約、プロジェクトの構造、コミットメッセージのフォーマット。毎回同じことをCodexに伝えるのが、地味に面倒だ」

または「チームメンバーに同じ使い方を共有したいが、各自が異なる指示を出していて品質がバラバラになっている」という悩みを持つ人もいるかもしれない。

この問題を解決するのがCodexの「Skills」機能だ。一言で言えば、「Codexに自分の仕事のルールを覚えさせて、毎回呼び出せるようにする仕組み」だ。

結論から言うと、「Skillsを設定してから、繰り返しの指示を書く時間がほぼゼロになった。さらにチームの暗黙知をCodexに渡せるようになった」というのが、使い始めてからの変化だ。

この記事では、Skills機能の仕組みと実際のSKILL.mdの書き方、実務で使える具体的なスキル例3つ、注意点を解説する。Codexを普段から使っているが「Skillsはまだ試していない」という人に、特に読んでほしい。

Codex Skills機能とは何か

Codex Skills（スキル）とは、タスク固有の処理手順・ルール・リソースをパッケージ化して、Codexが信頼性高く繰り返し実行できるようにする機能だ（OpenAI Developers公式）。

Codexとは、OpenAIが開発したAIコーディング支援エージェントで、自然言語の指示をもとにコードの生成・実行・修正を自律的に行うツールだ。通常の使い方ではそのつど指示を書いてCodexに渡すが、Skills機能を使うと「あらかじめ定義したルールセット」をCodexが自動的に参照するようになる。

「自分の仕事のルール」をCodexに覚えさせる仕組み

Skills機能の核心は「SKILL.md」というファイルだ。このMarkdownファイルに、Codexに覚えさせたいルール・手順・判断基準を書いておく。フォルダひとつがスキルひとつで、「1フォルダ＝1スキル」という設計になっている（AI総合研究所）。

スキルのフォルダ構成は以下の通りだ（OpenAI Developers公式）。

• SKILL.md（必須）　メタ情報（スキル名・説明）と、Codexへの指示本文を記述するメインファイル
• scripts/（オプション）　スキルが実行するスクリプトを格納するフォルダ
• references/（オプション）　Codexが参照する設計書・ガイドライン・ドキュメントを格納
• assets/（オプション）　テンプレートやサンプルファイルを格納

起動方法は2種類ある。「$skill-name」または「/skills」と明示的に呼び出す方法と、タスクの内容がスキルの説明と一致したとき自動的にCodexが選択する暗黙的な呼び出しだ。慣れてくると暗黙的呼び出しが便利で、「いつものやり方でやって」と言わなくても、Codexが文脈を読んで適切なスキルを使ってくれる。

段階的開示という設計思想

Skillsには「段階的開示（Progressive Disclosure）」という設計思想が組み込まれている（OpenAI Developers公式）。

これはコンテキスト効率化のための仕組みで、Codexは最初にスキルの名前と説明だけを読み込み、そのスキルが実際に必要になったときに初めて詳細な指示全体を読み込む。つまり「常にすべてを読み込んでいるわけではない」設計だ。

この設計のメリットは、多数のスキルを定義してもCodexのコンテキスト（処理できる情報量の上限）を圧迫しないことだ。20個のスキルを設定していても、実際に使われるスキルの詳細のみが必要なタイミングで読み込まれるため、処理効率が落ちない。

Skillsは「Codexへの毎回の説明を省略する」機能ではなく、「必要なときに正確な知識を自動参照できるCodexの記憶システム」と理解すると、活用の幅が広がる。

Skills機能がある世界とない世界の違い

具体的に何が変わるかを、「Skillsなし」と「Skillsあり」で比較してみる。

毎回同じ説明をしていた時間が消える

Skillsなしの状態で、たとえばコミットメッセージを書いてもらうとき、毎回こんな指示を書く必要がある。

「Conventional Commits形式で書いて。feat / fix / docs / chore / refactor / test などのタイプを使う。件名は英語で50文字以内、命令形で始める。本文は72文字で折り返し、変更の『なぜ』を書く。フッターにBreaking Changeがあれば記載する。」

これを毎回書くのは手間だし、書き方が多少ゆらぎやすい。チームで使う場合は、メンバーごとに指示の書き方が違ってアウトプットの品質がバラバラになる。

Skillsありの状態では、「コミットメッセージを書いて」という一言だけでいい。「draft-commit-message」というスキルをあらかじめ定義しておけば、Codexがそのスキルを参照して自動的にConventional Commits形式のメッセージを出してくれる。

この「毎回書く必要がなくなった指示の量」は、日々の業務で積み上がると意外と大きい。私の場合、コミットメッセージ・PRレビュー・週次レポートの3つのスキルを定義してから、Codexへの指示にかける時間が体感で3分の1以下になった。

チームの「暗黙知」をCodexに渡せる

個人での利用より、チームでの利用でSkillsのメリットが大きくなる。

どのチームにも「暗黙知」がある。コーディングのときに気をつけること、レビューで必ずチェックするポイント、ドキュメントを書くときのトーン。ベテランメンバーは自然にやっていることでも、新入りメンバーはなかなか習得できない知識だ。

チーム共通のSkillsファイルをリポジトリに置く（$REPO_ROOT/.agents/skills/に配置）と、そのリポジトリで作業する全員が同じスキルを使えるようになる。チームの暗黙知をSKILL.mdに文書化することが、Codexの品質標準化と同時に「チームの知識の言語化」にもなる。

Skills機能の本当の価値は「Codexへの説明を省く」だけでなく、「チームの知識をCodexを通じて共有・標準化できる」点にある。

SKILL.mdの書き方と実務で使えるスキル例3つ

実際にSKILL.mdをどう書くかを、具体例とともに紹介する。「人間が読む手順書として書く」という姿勢が、良いSKILL.mdを作る上での基本だ（AI総合研究所）。

SKILL.mdの基本的な書き方

SKILL.mdはYAMLフロントマターと本文の2部構成だ（OpenAI Developers公式）。

フロントマターに書く必須フィールドは2つ。

• name　スキル名。100文字以内の1行で書く。Codexがスキルを識別・参照するための名前になる
• description　「どんなときにこのスキルを使うか」を説明する。500文字以内の1行。Codexがスキルを自動選択する際の判断基準になる重要なフィールドだ

フロントマターのあとに本文を書く。本文には「Codexへの具体的な指示」を書く。箇条書き・番号付きリスト・見出しを使って読みやすく整理する。「Codexが実行すべき手順」を命令形で書くのが基本だ。

スキルの配置場所はスコープによって使い分ける。個人専用なら$HOME/.agents/skills/に置く。チーム共通にしたいなら、リポジトリのルートに.agents/skills/フォルダを作ってそこに置く。管理者がシステム共通のスキルを定義したい場合は/etc/codex/skills/に置く（OpenAI Developers公式）。

実務スキル例①：コミットメッセージを規約通りに書くスキル

コミットメッセージをConventional Commits形式で一貫して書くためのスキルだ。AI総合研究所の事例でも「最も基本的で効果的なスキルの一つ」として紹介されている。

SKILL.mdの記述例は以下のようになる。

フロントマター部分：スキル名を「draft-commit-message」、説明を「ユーザーがコミットメッセージの作成を依頼した場合、またはコードの差分からコミット内容を説明する必要があるときに使用する」と記述する。

本文部分には以下の指示を書く。使用するタイプ（feat・fix・docs・chore・refactor・test）の説明、件名の書き方（英語・50文字以内・命令形・何をしたかではなく何が変わったか）、本文の書き方（72文字折り返し・変更のなぜを書く）、Breaking Changeがある場合のフッター記載ルール、という4項目を箇条書きで記述する。

このスキルを設定してから「コミットメッセージを書いて」と言うだけで、毎回規約通りのメッセージが出てくるようになった。チームで同じスキルを共有すれば、メンバー全員のコミットメッセージが統一されてgit logが読みやすくなる。

実務スキル例②：PRレビューの観点を標準化するスキル

コードレビューで見るべきポイントをスキルとして定義しておくと、Codexによるレビューの品質と一貫性が上がる。AI総合研究所の「設計レビュー観点の標準化」の事例を参考にした。

スキル名は「review-pull-request」、説明は「プルリクエストのレビューを依頼されたとき、またはコードの品質確認が必要なときに使用する」。

本文には以下のチェック項目を記述する。

• 機能の正確性　要件通りに動くか。エッジケースの考慮があるか
• コードの読みやすさ　変数名・関数名が意図を表しているか。コメントが必要な箇所に記載されているか
• セキュリティ　入力バリデーション・SQLインジェクション・XSSなどの脆弱性がないか
• パフォーマンス　不要なループや重複処理がないか。N+1問題が発生していないか
• テスト　変更に対応したテストが追加・更新されているか。カバレッジが十分か
• 後方互換性　既存の機能を壊す変更がないか

チームのリポジトリにこのスキルを置いておくと、メンバー全員が同じ観点でCodexにレビューを依頼できる。「Codexにレビューを依頼したらチームによって観点がバラバラだった」という問題が解消される。

実務スキル例③：週次レポートを特定フォーマットで出力するスキル

毎週提出する週次レポートのフォーマットが決まっている場合、そのフォーマットをスキルとして定義しておくと、毎回フォーマットの説明が不要になる。

スキル名は「weekly-report-draft」、説明は「週次レポートや週次サマリーの作成を依頼されたとき、または今週の業務内容の整理が必要なときに使用する」。

本文には会社・チームの週次レポートの形式を記述する。たとえば「①今週完了したタスク（箇条書き、各タスクに進捗率）②来週の予定（3項目以内）③課題・リスク（あれば）④数値実績（売上・件数など、適用される指標）」という構成と、トーン（客観的・簡潔・数値を優先）のルールを書く。

references/フォルダに過去のレポートサンプルを入れておくと、Codexが文体・粒度の参考にできる。Automationsと組み合わせて「毎週金曜17時に週次レポートの下書きを作る」という定期実行にすると、さらに手間が省ける。

SkillsとAutomationsを組み合わせるとどうなるか

前の記事でも触れたCodexのAutomations機能（定期スケジュール実行）と、Skillsを組み合わせると、自動化の精度と一貫性が大きく上がる。

OpenAI Developersの公式ドキュメントでも「SkillsとAutomationsを組み合わせることで、より複雑なワークフローの実現が可能」と明記されている。具体的には以下のような組み合わせが効果的だ。

• 週次レポートスキル + Automations（毎週金曜17時実行）　決まったフォーマットの週次レポートを毎週自動生成。毎回フォーマットを説明する必要がなく、スキルに書かれたルールで一貫した品質になる
• PR自動レビュースキル + Automations（プッシュのたびに実行）　コードをプッシュするたびに、定義済みのレビュー観点で自動チェックが走る。人間によるレビュー前の一次フィルタとして機能する
• CI失敗ログ解析スキル + Automations（CI失敗時実行）　CI（継続的インテグレーション）が失敗したとき、スキルに定義したログ解析手順に従って自動調査が始まる。AI総合研究所の事例でもこのパターンが実務で活用されている

SkillsとAutomationsの組み合わせは「いつ実行するか（Automations）」と「どう実行するか（Skills）」の分離設計で、それぞれ独立して管理・更新できるため、運用しやすい。

導入前に知っておくべき注意点

実際に使い始めてわかった注意点と、AI総合研究所が指摘する重要な点を整理する。

注意点①：動作は必ず環境で検証する
AI総合研究所は「構造は共通でも動作は必ずツールごとに検証する」と強調している。SKILL.mdの書き方はCodexとClaude Codeなどで共通仕様があっても、環境依存の部分は動きが変わる可能性がある。特にscripts/フォルダのスクリプトは、他のメンバーの環境でも動くかを確認してから共有する。

注意点②：1スキル1役割の原則を守る
「コミットメッセージ＋PRレビュー＋週次レポート」を1つのスキルにまとめようとすると、descriptionが書けなくなる。Codexがスキルを自動選択するのは「descriptionと一致したとき」なので、役割が複数のスキルは自動選択されにくい。各スキルを1つの役割に絞ることが、運用の鍵だ。

注意点③：descriptionの質がスキルの呼び出し精度を決める
暗黙的呼び出し（Codexが自動でスキルを選ぶ）の精度は、descriptionの書き方に大きく依存する。「どんなときに使うか」だけでなく「どんなときに使わないか」も書くと、誤った場面でスキルが発動することを防げる。設定したあとにプロンプトテストをして、意図通りに呼び出されるか確認することを推奨する（OpenAI Developers公式）。

注意点④：スキルは定期的に見直す
一度書いたSKILL.mdをそのまま放置すると、プロジェクトのルールが変わったのにスキルが古いままになる。チームで使う場合は、コーディング規約・レビュー観点の更新時にSKILL.mdも合わせて更新するプロセスを作っておく。

良いSKILL.mdは「人間が読んでも意味が通る手順書」だ。AIのためだけでなく、チームの新人が読んでも仕事のやり方がわかる品質を目指すと、自然と良いスキルになる。

よくある質問（FAQ）

まとめ

Codexのスキル機能は、「繰り返しの指示を省く」というシンプルな効果だけでなく、「チームの暗黙知を文書化・共有する」という副次的な価値を持つ機能だ。

設定の手間は最初の1時間程度で、一度作れば繰り返し使える。その効果は日々の業務の中でじわじわと積み上がっていく。

Skills機能を試し始めるための最初のステップを整理する。

• ステップ1：毎回Codexに説明していることをリストアップする　「これは毎回書いているな」と感じる指示を3つ選ぶ。それがスキル化の候補だ
• ステップ2：最も頻度が高いものから1つだけスキルを作る　$skill-creatorを使うか、SKILL.mdを手書きで作る。nameとdescriptionを丁寧に書くことを優先する
• ステップ3：数パターンで発動テストをして、問題なければ使い続ける　意図通りに動いているか確認してから本格運用に入る

「まだ使っていない」人は、今日始めてみてほしい。Codexへの指示が一言で済むようになる感覚は、一度味わうと戻れなくなる。