skill-standardization

スキルの標準化

このスキルを使うタイミング

• SKILL.md を新規作成するとき
• 既存のスキルが Agent Skills 仕様に準拠しているか監査するとき
• 弱いトリガーの説明や古くなったルート案内を修正するとき
• 重複するスキルを、デフォルトのスキルと互換性エイリアスに正規化するとき
• スキルの追加／名前変更／削除／エイリアス設定後に、リポジトリレベルの検出やカタログの不整合を検証するとき
• 大幅な書き換え後に SKILL.toon／SKILL.compact.md の不整合を確認するとき

手順

ステップ 1：最小限の作業モードを選ぶ

references/working-modes.md を参照し、主要モードをちょうど 1 つ選びます。

1. 既存のスキルを 1 つ検証または修正する
2. SKILL.md を作成または書き換える
3. 重複を正規化する
4. 構造的なカタログ／検出の同期を行う
5. 大幅な書き換え後に派生サーフェスを同期する

これらのモードのいずれかで作業を解決できる場合は、最初から複数の作業を混ぜた大規模な一括処理を始めないでください。

ステップ 2：現在の作業ディレクトリに合った、正確なバリデーターコマンドを実行する

jeo-skills リポジトリのルートでメンテナンス作業を行う場合は、次を使用します。

bash .agent-skills/skill-standardization/scripts/validate_skill.sh .agent-skills/<skill-name>

.agent-skills/skill-standardization 内から実行する場合は、代わりに references/working-modes.md に記載されているスキルローカルの形式を使用します。現在の作業ディレクトリで実際に有効でない限り、リポジトリのルート向け手順書にそのままの scripts/... コマンドを記載しないでください。

バリデーターは次の項目を確認します。

• 必須のフロントマター（name、description）
• ディレクトリ名として安全な命名
• 説明の長さと命令形のトリガー表現
• 推奨セクション
• ファイルの長さに関する警告

リポジトリ固有のバリデーターに関する注意点：

• validate_skill.sh は、通常のアポストロフィやシェル風のテキストを含む有効な複数行の description: > ブロックを受け入れる必要があります。文章中の引用符が原因で失敗する場合は、スキルの説明を弱めるのではなく、バリデーターの修正が必要な不具合として扱ってください。
• シェルの解析に合わせるためだけに自然な文章を書き換えるのではなく、バリデーターを修正するか、回帰テストケースを追加してください。

ステップ 3：主要な SKILL.md を修正または作成する

スキルを作成または書き換える場合：

• 説明はトリガーを中心にし、スキルを使うタイミングを具体的に記述します
• 例外ケースを挙げる前に、主な目的が明確に分かるようにします
• 最初の案内はルーティングを優先します。例、チェックリスト、テンプレートなど、変更頻度の低い内容がメインのスキルを圧迫し始めたら、references/ に移します
• SKILL.md は 500 行未満にし、高頻度のルーターとして使うスキルでは、できるだけ小さく保ちます

肥大化したひな形を手作業でコピーするのではなく、references/working-modes.md にある簡潔なテンプレートと従来の見出しマップを使用してください。

ステップ 4：ほかの調整より先に説明の品質を高める

説明が弱いと、スキルは起動されません。次のパターンを使用してください。

description: >
  [What it does — list specific operations.]
  Use when [trigger conditions]. Even if the user does not explicitly
  mention [domain keyword] — also triggers on: [synonym list].

説明のルール：

1. 命令形を使います — 「Use when...」
2. 内部実装ではなく、ユーザーの意図を記述します
3. 周辺の同義語や、エッジケースのトリガーを含めます
4. 1024 文字未満にします
5. 隣接するスキルを優先すべき場合は、ルート案内を正確に保ちます

ステップ 5：動作を大幅に変更した場合は、必ず評価を追加する

スキルの追加、トリガー対象の書き換え、またはエイリアスへの範囲縮小を行う場合は、evals/evals.json を作成または更新してください。

適切な評価範囲には、次の項目が含まれます。

• スキルが明確に起動されるべき通常のプロンプト
• 別のスキルにルーティングされるべき、よく似ているが該当しないプロンプト
• 該当する場合、カタログ／検出の同期を確認する構造変更のプロンプト
• リポジトリで SKILL.toon／SKILL.compact.md が重要な場合の、コンパクト形式／検出サーフェスの確認

アサーションは具体的で検証可能なものにしてください。

ステップ 6：重複するスキルを競合させず、正規のスキルに統合する

2 つのスキルが同じ標準的な用途を十分に近い形でカバーしており、それぞれの name + description メタデータが競合する場合：

1. 正規のスキルを選びます
2. 通常のプロンプトで正規のスキルが選ばれるよう、その説明を明確にします
3. 古いワークフローや正確な名前でのインストールが引き続き依存している場合は、重複するスキルを用途を絞った互換エイリアスにします
4. 両方について評価項目を追加します
5. 同じ変更で検出用の各箇所も同期し、ユーザーに競合する 2 つのスキルとして誤認されないようにします
6. エイリアスに、正規の契約を再掲するサポート資料や例が含まれている場合は、エイリアス側の資料も更新し、古いラチェット適用前のパケット形式を引き続き案内しないようにします

