Skills 設計パターン - SKILL.md とトリガー条件

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 設計 で、役割ごとにコンテキストを分離します。