スキルオーサリングは何をしますか？

エージェントの行動を実際に変えるスキルを作成するためのガイド。決して読まれないドキュメントではありません。

基本原則: スキルは運用マニュアルであり、記事ではありません。 このスキルを読み込んでもエージェントの動作が変わらなければ、そのスキルは失敗です。

このスキルの使い方

このスキルは会話形式で使用し、一発で完了するものではありません。流れは以下の通りです:

ユーザーがスキルをトリガーする（例: 「スキルオーサリングを使って、エージェント用のスキルを作りたい」）。
エージェントは書き始めるのをやめ、ステップ1のインタビューを開始する。1回のターンにつき1つの質問、回答を待つ。
5つの質問すべてに回答があったら、エージェントはステップ2から5を実行し、ドラフトをユーザーに提示する。
ユーザーが承認したら、エージェントはファイルを書き（ステップ6）、トリガーテスト（ステップ7）とチェックリスト（ステップ8）を実行する。

エージェントのルール:

ステップ1の5つの質問にすべて回答があるまでは SKILL.md を書いてはいけない。早期のドラフトはインタビューを止めてしまう。
5つの質問を一度に提示してはいけない。1ターンに1つずつ、各質問に短い例を添えること。
ユーザーが「簡単な例だけ」と言ってきた場合でも、質問1と4だけは必ず聞き、その後続行する。
最初に、最終成果物はすぐに使える SKILL.md 1ファイルであることを伝える。

このスキルが有効なとき

ユーザーが「スキルを作る」「スキルを書く」「スキルの作成方法」「エージェント用のスキル」と言ったとき。
ユーザーがエージェントに能力のアイデアはあるが、どうやって形にすればいいか困っているとき。
既存のスキルがトリガーされない、またはエージェントがそれを無視しているとき。
これがスキル、エージェント、コマンド、フックのどれにすべきか判断が必要なとき。

既存のスキルを探すには、まず skill-scout を使用する。スキルが溜まりすぎている場合の監査には skill-stocktake を使用する。

ステップ0 - 書き始める前の基本ルール

優れたスキルには4つの特性がある:

特性	意味
具体的	1つの作業タイプに答える。「バックエンド全般」ではない
実用的	手順、コマンド、実際の例を含む。理論ではない
トリガー可能	`description` にユーザーが実際に使う言葉が含まれている
制限付き	500行未満。理想的には100〜250行

スキルのアイデアがこの4つを満たしていない場合は、まずアイデアを修正し、ファイルを書いてはいけない。

ステップ1 - 機能ではなく、実際の問題を捉える

「テスト用のスキル」から始めてはいけない。具体的な失敗から始める。

この5つの質問をユーザーに投げかける（1つずつ、一度にまとめてはいけない）:

エージェントが今、間違っている、または一貫性がないことは何？実際の例を1つ挙げてください。
それはいつ起こりますか？（コードを書いているとき、PRレビュー中、デプロイ中、ユーザーへの回答中、データ分析中）
正しい結果はどのようなものですか？ユーザーが良いと思う出力の例を1つ示してください。
エージェントが知らない、このスキルを通じて伝えるべき情報は何ですか？（チームの慣習、手順、落とし穴）
このスキルを実行するときに、エージェントがやってはいけないことは何ですか？

質問4と5への回答がスキルの実際の内容です。質問1と2への回答が description の内容です。

ユーザーが質問1に答えられない場合、プロセスを中止する。作成すべきスキルはまだありません。それは単なる願望です。その旨を伝えてください。

ステップ2 - 適切な形式を選ぶ

すべてをスキルにしてはいけません。問題を解決する最も軽量な形式を選びましょう。

ニーズ	形式	理由
コードを書くときに繰り返し使う知識・慣習	スキル	自動ロード、呼び出し不要
独立した複数ステップの作業（個別コンテキスト）	エージェント	並列実行可能、独自コンテキストを持つ
ユーザーが意識的に引数付きでトリガーするアクション	コマンド	`/{名前}` 明示的、自動ではない
イベント発生時の自動動作（コミット前、編集後など）	フック	モデルの判断なしで実行
すべての作業に適用される短いルール	ルール	常時アクティブ、トリガー不要
人間が読むための長い説明	ドキュメント	エージェントがロードする必要なし

