Skills と SKILL.md

Codex 学習目次に戻る

このレッスンでできること

Skill はサイト変更後の検証など、繰り返す手順をまとめます。常に適用するプロジェクト要件は AGENTS.mdに残し、Skill は特定のタスクで選びます。Pluginsはスキルとサービス接続の配布に使えます。

始める前に

ログイン済みの Codex CLI または Skills 対応のデスクトップ／IDE を用意します。ToDo 教材の expected を codex-practice にコピーし、broken は後で使う独立した教材として残します。二つの版のファイルを混ぜないでください。

テストは Node.js、プレビューは Python 3 を使います。ブラウザがなければスキルは画面確認を未実施として手動手順を示します。指示を書くだけでツールが増えるわけではありません。完全なスキルサンプルも取得できます。内容を読んでから配置します。

名前、説明、本文

スキルには SKILL.md を含むフォルダーが必要です。先頭の YAML frontmatter に name と description、本文に手順を書きます。Codex は最初に名前と説明を見て、使用時に全文を読みます。「何でも手伝う」という説明は無関係の依頼にも選ばれやすくなります。

例の名前は todo-acceptance で、一般のサイト開発ではなく Small Steps の検証に限定します。まずはスクリプト、外部サービス、全体インストールを加えず指示だけにします。決まった処理を反復する必要があれば scripts、大量の参考情報は references に置き、読む条件を示します。

手順 1：プロジェクト内に作る

codex-practice のルートに .agents/skills/todo-acceptance を作ります。先頭の点も名前の一部で、.codex や点のない agents ではありません。Windows では次を実行します。既存のフォルダーがあればスキルを上書きする前に内容を確認します。

New-Item -ItemType Directory -Force .agents/skills/todo-acceptance

mkdir -p .agents/skills/todo-acceptance

テキストエディターで SKILL.md を作ります。Windows は .txt が付いていないか、Linux は大文字か確認します。必要な構成は以下です。練習プロジェクトと一緒に管理し、全プロジェクト共通のスキルにはしません。

codex-practice/
  index.html
  style.css
  app.js
  core.mjs
  core.test.mjs
  .agents/
    skills/
      todo-acceptance/
        SKILL.md

手順 2：完全なスキルを書く

以下はダウンロード版と同じです。既存コードを読み、既存テストを実行し、可能ならブラウザを確認して PASS、FAIL、NOT RUN を報告します。検証を通すための修正は黙って行わず、問題を理解してから修正を選べるようにします。

---
name: todo-acceptance
description: Verify the Small Steps todo practice website after a change, using its existing tests and browser checks. Use for acceptance checks of this exercise, not unrelated websites or feature implementation.
---

# Small Steps acceptance

Confirm the requested practice folder contains index.html, style.css, app.js,
core.mjs and core.test.mjs. If these are missing, stop and report the path checked.

Read the existing code, then run `node --test core.test.mjs` from that folder.
Do not rewrite tests or implementation to make an acceptance run pass.

If a browser is available, preview the site on a loopback address with a fresh
browser context. Add Read and Build, complete Read, check Active and Completed
filters, reload, and delete Read. Reject whitespace-only input. Check 390px and
1280px widths and visible Tab focus. Keep existing user browser data unchanged.

Report PASS, FAIL or NOT RUN for each check, with the command, observation or
limitation. Include the working folder and remaining issues. Do not claim that
tests, screenshots, deployment or publication happened without evidence.

If a check fails, report the reproduction and relevant file. If a required tool
is unavailable, report NOT RUN and the manual steps. Finish with results only;
implement fixes only when the user requests them.

名前は小文字、数字、ハイフンを使い、フォルダー名と合わせます。description の前半で対象を明確にし、本文には判断を変える条件を残します。この例に余分なパッケージや設定は不要です。空のフォルダーを増やしても完成度は上がりません。

手順 3：見つけて明示的に使う

