make-skill

再現可能なワークフローを、移植可能なエージェントスキルとしてパッケージ化します。出力は自己完結型のスキルディレクトリで、コーディングエージェントが SKILL.md から検出して読み込めます。

フェーズ 1：ワークフローを把握する

不足している情報があれば質問します。

1. 何をするものですか？ — 1 文で説明してください。どのような問題を解決しますか？
2. いつ起動すべきですか？ — 正確なフレーズや状況を具体的に示してください。
3. ユーザーから何を受け取る必要がありますか？ — 実行前に必要な入力です。
4. 何を出力しますか？ — ファイルの変更、コード、チャットへの出力、コマンドなどですか？
5. 手順は何ですか？ — 最初から最後までのプロセスを説明してください。
6. 厳守すべきルールは何ですか？ — 常に行うこと、または決して行わないことです。

現在の会話ですでにワークフローが説明されている場合は、質問する前にそこから回答を抽出します。すでにわかっていることは質問しないでください。

フェーズ 2：フロントマターを記述する

---
name: skill-name           # lowercase, hyphenated, no spaces
description: [What it does]. Use when [specific contexts or requests].
license: MIT
---

説明文が起動条件になります。 エージェントのランタイムは、説明文を使ってスキルを有効にするかどうかを判断します。内容を明確にし、幅広い互換性を保つために 200 文字以内に収めてください。

• スキルが何をするか、そしていつ使うかの両方を含めます
• 具体的な状況やリクエストの種類を示します
• Use when ... のような直接的な表現を優先します
• ワークフローが特定のランタイムに本当に依存している場合を除き、ランタイム固有の要件は含めません

Agent Skills 仕様で定義されているフィールドのみを使用します。スキルに実際の環境上またはランタイム上の制約がある場合に限り、compatibility を追加します。カテゴリ、タグ、作成者など、カタログ専用のフィールドはパッケージのフロントマターに含めないでください。

フェーズ 3：本文を記述する

既存のスキルに求められる品質基準に合った構成は次のとおりです。

[One-liner opener — what this does, what it outputs. No heading above this.]

## Phase 1: [First Phase Title]

[Instructions. Dense. Opinionated. No hedging.]

## Phase 2: [Next Phase Title]

...

## Verify

```text
[ ] [Thing that must be true]
[ ] [Thing that must be true]
[ ] [Edge case handled]
```

変更してはいけないルール：

• 1 文で始めます。前に # Heading を置かないでください。これはエージェントが最初に読む指示です。
• すべての大きなセクションに ## Phase N: Title を使います
• ### 1.1 のサブフェーズを使うのは、フェーズ 1 で分岐が必要な場合（スタックの検出、モードの選択）に限ります
• コードブロックには、擬似コードではなく、実際に実行できるコードを記述します
• 暗黙に失敗したり、ワークフロー全体を破綻させたりする警告は、本文中で太字にします
• 最後は ## Verify とし、コードブロック内に裸の [ ] 項目を記述します（Markdown の - [ ] リスト項目にはしません）
• 全体を 500 行未満にします。長い例は references/guide.md に移します

フェーズ 4：検証セクション

検証セクションは必須です。ユーザーはこれを使って、スキルが正しく実行されたことを確認します。

形式は次のとおりです。フェンス付きコードブロック内に角括弧のみを記述します。

## Verify

```
[ ] [Thing that must be true after the skill runs]
[ ] [Output format is correct]
[ ] [Edge case handled]
[ ] [Common mistake avoided]
```

各項目は確認可能でなければなりません。完了したか、していないかが明確になるようにします。「品質に問題がないこと」のような曖昧な項目は使わないでください。

フェーズ 5：参照資料（必要な場合）

次の場合は references/guide.md を作成します。

• 完全な例を含めると SKILL.md が 500 行を超える
• 複数のバリエーションにそれぞれ専用のセクションが必要
• エッジケースが複雑で、具体例が必要

参照ファイルには、概要だけでなく、実際の入力 → 出力例を含める必要があります。

フェーズ 6：テスト用プロンプト

スキルを起動するはずのプロンプトを 3～5 個、起動しないはずのプロンプトを 2 個作成します。

"make a skill for PR reviews"          ✅ should trigger
"create a skill to audit my code"      ✅ should trigger
"turn this process into a skill"       ✅ should trigger
"review my PR"                         ❌ should not trigger (different skill)
"what skills are available?"           ❌ should not trigger

これらを使って、公開前に説明文を検証します。起動すべきなのに起動しないものがあれば、そのフレーズを説明文に追加します。

フェーズ 7：パッケージ化して検証する

スキル名と完全に一致する名前のディレクトリを 1 つ作成します。ルートに SKILL.md を配置し、任意のリソースは references/、scripts/、または assets/ に格納します。

引き渡す前に、次の項目を確認します。

1. YAML フロントマターを解析し、名前がディレクトリ名と一致することを確認します。
2. 説明文にスキルが何をするか、いつ使うかが 200 文字以内で記載されていることを確認します。
3. 相対 Markdown リンクがすべてスキルディレクトリ内で解決することを確認します。
4. 同梱する参照資料がすべて SKILL.md から直接リンクされ、いつ読むべきかが記載されていることを確認します。
5. リポジトリにスキル検証ツールがある場合は実行します。
6. SKILL.md だけでなく、完全なディレクトリを提供し、インストール後も同梱リソースが保持されるようにします。

検証

[ ] YAML frontmatter uses standard fields only and includes name, description, and license
[ ] Name matches the lowercase hyphenated directory name
[ ] Description states what the skill does and when to use it in 200 characters or fewer
[ ] Body opens with a one-liner — no heading before it
[ ] All sections use ## Phase N: Title format
[ ] Code blocks contain real code, not pseudocode
[ ] Critical constraints are bolded inline
[ ] Verify section uses bare [ ] items in a fenced code block
[ ] SKILL.md is under 500 lines
[ ] Long examples moved to references/guide.md when needed and linked from SKILL.md
[ ] Every relative link resolves and every bundled reference is reachable
[ ] 3-5 test prompts written to validate triggers

注釈付きの移植可能なスキル、複数ファイルの例、よくある構成上の誤りについては、references/guide.md を参照してください。