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

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

練習用のプロジェクトフォルダーを用意し、Codexからそのフォルダーを開きます。仕事の原本や顧客情報は入れず、後述の架空メモだけを使ってください。ここで扱う例には追加ライブラリや外部APIは不要ですが、Codex自体の利用には選択したプランや認証経路の条件が適用されます。

CodexにはChatGPTでのログインとAPIキーによる利用があります。すでにChatGPTへ料金を支払っていても、APIキー経路の利用がその契約の枠に置き換わるわけではありません。導入手順の途中でAPIキーを求められたら、目的に必要な経路かを確認しましょう。

根拠：OpenAI — Authentication / OpenAI — Build skills

練習用フォルダーに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

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

Codex CLI・IDEでは、/skillsまたは$を使ってSkillの候補を確認できます。名前が見えたら明示的に選び、次の入力を渡します。アプリでは画面上のSkills一覧やメンション候補を使い、CLIのキー操作をそのまま当てはめないようにします。

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

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

期待する結果は、料金表の改定について未決事項が残り、担当Aと「次回会議まで」という原文の情報が保持されることです。9月18日を次回会議の日付に転用したり、決定済みの見積書作成を未決事項に入れたりしないかを見ます。

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

根拠：OpenAI — Build skills

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

同じ入力をもう一度試しても、文章表現まで完全に一致するとは限りません。比較するのは語尾ではなく、必要な項目の有無と事実の扱いです。評価例を手元に残しておくと、後で指示を変更した際に以前できていたことが崩れていないか確認できます。

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

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

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

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

根拠：OpenAI — Build skills

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

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

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