Codex はスキルの変更を検出します。見えなければセッションを再開し、作業場所を確認します。CLI／IDE は /skills または $ で検索できます。デスクトップでは側欄の Skills と現在の選択 UI を使います。名前が見えることは発見の証拠で、実行の証拠ではありません。

$todo-acceptance Check this Small Steps practice folder. Report the results without editing files.

デスクトップの選択 UI では todo-acceptance を選び、同じ検証を依頼します。このプロジェクトの SKILL.md を読み、別の同名スキルではないか確認します。同名スキルは自動で統合されないため、グローバルや他の場所にもある場合はパスが重要です。

手順 4：正常と意図的な失敗を比べる

expected のコピーでは node --test core.test.mjs が 3 テスト成功のはずです。報告には実際の命令と結果を含めます。ブラウザも動かしたなら Read、Build、フィルター、再読み込み、空白入力の観察を期待します。ブラウザがなければ NOT RUN であり、成功でもスキル全体の失敗でもありません。

独立した broken コピーを作り、同じスキルをその .agents/skills に置き、その場所から新しいタスクを始めます。この版では Completed が反転し、Read が完了、Build が未完了のとき誤って Build を表示します。テストは 2 成功、1 失敗のはずです。スキルは FAIL と再現手順を報告し、ソースを変更しないことを確認します。

これで失敗を忠実に報告する流れか比較できます。形式検証はメタデータと構造が読めることだけを示し、エージェントが手順に従った証明ではありません。逆にテスト失敗はスキルがバグを見つけた成功でもあります。一つの「成功」だけにまとめず、証拠を分けます。

材料不足で停止することも確認する

expected から独立した incomplete コピーを作り、同じスキルを入れます。そのコピーの core.test.mjs だけをフォルダー外へ退避し、元の expected と broken は変更しません。incomplete から新しいタスクを開始してスキルを選びます。欠けたファイルと確認したパスを示して受け入れ確認を止めるのが期待する動作です。テストの創作、別コピーでの実行、以前の合格結果の再利用は認めません。退避したファイルを元の場所に戻してから再確認します。

broken は材料がそろい、実際に実行したテストが失敗します。incomplete は開始条件を満たしません。ブラウザがない場合は画面確認だけが NOT RUN です。この三つを同じ FAIL にまとめないでください。入力や選択のケースはスキルのテスト、スクリプトや参考資料の追加はスキルのリソースで学べます。

問題解決、無効化、復元

表示されない場合は .agents/skills の場所、実際の拡張子、frontmatter の二つの ---、name と description を確認します。ZIP を置いただけでは展開済みスキルではありません。直して Codex を再起動し、一覧を調べます。

表示されても使われない場合は明示選択または $todo-acceptance を使い、名前とパスを確認します。自動選択は説明と依頼の解釈によるため、似た文でも必ず発動するわけではありません。挨拶でも使われるなら、この教材の検証に説明を絞ります。

選ばれてもテストできなければ、実際のホストの Node.js と作業場所の core.test.mjs を確認します。スマートフォンの Remote でもスキルとツールはホストにあります。A にインストール済みでも B にあるとは限りません。不足ツールをすべて自動インストールして前提を隠さないでください。

実行中の検証はタスク内で停止します。無効化はスキルをプロジェクトの探索場所から外に移して保存し、再起動後に確認します。設定で無効にする場合は公式 [[skills.config]] を参照し、既存 config.toml を残します。無効化しても過去の報告やファイル変更は消えません。

練習と検証記録

「Small Steps のフィルターと保存を検証」と「今日の練習目標を説明」を比較します。前者はスキルに合い、後者は全検証を必要としません。選択、パス、結果を記録して説明を調整します。一度正しく選ばれただけでは全状況の検証になりません。

機構は 2026-09-14 に Build skills 公式文書で確認しました。例には形式検証を行い、サイトのコアと故障には実際のテスト結果があります。自動選択や各 Codex UI は別に実測が必要です。次は Plugins、MCP、テストとレビューを参照できます。

Codex 学習目次に戻る

詳しい説明を読む

SKILL.md to Invoke to Output

• AIツール
• チュートリアル
• Codex