Agent Skill は、特定の作業を安定して実行するための手順、参考資料、スクリプト、テンプレートをまとめたディレクトリです。Codex は最初から全文を読むのではなく、名前と説明を見て必要な Skill だけを読み込みます。この方式を progressive disclosure と呼びます。
基本構造
.agents/skills/docs-content/
├── SKILL.md
├── scripts/
├── references/
└── assets/SKILL.md には少なくとも name と description を記述します。
---
name: docs-content
description: Create or update beginner-facing documentation pages and keep locale indexes synchronized.
---
# Procedure
1. Read the content rules.
2. Confirm the target section.
3. Write Japanese first.
4. Sync the English page.
5. Run link and harness checks.明示呼び出しと暗黙呼び出し
Codex は二つの方法で Skill を使います。
- 明示: プロンプトで
$docs-contentのように指定する - 暗黙: 依頼と
descriptionが一致すると Codex が選ぶ
暗黙選択の精度は description に依存します。「何でも支援する」のような広い説明を避け、使う場面と使わない場面を先頭に書きます。
保存場所と責任範囲
リポジトリ固有の Skill は .agents/skills/、個人共通の Skill は $HOME/.agents/skills/、管理者配布は /etc/codex/skills に置けます。このリポジトリでは shared/skills/ を正とし、ランタイムが読むアダプターへ同期します。
Skill は一つの責務に絞ります。ブログ執筆、docs 執筆、CI 修復を一つにまとめると、不要な手順が読み込まれます。複数 Skill をまとめて他の利用者へ配る段階で Plugin を使います。
設計チェック
descriptionだけで適用範囲を判断できる- 手順が番号付きで、完了条件が明確
- 長い参考情報は
references/へ分離 - 反復可能な処理は
scripts/に置く - 秘密情報や個人専用パスを含めない
- Skill 更新後に実際の依頼で呼び出しを確認する
次は Subagents 設計 で、役割ごとにコンテキストを分離します。
クイズ