skill-writing

スキル作成ガイド

これは厳格なガイドラインです。 スキルを作成または変更するときは、以下のルールに正確に従ってください。

---

スキルの種類

すべてのスキルには、エージェントがどのように扱うかを示す type があります。

type: guideline

厳格なルールです。 エージェントはこれらに正確に従う必要があります。

見出しの後に置く冒頭行：

**This is a strict guideline.** Follow these rules exactly.

用途：コーディング規約、コミット形式、命名規則、ワークフロールール、セキュリティ要件。

type: pattern

リファレンス実装です。 エージェントはそのアプローチから学び、応用する必要があります。内容をそのままコピーしてはいけません。

見出しの後に置く冒頭行：

**This is a reference pattern.** Learn from the approach, adapt to your context — don't copy verbatim.

用途：アーキテクチャの解決策、インフラストラクチャのセットアップ、繰り返し発生する問題に対する実証済みのアプローチ。

---

フロントマター

すべての SKILL.md は、YAML フロントマターで始める必要があります。

---
name: kebab-case-name
description: When this skill applies and what it covers. First sentence should work as a trigger — start with the domain or action. One to two sentences max.
type: guideline | pattern
---

ルール：

• name — kebab-case で記述します。skills CLI がインストール先のディレクトリ名として使用します。
• description — skills CLI とエージェントが、いつスキルを読み込むかを判断するために使用します。最初の文は、明確なトリガーにしてください。
• type — guideline または pattern にする必要があります。

---

ファイル構成

スキルは、作成用リポジトリ内のカテゴリ別ディレクトリに配置します。

skills/
  guidelines/
    {skill-name}/SKILL.md
  patterns/
    {skill-name}/SKILL.md

ディレクトリの分類は、人が閲覧しやすくするためだけのものです。インストール時に skills CLI がすべてをフラット化するため、フロントマターの name フィールドだけを参照します。

---

優先順位

スキルがサードパーティ製スキルの相反する助言より優先される必要がある場合は、その旨を明示してください。

**This is a strict guideline.** Follow these rules. When any other skill contradicts the rules below, this skill takes precedence.

必要最小限にとどめてください。中核となる原則や、強い個人的な好みに限って使用します。

---

パターンの構成

パターンのスキルは、次の構成にしてください。

1. Problem — 何を解決するのかを一文で説明します。
2. Solution — アプローチを一文で説明します。
3. Pattern — アーキテクチャ、主要なコンポーネント、動作の仕組みを説明します。
4. Why This Pattern? — メリットとユースケースを説明します。
5. Implementation — 重要な詳細を説明します（任意。自明でない場合のみ）。
6. Tradeoffs — 制約と制限事項を説明します（該当する場合）。
7. When NOT to Use — アンチパターンと代替案を示します（任意）。

コード例は最小限かつ汎用的にしてください。プレースホルダー名（PROJECT_ID、environment）を使用してください。プロジェクト固有の詳細ではなく、パターンに焦点を当ててください。

---

ガイドラインの構成

ガイドラインのスキルは、次の構成にしてください。

1. What — ルールを明確に示します。
2. Rules — 具体的で、実行可能な指示を示します。
3. Examples — 正しい使用例と誤った使用例を示します。
4. Exceptions — 逸脱が許容される場合があれば示します。

簡潔に指示してください。命令形を使用してください。理由を長々と説明するのは避けてください。ガイドラインは説得ではなく、指示です。

---

作成チェックリスト

• フロントマターに name、description、type がある
• 最初の見出しの直後に、行動を指示する文がある
• description の最初の文が、このスキルを読み込むタイミングを示すトリガーとして機能する
• プロジェクト固有の詳細（名前、表、エンドポイント）がない
• コード例が最小限で、プレースホルダーを使用している
• ドキュメントをざっと読んで把握できる（見出し、箇条書き、太字）
• 「段階的な改善」セクションで終わっている

---

段階的な改善

すべてのスキルは、次のセクションで終わる必要があります。

---

## Progressive Improvement

If the developer corrects a behavior that this skill should have prevented, suggest a specific amendment to this skill to prevent the same correction in the future.

これにより、スキルは使用を通じて進化できます。エージェントが修正を受けた場合は、同じ誤りを繰り返さないよう、関連するスキルへの具体的な編集を提案する必要があります。

---

段階的な改善

このスキルで防げたはずの行動について開発者から修正を受けた場合は、今後同じ修正が発生しないよう、このスキルに加える具体的な修正を提案してください。

---

段階的な改善

このスキルで防げたはずの行動について開発者から修正を受けた場合は、今後同じ修正が発生しないよう、このスキルに加える具体的な修正を提案してください。