CodexのスキルとSKILL.mdを理解する：反復業務を一度だけ説明する方法

要約： スキルは反復業務に必要な手順と結果形式を再利用できるよう整理した一式です。最初は一つの作業のための短いSKILL.mdから書いてみてください。

1. スキルはいつ役立つか？

文書確認のたびに「古いコマンドを探す」「コードと説明を比べる」「結果を表にする」を繰り返すなら、スキルに整理できます。プロンプト保存から一歩進み、使う場面、必要入力、処理手順、結果形式をまとめる方法です。

OpenAIの公式説明によると、スキルは特定作業の指示と補助資料をまとめ、プラグインはスキルや接続ツールなどを含められるインストール可能な一式です。スキル名があるだけで外部サービスへの接続機能が必ず生まれるわけではありません。手順の有無と実際のツールの有無を分ける必要があります。

2. SKILL.mdの基本構成

公式の作成文書は、スキルフォルダー内にSKILL.mdを置き、nameとdescriptionを含めるよう案内しています。必要ならスクリプト、参考資料、テンプレートなどを追加できます。最初は実行コードなしで業務の指示だけを書いても構いません。

---
name: docs-check
description: 프로젝트 문서의 명령과 경로를 검토하고 차이를 보고할 때 사용합니다.
---

프로젝트 문서 검토 지침

입력:
- 검토할 문서 경로
- 비교할 프로젝트 설정과 소스

수행:
1. 문서에 적힌 경로와 명령의 근거를 확인합니다.
2. 실제 프로젝트 설정과 다른 내용을 찾습니다.
3. 직접 확인한 사실과 추가 확인이 필요한 내용을 구분합니다.
4. 이 작업에서는 파일을 수정하지 않습니다.

출력:
- 문서 위치 / 차이 / 근거 / 권장 수정
- 검토하지 못한 범위

この例は架空の文書確認スキルです。インストール済みや実行済みのスキルの紹介ではないため、実際のプロジェクトで動作を確認してから使う必要があります。自動修正も求めるなら、その段階と変更の境界を別途設計してください。

3. descriptionには使う場面を書く

「開発を助ける最高のスキル」ではどの依頼に適用するか分かりません。「READMEの実行コマンドとプロジェクト設定を比較するときに使う」のように状況を書いてみてください。似たスキルが複数ある場合、文書確認とコードレビューの範囲も区別するとよいでしょう。

本文には求める結果を明確に残します。文体の修正が目的なら根拠確認より文と読者が中心になる場合があります。コードと文書の不一致探しならパスと設定が中心です。異なる作業を巨大な一スキルに入れるより、明確な一作業から始めると結果を評価しやすくなります。

4. 読み込み後、期待どおり動くか確認する

公式文書はCodexでスキルを明示的に選択するか、依頼が説明に合う際に自動適用できると案内しています。CLIとIDEでは$メンションなど環境ごとの選択方法を確認してください。ローカルスキルのパスも現在の公式案内に従い、古い記事の場所が同じままと仮定しないでください。

$docs-check
README.md의 실행 안내를 검토해 주세요.
package.json과 관련 설정을 근거로 비교하고,
문서 위치, 차이, 근거, 권장 수정을 표로 정리해 주세요.
파일은 수정하지 말고 미확인 사항을 표시해 주세요.

初回は必要文書を読むか、約束の形式で結果を出すか、禁止した変更を行うかを確認します。存在しないファイルを実際に読んだと報告していないかも調べてください。結果がずれたら指示を一気に長くするより、誤判断の原因となる部分を補う方が管理しやすくなります。

5. スキルが期待どおり適用されないとき

• 選択されない： インストール状態と説明文が実際の依頼に合うか確認します。
• 別のスキルと混同される： 名前と適用範囲を区別します。
• 指示が広すぎる： 入力、完了基準、結果形式を一業務に合わせます。
• 外部資料を読めない： スキルの指示と実際のツール・アクセス権限を別々に確認します。
• 結果を比べにくい： 根拠箇所と未確認範囲を出力に含めます。

他の人のスキルを取り入れる際は指示と付属スクリプトを確認してください。特定業務の指示の再利用と実行権限の拡大は別の決定です。最初は結果を草案として確認できる作業に設計すると、確認基準を定めやすくなります。

6. 最初のスキルをプロジェクト内に配置する

初めて作る文書確認スキルをプロジェクト内に置くと、指示とコードの変更を一緒に管理しやすくなります。現在の公式文書はリポジトリの.agents/skillsを使うローカルスキル探索を案内しています。次はルートにdocs-checkを置く例です。上位フォルダーや利用者範囲にもスキルがあり得るため、同名の既存スキルを先に調べてください。

project/
  .agents/
    skills/
      docs-check/
        SKILL.md
  README.md
  package.json
  docs/

Windows PowerShellでフォルダーを準備するには下記のコマンドを使えます。先にプロジェクトルートにいるか確認し、作成したフォルダーのSKILL.mdに前節の指示を保存してください。これはフォルダー作成の例で、この記事で実際にインストールした結果ではありません。

Get-Location
New-Item -ItemType Directory -Force -Path '.agents\skills\docs-check'
Get-ChildItem -LiteralPath '.agents\skills\docs-check'

保存後は現在のクライアントで選択可能か確認します。公式文書はCodexが変更を検知し、反映が見えないときは再起動するよう案内しています。CLIは/skillsや$メンションで直接選べます。一覧に出なければファイル名、name・descriptionメタデータ、保存場所から確認してください。本文を長くしても設置場所の誤りは解決しません。

7. 名前と説明を業務範囲に合わせる