完全な削除は通常、最初に行うことではなく、後のステップです。

ステップ 7：追加／名前変更／削除／エイリアス化／大幅な再配置の後に、構造的なカタログ同期を実行する

jeo-skills のリポジトリレベルのずれには、次を使用します：

python3 .agent-skills/skill-standardization/scripts/validate_catalog_sync.py --repo-root /Users/jang_jennie/projects/jeo-skills

ポータブルな形式：

python3 .agent-skills/skill-standardization/scripts/validate_catalog_sync.py --repo-root /path/to/repo

カタログバリデーターはガードレールとして扱い、作業のすべてを担うものとは考えないでください。メンバーシップ／件数／パスのずれは確認しますが、派生した検出用文言やコンパクト版の鮮度を手動で確認する作業の代わりにはなりません。

ステップ 8：書き換えが大幅な場合は、派生した検出用の各箇所を同期する

SKILL.md で、達成したい作業、振り分け先、サポート対象のユースケースを大幅に変更した場合は、必要に応じて以下を確認し、更新してください：

• スキル内の SKILL.toon / SKILL.compact.md
• 正規の契約を反映したエイリアス側のサポート資料やチェックリスト
• .agent-skills/skills.json
• .agent-skills/skills.toon
• README.md
• README.ko.md
• setup-all-skills-prompt.md

これらの箇所のいずれかを変更する必要がない場合は、その理由を説明できるようにしてください。

ステップ 9：作業完了とする前に、残存項目を検索する

サポート資料を多く含む書き換えや構造的な書き換えの後は、明らかな残存項目を検索します：

• 古いファイル名やパス
• 削除済みのコマンド例
• 古い正規スキルとエイリアスの表現
• 古い用途を引き続き案内しているコンパクト版／検出用テキスト

結果がベースラインよりも正確で、他に応用しやすい場合にのみ、この作業を完了としてください。

利用可能なスクリプト

• bash .agent-skills/skill-standardization/scripts/validate_skill.sh <skill-dir> — 1 つのスキルを検証します
• bash .agent-skills/skill-standardization/scripts/validate_skill.sh --all .agent-skills/ — 一括検証します
• python3 .agent-skills/skill-standardization/scripts/validate_catalog_sync.py --repo-root /path/to/repo — 実際のフォルダーとカタログ／検出用の各箇所を比較します
• bash .agent-skills/skill-standardization/scripts/regression_folded_description_quotes.sh [repo-root] — アポストロフィやシェル風のテキストを含む折りたたみ形式の説明を回帰チェックします

例

例 1：リポジトリのルートから 1 つのスキルを検証する

bash .agent-skills/skill-standardization/scripts/validate_skill.sh .agent-skills/my-skill

例 2：リポジトリ全体を一括検証する

bash .agent-skills/skill-standardization/scripts/validate_skill.sh --all .agent-skills/

例 3：名前変更またはエイリアス変更後にカタログ／検出用の同期を確認する

python3 .agent-skills/skill-standardization/scripts/validate_catalog_sync.py --repo-root /path/to/repo

スキルの追加、名前変更、削除、正規化の後にこれを実行すると、古いマニフェスト項目、誤った項目数、派生した各箇所の更新漏れが残るのを防げます。

例 4：よくあるフロントマターの問題を修正する

# WRONG
metadata:
  tags: [tag1, tag2]
  platforms: Claude

# CORRECT
metadata:
  tags: tag1, tag2
allowed-tools: Bash Read Write

ベストプラクティス

1. まず説明の品質を高める — 説明が不十分だと、スキルは起動しません
2. 高頻度で使われるルーターを小さく保つ — 冒頭部分がハンドブックになる前に、変更頻度の低い詳細を references/ に移します
3. コマンドの実行パスを正確に記載する — リポジトリルートとスキル内のどちらで実行するかを明示します
4. スクリプトは非対話型で構造化する — フラグと機械可読な出力を優先します
5. 公開前に評価テストを追加する — 起動すべきケース、起動すべきでないケース、構造変更のケースを網羅します
6. コンパクト版や検出用のファイルは派生物として扱う — 大幅な書き換えの後に更新するか、更新しない理由を記録します
7. 重複項目を増やさず、正規の項目に統一する — デフォルトのスキルを1つにし、互換性エイリアスを使います
8. 正規の契約が変更されたら、エイリアス側の関連サポートも同期する — エイリアスに古いパケット形式を再記述したチェックリスト、リファレンス、例がある場合は、同じ作業の中で更新し、古いガイダンスがひそかに残らないようにします
9. 構造を書き換えた後は残存物をスキャンする — バリデーターを通過しても、古いファイル名、コマンド、検出用の記述が残っていることがあります

リファレンス

• Agent Skills 仕様
• 説明の最適化
• スキルの評価
• スクリプトの使用
• スキルサポートの追加