writing-skills

スキルの作成

スキルは、タスク固有の知識や、モデルが本来は改めて見つけ出さなければならない信頼できる手順を提供します。正確な結果、有用な根拠、低いオーバーヘッドを優先してください。毎回同じ手順を使うことが有効なのは、順序が契約の一部である場合に限ります。

対象範囲を選ぶ

• ユーザーが求める結果と既存の権限に従ってください。スキルによって承認手順を追加したり、リポジトリのポリシーを覆したりしてはいけません。
• 関連する判断を変える、または根拠のある失敗を防ぐルールだけを残してください。一般論、重複するルール、古くなったモデルの前提、修辞的な圧力は削除してください。
• 説明は簡潔にしてください。切り詰められても使用条件が伝わるよう、最初の文に具体的なタスク、適用条件、主な対象範囲の境界を記載してください。重複が起きそうな場合に限り、対象外の条件を追加してください。手順がより限定された問題にのみ必要な場合は、すべてのコード編集、テスト、完了時に適用されるような説明は避けてください。
• 共通の指針とリポジトリ固有のポリシーを区別してください。まず共通のソースを編集し、同期時にはローカルの差分を維持してください。インストーラーがスキルを上書きする前に、ディレクトリ全体の差分を確認してください。

作成または改訂

1. 結果、対象ファイル、既知の失敗、既存の指示を特定します。現在の会話にある根拠を再利用し、不足している情報や古くなった情報だけを再確認します。
2. SKILL.md には共通の契約の最小限だけを残します。分岐ごとのリファレンスには、適用条件と必要なセクションを添えてリンクします。完全な契約が必要な場合は、完全なスキーマや密接に関連する手順を読みます。通常はすべてのリファレンスを読む必要はありません。
3. 依存関係、変更、権限、後片付けがある場合に限り、必要な順序を明記します。独立した検索はまとめて実行できるようにし、定型的な実装の詳細はエージェントが選べるようにします。
4. 完了条件は、求められた成果物と該当するチェックに基づいて定義します。入力に変更がなければ既存の根拠を再利用します。スキルがインストールされているというだけの理由で、必須レポート、サブエージェントの追加ラウンド、テストスイート、確認手順を加えてはいけません。
5. 変更した適用条件、リンク、メタデータ、および影響を受けるヘルパーの動作を確認します。短い文章の編集ではこのレビューを要約し、新しいスキルや広範な書き直しでは references/checklist.md を使用します。重大な問題は、その発生源で修正してください。

新しいパッケージを作成する場合は、references/authoring-procedure.md を読みます。assets/SKILL.template.md は任意のひな形です。同梱されたヘルパーは、スキルの実際のディレクトリを基準に解決してください。読み取り専用のメタデータヘルパーは python3 <writing-skills-dir>/scripts/validate-metadata.py --name "[name]" --description "[description]" です。

診断と測定

必要なリファレンスを見落とした場合は、references/loading-diagnosis.md を使って、不適切な適用条件、アクセスできないパス、競合するルール、古い内容、モデルの誤りを区別します。関連する参照先を補強するか、ヘルパーを修正してください。強調を追加することは、通常の修正方法ではありません。

動作を変える指針は、可能であれば同じモデル／ハーネスで代表的なタスクを使って評価します。正確性、やり直し、不要な質問、ツール呼び出し、所要時間を確認してください。対照として成功した実行も含めます。リファレンスの読み込み回数やスキルの実行回数はコストまたは診断情報として数え、それ自体を成功とはみなしません。静的レビューのみを行った場合は、その旨を明記してください。比較実行なしに改善を測定したと主張してはいけません。

必要に応じて、用語については references/glossary.md を参照してください。