スキルはまず名前と説明で必要な業務を判断されます。本文に優れた手順があっても、説明が「文書関連作業」だけでは作成・翻訳・要約・確認のどの依頼に使うか分かりにくくなります。一業務の開始条件と除外業務を説明に入れると、適用範囲を明確にできます。

넓은 설명:
문서 작업을 도와주는 스킬입니다.

구체적인 설명:
README나 docs의 실행 명령·로컬 경로를
현재 프로젝트 설정과 비교해 오류를 보고할 때 사용합니다.
문체 수정·번역·외부 웹사이트 전체 검사는 대상으로 하지 않습니다.

実際のdescriptionはYAMLメタデータで正しい文字列形式にしてください。長くするより「いつ使い、何を行わないか」が先に読めるように書くとよいでしょう。似た名前を幾つも作るより、docs-checkのように役割が分かる名前を使い、同名が既にあれば別名を決められます。公式文書は同名スキルが自動で統合される方式ではないと案内しています。

本文には判断する選択を残してください。「全リンクを確認」はローカルパスと外部URLに同じ方法を適用させる場合があります。ローカルパスはリポジトリ内の存在を確認し、外部URLは現在の作業でウェブアクセスが可能か先に分けます。外部検査を範囲外にしたら未検査と表示すれば十分です。アクセス不能な資料を正常と報告しないよう、結果形式で空欄の意味を定めてください。

8. 文書確認を根拠のある報告にする手順

架空のREADMEにnpm run startがあるのに、現在のpackage.jsonにはdevとtestだけあると仮定します。「startがない」という事実と「devに変えればよい」という提案は区別する必要があります。開発サーバーの案内ならdevが候補でも、運用サーバーの案内なら別コマンドとビルド手順が必要な場合があります。スクリプト名が似ているだけで無条件に置き換えないでください。

문서 검토 세부 절차
1. 문서에서 실행 명령과 로컬 파일 경로를 추출합니다.
2. 실행 명령은 해당 프로젝트 설정과 README 맥락을 함께 비교합니다.
3. 경로는 문서가 기준으로 삼는 폴더를 확인하고 존재 여부를 조사합니다.
4. 일치·불일치·미확인으로 구분합니다.
5. 불일치는 근거 파일과 필요한 수정안을 함께 보고합니다.
6. 판단 자료가 없으면 확인할 자료를 적고 문서를 임의로 수정하지 않습니다.

실패 분기
- 대상 문서 없음: 정확한 경로를 요청하고 검토 미실행으로 보고
- 설정 파일 없음: 다른 언어나 도구의 설정 위치를 조사
- 외부 링크 접근 불가: 실패와 미검사를 구분
- 명령의 목적 불분명: 개발·빌드·운영 중 용도를 확인

結果表に位置と根拠を入れると人が修正できます。「READMEが古い」では発見内容が広く次の行動を決めにくくなります。「開発サーバー実行節のstartスクリプトが現設定に存在せず、devの役割を確認する必要がある」のように文書位置と判断を結び付けてください。直接実行していなければ、スクリプトの存在確認と実行成功を分ける必要があります。

9. スキルを評価・修正する小さな事例集

初回評価では同じ文書を一度だけ確認せず、異なる小さな状況を入れてみてください。正常な案内、存在しないコマンド、文書なしの依頼、範囲外の依頼を分けると判断のずれが分かります。次は実行結果ではなく、評価入力と期待基準の例です。

• 正常なREADME：存在しない問題を作らず、確認根拠を報告するか？
• 存在しないスクリプト：設定にない事実と修正提案を分けるか？
• 文書パスの誤り：別ファイルを代わりに読み、正常に確認したように報告しないか？
• 文体修正の依頼：このスキルの確認範囲と区別するか？
• 外部資料へ未アクセス：正常と断定せず未確認と表示するか？

$docs-check
README.md의 개발 실행 안내와 로컬 설정 경로를 검토하세요.
문서 위치 | 일치 여부 | 실제 확인 근거 | 수정 제안 형식으로 보고하세요.
명령을 실행하지 않았다면 실행 성공으로 표현하지 마세요.
파일 수정은 하지 말고 필요한 다음 확인을 적어 주세요.

結果が誤っていれば、誤った一部分に対応する規則だけを補います。外部URLを読めないのに正常と報告したなら「外部資料は未検査と表示」を加えればよいでしょう。特定スクリプトの用途を誤解したら、コマンド目的も比較する手順を補ってください。失敗ごとに長い禁止文を追加すると、正常な作業手順が見えなくなることがあります。

手順が安定してから補助資料やスクリプトを検討してください。人が直す表を作る業務は指示だけで始められます。多数ファイルから同じパスを抽出するなど、反復計算が明確になった際はスクリプトが役立つ場合があります。追加したら入力と変更するファイルをスキル文書に書き、結果を確認できるようにしてください。

10. よくある質問

スキルを作るとモデルが学習しますか？ この記事のスキルは再利用する指示と資料を提供する方式です。モデルを別途訓練する手順とは理解しないでください。

スクリプトは必須ですか？ 反復手順と結果形式を伝える業務は指示だけで始められます。計算や外部ツールが必要な場合に追加を検討してください。

プロジェクトの規則も全てスキルにしますか？ 全作業の共通規則と特定業務だけの手順を分けると文書管理が容易です。スキルにはその業務を選んだ際に必要な内容から入れてください。

公式の出典と確認日： OpenAI公式文書：スキルとプラグイン · OpenAI公式文書：スキルを作る。2026年10月3日確認。例は自分のプロジェクトと現在の機能に合わせて調整してください。