write-great-skill

優れたスキルを書く

スキルとは、エージェントが独力では知らない手順を教えるフォルダーです。状況が発生したときにエージェントが読み込み、それまでは読み込みません。あなたの役目は、ユーザーの頭の中にある手順を引き出し、判断と作業手順に分け、適切なリクエストに反応するフォルダーとして仕上げることです。

手順

1. 聞き取りを行います。 推奨する回答を添えて、質問を1つずつします。

   • トリガー： どのような状況でこのタスクを開始しますか？ ユーザーは具体的にどんな言葉を入力しますか？ 実際の言い回しを3～5個集めます。
   • 知識： ユーザーが知っていて、どのモデルも知らないことは何ですか？ コマンド、パス、手順の順序、システム名、よくある原因などです。
   • 禁止事項： 絶対に起こしてはいけないことは何ですか？ 回答のそれぞれを、厳守ルールまたは注意点にします。
   • 作業手順： 毎回同じ手順はどれですか（コマンド、チェック、決まった形式のファイルなど）？ それぞれをスクリプトにします。
   • 配置先： このリポジトリのみ（.claude/skills/<name>/。git で共有）ですか、それともすべてのリポジトリ（~/.claude/skills/<name>/）ですか？ 他のツールも同じ形式の専用スキルフォルダーを使用します。

   ユーザーがすでに資料（チェックリスト、ランブック、ドキュメント）を提供している場合や、回答できる人がいない場合（ヘッドレス実行）は、その資料から回答を導き、前提を明記して続行します。すべての手順を列挙し、それぞれを判断または機械的な手順に分類できたら完了です。

2. まず説明文を書きます。 エージェントは、どのスキルを読み込むか判断するとき、説明文だけを見ます。曖昧な説明文は選ばれません。

   • モデル向けに、ユーザーの言葉で書きます。最初の文では、57文字以内でタスクを説明します（Hermes に表示されるのはそこまでです）。続けて、手順1で集めた言い回しを使って Use when … と書き、何をするのか、何を決してしないのかを説明します。
   • 1,024文字未満に収めます（Agent Skills 仕様の上限）。Claude Code では一覧表示が1,536文字で切られます。
   • 選ばれない例：デプロイを支援します。 選ばれる例：本番環境またはステージング環境にデプロイします。ユーザーが「deploy」「ship」「release」「push to prod」「roll back」と言ったときに使用します。

   手順1のすべての言い回し、またはそれに近い表現が説明文に含まれていれば完了です。

3. references/skill-template.md をもとにフォルダーを作成します。 SKILL.md は短いエントリーポイントです（100行未満を目安にします）。機械的な手順は scripts/ に、特定の手順でのみ必要な長い資料は references/ に、作業例は examples/ に置きます。エージェントが補足ファイルを読むのは、手順から参照先が示されたときだけです。

   • 判断は指示として記述し、作業手順はスクリプトにします。 モデルは決定論的ではありません。文章で書かれた手順は、実行するたびに異なる可能性があります。コマンドの一連の実行、チェック、決まった形式のファイルは scripts/ に置き、SKILL.md から正確なコマンドラインで呼び出します。
   • スキルの主な処理を行うスクリプトにはスキル名を付けます（scripts/<name>.sh）。各補助スクリプトには、対応する手順にちなんだ名前を付けます（scripts/<step>.sh。たとえば、事前チェックです）。
   • スクリプトは最初のエラーで停止し（set -euo pipefail）、引数と実行前提をチェックして、各手順を表示します。プッシュ、タグ付け、デプロイ、公開、送信を行うスクリプトは、既定でドライランを実行し、--yes を指定した場合のみ実行します。SKILL.md には、まずドライランを表示して承認を得るよう記載します。
   • すべての手順に、命令形のアクション文、正確なコマンド・パス・名前を続け、最後にエージェントが確認できるチェックを含む Done when … を記載します。
   • 各参照資料は、それを必要とする手順から1階層でリンクします。
   • 手順1の「禁止事項」と、ユーザーが挙げたすべての落とし穴を盛り込んだ ## Gotchas を追加します。

   すべての機械的な手順がスクリプト呼び出しになり、すべてのスクリプトが bash -n（または使用する言語の構文チェック）に通り、副作用なしでドライランまたは --help を実行できたら完了です。git push を実際にテストする場合は、ローカルの bare クローンを指定します（git clone --bare . <tmp>/origin.git）。ユーザーの実アカウント（クラウド、パスワードマネージャー、決済プロバイダー、本番環境）に対して、スクリプトをテストしてはいけません。代わりに、ツールの --help を確認してください。

