skill

Skill 管理

/skill コマンドでローカルの SKILL.md ファイルを管理します。共有の実行、委任、状態、フック、チーム、キャンセル、検証、エスカレーションに関する不変条件は templates/AGENTS.md にあります。ここで繰り返すのではなく、そちらのコントラクトに従ってください。

ユーザーまたはプロジェクトのスコープでスキルを作成、確認、検証、更新、整理します。各スキルは具体的で、実行可能で、根拠に基づいており、このコードベースにとって有用な状態に保ってください。

<Use_When>

• ユーザーがスキルの一覧表示、追加、編集、削除、検索、確認、同期、セットアップ、スキャン、検証を依頼したとき。
• 永続的でコードベース固有の解決策またはワークフローをスキルとして記録すべきとき。 </Use_When>

<Do_Not_Use_When>

• 会話からスキルを抽出するには /learner を、短いメモには /note を使用してください。
• このプロンプトを使って、実行時コード、カタログ、フック、インストールロジックを変更しないでください。 </Do_Not_Use_When>

スコープとコマンド

正規のルートは ${CODEX_HOME:-$HOME/.codex}/skills/（ユーザー）と .codex/skills/（プロジェクト）です。スキルは <root>/<name>/SKILL.md に配置されます。

コマンド	コントラクト
/skill list	両方のルートをスキャンし、フロントマターを解析して、名前、説明、トリガー、スコープ、品質/使用状況（利用できない場合は N/A）を表示します。
/skill add [name]	作成ウィザードを実行し、名前を検証し、スコープを選択して、SKILL.md を作成し、そのパスを報告します。
/skill edit <name>	1つのスコープを特定し、メタデータを表示したうえで、説明、トリガー、引数のヒント、本文、または名前変更を更新し、変更を報告します。
/skill remove <name>	スキルを見つけ、スコープとメタデータを表示し、明示的に確認してから、そのディレクトリを削除します。
/skill search <query>	名前、説明、トリガー、本文を大文字小文字を区別せずに検索し、名前とトリガーの一致を優先して順位付けし、文脈を表示します。
/skill info <name>	解析済みのメタデータ、スコープ、パス、本文全体を表示します。存在しない場合は /skill search を提案します。
/skill sync	ユーザーとプロジェクトのスキルを比較し、ユーザーのみ/プロジェクトのみ/共通のエントリを表示して、すべてのコピーまたは上書きを確認します。
/skill setup	両方のルートが存在することを確認し、それらをスキャンしてから、追加、一覧、パターンスキャン、インポート、完了のいずれかを提示します。
/skill scan	対話型メニューなしで、setup のスキャンとインベントリを実行します。
/skill validate	両方のルートのすべてのスキルを検証し、各パスの合格/不合格の結果を報告します。ファイルは決して書き換えません。

引数がある場合は直接コマンドモードを使用し、引数がない場合はガイド付きのセットアップメニューを使用します。

作成コントラクト

不足している値は必ず確認してください:

1. name: 小文字の英数字を単一のハイフンで区切ったもの（[a-z0-9]+(?:-[a-z0-9]+)*）。
2. description: 簡潔で空でない1行の目的説明。
3. triggers: カンマ区切りの認識用語。
4. argument-hint: 任意の呼び出し引数。
5. scope: user または project。

すべてのスキルの先頭に、このフロントマターを記述してください。任意のメタデータとして id、source、quality を追加できますが、必須フィールドを置き換えてはいけません:

---
name: <name>
description: <one-line purpose>
triggers: [<trigger1>, <trigger2>]
argument-hint: "<args>"
# optional: id, source, quality
---

実行可能な本文を使用してください。推奨される最小限の構成は次のとおりです:

# <Skill title>

## Purpose
What durable, codebase-specific outcome does this skill provide?

## When to Activate
Recognition signals, scope, and explicit non-goals.

## Workflow
1. Inspect the named files or inputs.
2. Apply the precise approach and record important assumptions.
3. Verify observable behavior and report evidence.

## Examples / Gotchas
Concrete invocation, edge cases, and failure recovery.

一般的なプログラミングの助言よりも、苦労して得た、自明でない知識を優先してください。実際に役立つ場合は、正確なパス、コマンド、エラーメッセージ、期待される根拠を含めてください。

検証とエラー

成功を報告する前に、ファイルが存在すること、--- のフロントマターで始まること、空でない name と description があること、有効な名前を使用していること、そして空でない本文があることを確認してください。不正な形式または閉じられていない YAML、複数行にまたがる必須のスカラー値、同一スコープ内の重複した名前、欠落したディレクトリやファイル、権限エラー、無効な引数は拒否してください。エラーは次の形式で一貫して報告してください:

✗ Error: <clear message>
→ Suggestion: <specific next step>

終了コントラクト

すべてのコマンドは、簡潔な結果で終了してください。影響を受けたスキルとパスおよび次の操作を伴う ✓、またはエラーと提案を伴う ✗ のいずれかです。キャンセル時や検証のみの実行時はファイルを保持してください。add/edit/sync では、変更されたスコープとメタデータを報告してください。list/search/info/scan/validate では、件数または一致したパス、および失敗があればそれを報告してください。