実用的な判断基準:

トリガーが必要？→ スキル
個別コンテキストや限定ツールが必要？→ エージェント
手動でパラメータ付き呼び出しが必要？→ コマンド
依頼なしで実行が必要？→ フック
常に守られ、決して破られない必要？→ ルール
人間が読むものでエージェント向けではない？→ ドキュメント

スキルとルールで迷った場合: 内容が10行未満でどこにでも適用されるなら、それはルールです。

ステップ3 - まず重複を探す

書く前に、まず探す。スキルフォルダはハーネスごとに異なる。ユーザーの環境に合わせてください:

ハーネス	スキルフォルダ
Claude Code	`~/.claude/skills/` またはプロジェクト内の `.claude/skills/`
OpenCode	`~/.config/opencode/skills/` または `.opencode/skills/`
Cursor	`.cursor/skills/`
Codex	`.agents/skills/`

# 既にインストールされているスキルを検索（<スキルフォルダ>は上の表に従って変更）
grep -ril "キーワード" <スキルフォルダ> --include=SKILL.md

# プロジェクト内に skills/ フォルダがある場合
cd プロジェクトルート
grep -ril "キーワード" skills --include=SKILL.md

ユーザーが自分のスキルフォルダを知らない場合は、上の表を説明し、使用しているハーネスを選んでもらう。推測してはいけない。

既に近いものがある場合、選択肢は: そのまま使う、既存を拡張する、新しく作る。重複スキルはエージェントを混乱させ、コンテキストを圧迫する。

ステップ4 - `description` を書く（最も重要な部分）

description は、エージェントがスキルをロードするかどうかを判断するために読む唯一の部分です。ここを間違えるとスキルは死にます。

公式:

[実行するアクティビティ] + [トリガーとなるコンテキスト] + [ユーザーが使うキーワード] + [使わないとき]

悪い例:

description: テストを支援します

良い例:

description: ReactコンポーネントのVitestとTesting Libraryによるテストパターン - レンダリング、ユーザーイベント、ネットワークモック、アクセシビリティアサーション。Reactコンポーネントのテスト作成や修正時に使用します。E2Eテストには使用しないでください（e2e-testingを使用）。

ルール:

ユーザーが実際にタイプする言葉を使い、内部用語は使わない。
他のスキルの領域を侵さないよう、範囲の境界を明記する。
1行。文字列内に改行を入れない。
「コード」「ヘルプ」「様々」のような単一の汎用語は避ける。

簡単なテスト: ファイルを閉じて、description だけを読む。エージェントとして、いつロードすべきか正確にわからないなら、書き直す。

ステップ5 - 内容を構成する

実績のあるセクション構成:

---
name: スキル名
description: <ステップ4の公式>
metadata:
  origin: ECC
---

# タイトル

1段落: このスキルがエージェントの行動をどう変えるか。

## 有効なとき
具体的なトリガーのリスト。

## コア
作業手順、判断表、ルール。これがスキル内容の70%。

## 例
間違った例1つ、正しい例1つ。実際のもの。プレースホルダーではない。

## アンチパターン
避けるべき間違いとその簡単な理由。

## チェックリスト
検証可能なチェックボックス。

## 関連スキル
2〜4つのスキル名。

内容を書くときのルール:

命令文（「Xを実行する」）を使い、受動態（「Xは実行可能です」）は使わない。
判断には表、順序には番号付きリスト、コマンドにはコードブロックを使う。
各ルールは検証可能であること。「きれいなコードを書く」は不可。「関数は最大50行」は可。
エージェントが実行する部分には [ここに入力]、TODO、... のようなプレースホルダーを入れない。
外部製品のアイデンティティを丸写ししない。アイデアを抽出し、自分のコンテキストで書き直す。
秘密情報（APIキー、トークン、絶対パス、社内名前）を含めない。

長さの制限: 500行（最大厳守800行）。超える場合は、2つのスキルに分割するか、詳細を同じスキルフォルダ内の references/ に移動する。

ステップ6 - ファイルを書く

書き始める前に、最後の2つを確認する:

スキルの言語 - ユーザーが日常的に使う言語か、移植性のために英語か？ユーザーの答えに従い、勝手に選ばない。
フォルダ名 - 説明的なkebab-caseを提案し（例: test-komponen-react）、承認を得る。

