Codex Skillsの使い方：最初のSKILL.mdを作って確かめる

01最初に、実行する場所とログイン方法を確認する

まずは練習用のフォルダーを1つ用意し、Codexでそのフォルダーを開きます。実際の業務データや顧客情報は入れず、記事内で紹介する架空のメモだけを使いましょう。この例では追加ライブラリや外部APIは不要ですが、Codex自体の利用には契約プランや認証経路ごとの利用条件が適用されます。

Codexには「ChatGPTアカウントでログインする方法」と「APIキーで従量課金利用する方法」の2つがあります。すでにChatGPTの有料プランを契約していても、APIキーを使った実行分がその定額枠に含まれるわけではありません。途中でAPIキーを求められたら、意図した利用経路かどうかを確認しましょう。

根拠：OpenAI — Authentication / OpenAI — Build skills

02練習用フォルダーにSKILL.mdを置く

プロジェクト内だけで使うローカルSkillは、「.agents/skills」フォルダーの下で管理します。以下の例では、練習用フォルダーの直下にこの配置を作成します。既存のプロジェクトで試す場合は、同名のSkillがないかを事前に確認し、大切なファイルを誤って上書きしないよう注意してください。

練習用プロジェクト/
└── .agents/
    └── skills/
        └── meeting-open-items/
            └── SKILL.md

以下は学習用の原稿です。配布済み製品や動作保証されたテンプレートではありません。前半のnameとdescriptionで名前と用途を伝え、後半で具体的な処理と確認条件を定めます。

---
name: meeting-open-items
description: 会議メモから未決事項を整理するときに使う。決定事項の作成や外部送信には使わない。
---

入力されたメモだけを根拠に、未決事項を表にする。
列は「未決事項」「次の確認」「担当」「期限」。
担当や期限が明記されていなければ「未定」と書く。
決定済みの項目は未決事項へ混ぜない。
入力が空なら、整理できない理由と必要な入力を返す。
外部サービスへ接続せず、結果をこの会話へ返す。
最後に、推測で補った情報がないか自己点検する。

根拠：OpenAI — Build skills / Agent Skills — Specification

03名前を指定し、短いメモで試す

Codex CLIやIDE拡張では、「/skills」または「$」を入力すると利用可能なSkillの候補が表示されます。一覧から目的のSkillを確実に選び、続けて整理したいテキストを渡します。なおデスクトップアプリ版では画面上のSkills一覧やメンション機能を使うため、環境に合った操作を行ってください。

$meeting-open-items を使って次のメモを整理してください。

見積書は9月18日までに作る方針で決定。
料金表の改定日はまだ決まっていない。
担当Aが次回会議までに新しい料金案を確認する。
次回会議の日付は未定。

期待通りの出力とは、料金表の改定が未決事項として整理され、担当Aや「次回会議まで」という原文の情報がそのまま保たれている状態です。「9月18日」を次回会議の期日だと勝手に推測したり、決定済みの見積書作成を未決事項に混入させたりしていないかを点検します。

暗黙の自動選択は説明文との一致に左右されます。最初は明示的に選択して、Skillそのものが読まれているかと、手順が妥当かを分けて確かめると診断しやすくなります。

根拠：OpenAI — Build skills

04「うまく見える」から一段進めて確認する

AIに同じ入力を再度与えても、語尾などの文章表現は毎回微妙に変わることがあります。比べるべきは言い回しではなく、必要な項目の有無と事実関係の正確さです。テスト用の入力例を手元に残しておけば、後から指示文を変更した際にも動作が崩れていないかをすぐに再確認できます。

AIの自己点検だけで合格にせず、人が元の短いメモと表を照合します。ここを通過してから、少し長い匿名サンプルへ進みましょう。

05読み込まれない・別の動作になるとき

• ファイル名がSKILL.mdになっているか確認する。拡張子が二重になっていないかも見る。
• Codexで開いた作業フォルダーと、.agents/skillsを置いた場所が対応しているか確認する。
• nameとdescriptionが存在し、YAMLの区切りが崩れていないか確認する。
• 同じnameのSkillが別の場所にもないか、選択候補を確認する。
• 更新が反映されなければCodexを再起動し、もう一度明示的に選ぶ。

候補に現れるのに結果が悪い場合は、保存先を何度も変えるより、曖昧な指示を一つずつ直します。エラーが外部コマンドや権限に関するものなら、文章の修正だけでは解決しません。配布元の必要環境と実際の環境を照合してください。

根拠：OpenAI — Build skills

06既製Skillを入れるときも、確認の順番は同じ

配布元の手順に従う前に、何が追加されるか、必要なOS・アプリ・外部サービスは何かを確認します。スクリプトが付属する場合は、ファイルを書き換える場所やネットワーク送信先も確認対象です。読めない内容は、エージェントに要約と作用の説明を頼み、分からないまま実行しないようにします。

今回の練習で得るものは「インストールできた」という印ではなく、入力・期待結果・実際の結果を比べる習慣です。購入後のSkillでも、付属のサンプルと重要な失敗入力を一つずつ試し、自分の仕事へ広げてください。