skill-authoring

スキルの作成 — easy-cheese の規約

このドキュメントでは、obra/superpowers（CSO の原則、プレッシャーテストのゲート）と Matt Pocock のスキルリポジトリ（サイズの上限、作成チェックリスト）を参考に、easy-cheese のスキル作成ルールを定めます。スキルを追加または改訂するすべての人が参照する標準文書です。

---

説明のルール（CSO）

説明は、スキルの選択時にハーネスがモデルに表示する唯一の情報です。説明ではなく、スキルの起動を促すことを最適化してください。

ルール： 1 文目は機能、2 文目は「次の条件で使用します：[起動条件]」とします。ワークフローの要約、パイプライン内の位置を説明する文章、機能の一覧は含めません。

理由：スキルのワークフローを要約した説明は、モデルが SKILL.md の本文を読む代わりに使う近道を作ってしまいます。その結果、スキルは気づかないうちに、1 行の説明だけに依存するようになります。

制約：

• 最大 1024 文字（Codex はこれを超える説明を拒否します）。
• 三人称、現在形。
• 起動条件には、ユーザーが実際に使いそうな具体的な語句を含めます。

テスト： 説明だけを取り出して、この語句だけをもとに、モデルがほかのすべてのスキルよりもこのスキルを選べるかを確認します。選べない場合は、起動条件が不足しています。

---

サイズの上限

SKILL.md の本文は簡潔に保ってください。モデルが話の筋を見失わずに一度で読める本文を目指します。

上限：SKILL.md 本文で推定 3,600 トークン（フロントマターを除く）。このリポジトリで測定した文章密度では、およそ 150 行に相当します。ただし、制限の対象は行数ではなくトークン数です。文章が密な場合、行数は目安になりません。このリポジトリの 16 個すべてのスキルが Anthropic の 500 行ルールを満たす一方で、同じ本文のうち 8 個は 3,600 トークンの上限を超えています。

適用方法： CI では、縮小のみを許可するラチェットとして検証します — .github/scripts/validate_skills.py。基準値は .github/skill-budgets.json に記録され、just update-skill-budgets で再生成されます。ラチェット導入時点ですでに上限を超えていたスキルは、記録された値が適用され、それ以降は縮小のみが認められます。上限以下のスキルは、3,600 トークン未満を維持する必要があります。

Anthropic が公開しているレベル 2 の基準は、500 行または 5,000 トークン未満です。easy-cheese は意図的に、その上限より厳しい基準を採用しています。

実用上の上限：

• 手順ごとのサブプロトコル、参照表、プロンプトテンプレート、大きな例などの補足的な詳細は、名前を付けた references/*.md ファイルに移してください。SKILL.md 本文からそれらを参照し、内容を重複させないでください。
• references/ ディレクトリは、長い合理化のための表、出力形式のテンプレート、詳しいサブプロトコルの手順、グラフの規約を置くのに適しています。
• 分割が効果を発揮するのは、SKILL.md に参照ファイルをいつ読むべきかが記されている場合だけです。参照ファイルは、本文から明示的にリンクされている場合にのみ読み込まれます。本文からの参照なしに文章を references/ に移しても、モデルの読み込みを先延ばしにすることにはならず、表示される上限の対象からトークンを移すだけです。

兆候を見極める： SKILL.md 本文が長くなり、長い「入力」セクションと 3 つのフラグ表の下に「フロー」セクションが埋もれているなら、内容を分割するタイミングです。

由来：この上限は、Matt Pocock のスキルリポジトリ向け「<100 行」という上限を応用したものです。その後、このリポジトリで測定した文章密度をもとに、トークン数で改めて定義されました。

---

規律のセクション

規律スキル（手法を説明するだけでなく、プロセスを徹底させるスキル）では、SKILL.md 本文の ## Discipline セクション、または本文がすでに上限に達している場合は補足ファイル references/<skill>-discipline.md にルールを記載します。

このセクションは簡潔にします。ルールを 1 文で示し、そのルールが破られようとしていることを示す観察可能な兆候を列挙し、必要な対応を明記します。実際に見られた合理化に限り、反論の表を追加してください。

作成時のレビューチェックリスト

スキルを公開する前に、以下を確認してください。

• トリガーが含まれている。 説明には、ユーザーが実際に言いそうな具体的なフレーズが記載されています（機能の説明ではありません）。
• 時間の経過で古くなる情報がない。 スキル本文に、バージョン番号、日付付きの価格、古くなる API エンドポイントを埋め込んではなりません。代わりにドキュメントを参照してください。
• 具体例がある。 インラインまたは references/ ファイルに、少なくとも1つの具体例が含まれています。
• 参照は1階層まで。 SKILL.md 本文は references/*.md ファイルを参照し、それらのファイルからさらに下位の参照先へ Markdown リンクを張っていません。参照ファイルを head のように一部だけ読み込むと、隠れた2段目の参照先の末尾を見落とす可能性があります。SKILL.md から参照されている参照ファイルへのリンクは、横方向の引用であり、2段目の参照には当たらないため問題ありません。
• 規律に関するセクションが短い。 ゲートやループを適用するスキルでは、ルール、ルールに違反しそうな兆候、必要なアクションを数行で示しています。
• 両方に登録されている。 スキルのディレクトリが .claude-plugin/plugin.json の skills 配列に含まれています。CI チェック tests/python/test_plugin_manifest.py::test_claude_plugin_manifest_matches_top_level_skills によってこれが保証されます。

---

まずプレッシャーテストを行う作成ゲート

ルール：失敗するベースラインでサブエージェントを実行するまでは、スキルを公開してはなりません。

新しいスキル本文を書く前に、次の手順を実行してください。

1. 代表的なプレッシャーシナリオを作成します。これは、スキルで改善することを意図したタスクを説明するプロンプトです。
2. そのシナリオで、スキルを有効にせずにサブエージェントを実行します。出力をベースラインとして記録します。
3. 具体的な失敗を特定します。サブエージェントは何を誤ったのか、何を省略したのか、何を誤った枠組みで捉えたのかを確認します。
4. その具体的な失敗に対処するスキル本文を書きます。
5. スキルを有効にしてサブエージェントを再実行し、失敗が修正されたことを確認します。

失敗するベースラインで一度もテストされていないスキル本文は、モデルが実際には抱えていない問題を修正してしまうことがあります。または、指示されなくてもモデルがすでに実行しているワークフローを説明してしまうことがあります。

---

disable-model-invocation フロントマター（候補 — 未適用）

Matt Pocock の skills リポジトリでは、純粋なプロンプト型のスキル（モデルへの再プロンプトなしですぐに実行されるスキル）のフロントマターに disable-model-invocation: true を使用しています。Claude Code のフロントマター検証ツール（.github/scripts/validate_skills.py）は、すでにこのキーを許可しています。

ステータス： ハーネスでの検証待ちの候補です。ハーネスの動作を確認するまでは、easy-cheese スキルに適用しないでください。このキーが設定されているときにハーネスがどう動作するのか、また「すぐに実行する」という意図したセマンティクスに一致するのかを確認してください。適用する前に、検証結果をここに記録してください。