次に <スキルフォルダ>/<名前>/SKILL.md に書き込む。絶対に破ってはいけないルール:

フロントマターの name: はフォルダ名と完全に一致していること。これがないと、一部のハーネスはスキルをロードしない。
完全なドラフトをまずユーザーに表示してから保存する。こっそり保存してはいけない。
エージェントが実行する部分にプレースホルダー（TODO、[ここに入力]、...）を含めない。
保存後、完全なパスと、スキルをトリガーする1行の説明を報告する:「これで、<トリガー>のときにエージェントにスキル<名前>を使うように依頼してください。」

ステップ7 - 使う前にテストする

最低3つのテスト。どれも省略してはいけない。

テスト1 - ポジティブトリガー（発動） スキル名を言わずに、このスキルをトリガーすべきタスクをエージェントに与える。

「LoginButtonコンポーネントのテストを書いてください。」

合格条件: スキルがロードされる。失敗条件: description にキーワードが不足している。

テスト2 - ネガティブトリガー（発動しない） 似ているが、スキルの範囲外のタスクを与える。

「ログインフローのE2Eテストを書いてください。」

合格条件: スキルがロードされない（またはエージェントが別の適切なスキルを選ぶ）。失敗条件: description が広すぎる。

テスト3 - 実行 スキルを実際にトリガーするタスクをエージェントに依頼し、出力をスキルがない場合と比較する。

スキルなし: エージェントはスタイルXでテストを書く
スキルあり: エージェントはスタイルYでテストを書く（チーム規約に従う）

合格条件: 示せる行動の違いがある。出力が同じなら、スキルは無価値。削除するか統合する。

ステップ8 - リリース準備完了チェックリスト

自動検証は、ユーザーのリポジトリで利用可能な場合のみ:

# ECC / スキルバリデーターがあるリポジトリ
node scripts/ci/validate-skills.js

バリデーターがない場合、最も失敗しやすい4つを手動で確認する: name: がフォルダと一致、description が1行、行数が500未満、プレースホルダーがない。この手動チェックを使用することをユーザーに伝える。

すぐに使えるテンプレート

---
name: スキル名
description: <アクティビティ> - <範囲>。<具体的なトリガー>のときに使用。<範囲外>には使用しない。
metadata:
  origin: ECC
---

# スキル名

このスキルをロードした後、エージェントの行動がどう変わるか。

## 有効なとき
- <トリガー1>
- <トリガー2>

## 手順
1. <すぐに実行できる最初のステップ>
2. <2番目のステップ>
3. <検証>

## 例
間違い: <よくあるコードや回答>
正解: <望ましいバージョンと簡単な理由>

## アンチパターン
- <間違い> - <なぜ悪いか>

## チェックリスト
- [ ] <機械や目で確認できるもの>

## 関連スキル
- `<スキルA>`, `<スキルB>`

オーサリングのアンチパターン

トリガーのないスキル。 description が曖昧で、スキルがロードされない。これが最も一般的な失敗原因。
テキストの壁のスキル。 900行の理論に1つの命令もない。エージェントはロードするが無視する。
「親切であれ」スキル。 具体的な知識がなく、結果はスキルなしと同一。
重複スキル。 2つのスキルが同じ領域を主張。エージェントはランダムに選ぶ。
他人のスキルを丸ごとコピー。 気づかないうちに隠れた命令や依存関係が含まれる。
秘密やパスを含むスキル。 スキルを共有したときに漏洩する。
一度きりのイベントのためにスキルを書く。 1回だけ使うなら、それはスキルではなく、ドキュメントかコマンド。
探す前にスキルを作る。 必ずステップ3を実行する。

スキルを作る必要がないとき

以下のいずれかに該当する場合は、率直にユーザーに伝える:

問題がコードのバグであり、エージェントの知識不足ではない。
1回だけ実行すればよい。直接指示を与えるだけで十分。
内容が10行未満の一般的なルール。それはルールです。
プロジェクトの AGENTS.md や CLAUDE.md に追加するだけで十分。
80%のニーズをカバーするスキルが既に存在する。既存のものを拡張する。

スキルオーサリング