4. エージェントがすでに知っていることは削ります。 各行について、これがなくてもエージェントは同じことをするかを考えます。「コードをきれいに書く」「意味のある名前を使う」「ベストプラクティスに従う」といった行は何も変えないため、削除します。その行がなくても振る舞いが変わらないなら、その行は何の効果もなく、実行のたびにコンテキストを消費します。行は、エージェントの既定の振る舞いから外すための情報、つまりこのシステム固有の事実、このチームの順序、落とし穴に使います。すべての行にコマンド、パス、数値、名前、または記載がなければエージェントが破るルールのいずれかが含まれていれば完了です。

5. チェックします。 node <this-skill>/scripts/check-skill.mjs <new-skill-folder> を実行します。フロントマター、名前、説明の長さと最初の文、存在しないファイルへのリンク、実行可能ビットのないスクリプト、TODO マーカー、SKILL.md の長さ、埋め草の表現をチェックします。終了コードが 0 になり、すべての警告が修正済み、または理由が明記されていれば完了です。

6. ユーザーと一緒に精査します。 フォルダーツリー、説明、各スクリプトを提示します。references/review-checklist.md に沿って確認します。「これが必要なとき、どんな言葉を入力しますか？」と尋ねます。不足している言葉を説明の先頭に追加します。ヘッドレスの場合は、未解決の質問をレポートの最後に列挙します。ユーザーの承認を得るか、未解決の質問が列挙されていれば完了です。

7. トリガーをテストします（claude CLI が必要です）。スキルをインストールしたフォルダーから、スキル名を含まず、トリガーされるべきリクエストを 3 件指定して <this-skill>/scripts/fires.sh <skill-name> "<request>" ... --not "<request>" を実行し、続けて --not とトリガーされるべきでないリクエストを 1 件指定します。トリガーされなかった場合は、不足しているユーザーの言葉を説明の先頭に追加して、もう一度実行します。スクリプトが PASS（3 件中 3 件がトリガーされ、否定条件ではトリガーされない）と表示すれば完了です。

エージェント向けの書き方

• 短い命令文にします。「実行する」「停止する」「尋ねる」のように書きます。1 文につき 1 つの指示にします。
• 具体的に書きます。「プロジェクトをビルドする」ではなく npm run build、「数回」ではなく「最大 3 回再試行する」と書きます。
• 1 つの事柄には 1 つの用語を使います。ステップ 2 で「リリースブランチ」と書いたら、ステップ 5 でも「デプロイブランチ」ではなく「リリースブランチ」と書きます。
• 形容詞より例を使います。「明確に」や「堅牢に」と求めるのではなく、良い出力例を 1 つ示します。
• 前置き、動機を説明する段落、「このスキルは役立ちます」といった文は書きません。作業内容から始めます。

注意点

• 説明は要約ではなくトリガーです。本文が完璧でも、説明が曖昧なら実行されません。
• すべての会話に適用するルールはスキルではなく、CLAUDE.md または AGENTS.md に記載します。スキルには手順を記載します。
• 名前には小文字、数字、単一のハイフンのみを使用し、64 文字以内にします。また、フォルダー名と同じにします。
• ステップで読むタイミングが指定されていない限り、エージェントは references/ 内のファイルを読みません。
• スキルにシークレットを記載してはいけません。スクリプトは環境変数またはツールの認証情報ストアから読み込みます。
• 注意点のセクションは増えていきます。エージェントがスキルの中で何かを間違えるたびに、そのスキルの注意点に 1 行追加します。

最終確認日：2026-10-03、Claude Code 2.1.288 を使用（TicketBay のリリーススキル 12/12、ゼロから作成したキー ローテーションの手順書 9/9、自動選択 5/5（インストール済みスキル 144 個）、プロジェクト専用 5/5）

Matt Pocock の writing-for-agents（MIT）に着想を得ています。