create-skill

name	create-skill
description	会話中に行った作業を再利用可能なスキル（SKILL.md）に変換する。引数不要で起動し、会話履歴から手順・判断・スクリプトを抽出して、暗黙知を徹底的に言語化した高品質なスキルを生成する。Use When: 「スキル化して」「この作業をスキルにして」「/create-skill」で起動。作業完了後に「これスキルにしたい」と言われた場合にも使用。

/create-skill — 作業のスキル化

会話中に行った作業を分析し、誰が読んでもミスなく再現できるスキルを生成する。

---

[Phase 1] 作業分析 & スキル名提案

1-1. 会話履歴の分析

会話全体を振り返り、以下を抽出する：

抽出項目	具体的に見るもの
実行タスク	時系列での操作一覧
使用ツール	MCP、CLI、API、スクリプト
判断ポイント	分岐とその判断理由
修正・リトライ	失敗→修正の箇所と原因
作成スクリプト	ファイルパスと用途
入出力	入力データの形式、最終出力の形式
ユーザー修正指示	ユーザーが「こうじゃない」と言った箇所

1-2. スキル名の提案

.claude/skills/（プロジェクト内）と~/.claude/skills/（グローバル）の既存スキル名を確認し、重複しない名前を3つ提案する。

スキル名の候補：
1. `xxx-yyy` — [1行説明]
2. `aaa-bbb` — [1行説明]
3. `ccc-ddd` — [1行説明]

おすすめ: 1（理由: ...）

命名ルール（公式仕様準拠）：

• 小文字・ハイフン区切り（a-z, 0-9, -のみ）
• 64文字以内
• ハイフンで始まらない・終わらない・連続しない
• 親ディレクトリ名と一致させる
• helper, utils, tools 等の曖昧な名前はNG
• anthropic, claude は予約語のため使用不可

ユーザーに選択を求め、カスタム名の入力も受け付ける。

1-3. 配置先の確認

デフォルトは .claude/skills/{スキル名}/（プロジェクトスコープ）。 グローバルにしたい場合は ~/.claude/skills/{スキル名}/ に配置。

---

[Phase 2] SKILL.md 初稿の作成

2-1. ディレクトリ作成

mkdir -p .claude/skills/{スキル名}

スクリプトや参照ファイルがある場合のみ追加：

mkdir -p .claude/skills/{スキル名}/scripts
mkdir -p .claude/skills/{スキル名}/references

2-2. SKILL.md の構成

公式仕様はSKILL.mdのbody構造を固定していない（「作業に合わせて適応させよ」が方針）。ただし以下のセクションは公式ベストプラクティスで推奨されており、必要に応じて含める：

• frontmatter（必須）: name, description
• 概要: 1-2行でスキルの目的を述べる
• 前提条件: 環境・認証・依存関係（省略するとエージェントが推測して失敗する）
• 手順: ステップごとに入力→操作→出力を明示。作業の性質に応じて構造化する
• Gotchas: 実際に遭遇した落とし穴。公式が「スキルの中で最も価値が高いコンテンツ」と明言しているセクション
• Available scripts: バンドルしたスクリプトの一覧（なければ省略）

2-3. description の書き方（公式ベストプラクティス準拠）

descriptionはスキル発動の唯一のトリガーであり、最も重要なフィールド。

必須要素：

• 何をするか（具体的な動作）
• いつ使うか（ユーザーの意図に焦点）
• トリガーフレーズ（ユーザーが実際に言いそうな言葉）

書き方のルール：

• 命令形で書く（「Use when...」スタイル。「I can help」はNG）
• ユーザーの意図に焦点を当てる（実装手段ではなく）
• 積極的（pushy）に適用範囲を示す（underfireを防ぐため）
• 明示的にドメインを言及しないケースもカバーする
• 1024文字以内

公式の description 構成式： [What it does] + [When to use it] + [Key capabilities]

2-4. body の書き方の原則

• エージェントが既に知っていることは書かない（HTTP、PDF、DBマイグレーション等の一般知識は不要）
• 判断基準： 「この指示がなければエージェントは間違えるか？」→ Noなら削除
• whyを説明する： 「常にXせよ」より「XすべきなぜならY」の方が効果的
• デフォルトを1つ提示し、代替は簡潔に言及するのみ（メニュー形式はNG）
• 手順は汎化する： 特定インスタンスの回答ではなく、再利用可能な方法を記述
• 500行以下、5000トークン以下が目標
• 参照ファイルへのリンクは「いつ読むか」の条件を明記（「詳細は参照」だけではNG）

---

[Phase 3] 暗黙知の徹底的な言語化

これが最も重要なフェーズ。 Phase 2で初稿を完成させた後、一度完全にパイプラインとしての全体像を確認し、そのうえで「書かれていない知識」を徹底的に洗い出す。

3-1. 洗い出しチェックリスト

SKILL.mdの初稿を読み直し、以下を1つずつ自問する。答えがSKILL.mdに書かれていなければ追記する。

環境・前提：

• 必要な認証情報やログイン状態は明記したか？
• 使用するブラウザプロファイルは指定したか？（Playwright使用時）
• 環境変数やAPIキーの取得・設定方法は書いたか？
• 前提ファイルやディレクトリの存在確認手順を含めたか？
• 必要なパッケージのインストール方法は書いたか？

手順の詳細：

• 各ステップで「何を入力し、何が出力されるか」は明記したか？
• 待機が必要な箇所（sleep、ページ読み込み等）は書いたか？
• 条件分岐（if A then X, if B then Y）は網羅したか？
• エラー発生時の対処法（リトライ回数・待機秒数含む）は書いたか？
• 操作の順序が重要な箇所で、順序を明示したか？

判断基準：

• 「成功」の定義は明確か？（何をもって完了とするか）
• 「失敗」の定義は明確か？（どうなったら中断するか）
• 曖昧な判断箇所で、具体的な数値・具体例で基準を示したか？
• 「こうなったらこうする」のパターンを網羅したか？

ツール固有の知識：

• MCPツール名は完全修飾名か？（mcp__server__tool）
• Playwrightのセレクタは正確か？（DOM構造依存の部分）
• APIのレスポンス形式やエラーコードは記載したか？
• レート制限やタイムアウトの考慮は書いたか？

落とし穴（Gotchas）：

• 作業中に実際に遭遇したエラーと回避策は全て書いたか？
• 「やってはいけないこと」は明記したか？
• 直感に反する動作（普通こうだと思うがこのツールではこう）は書いたか？
• 順序依存操作で、順序を間違えた場合の影響は書いたか？

3-2. ユーザー指示の徹底分析（最重要）

ユーザーが会話中に出した修正指示・フィードバックは、スキルにとって最も価値の高い情報源である。 ユーザーの修正は「エージェントのデフォルト動作」と「ユーザーが本当に求めるもの」のギャップを正確に示しているため、これを言語化できれば同じ失敗を二度と起こさないスキルになる。

会話履歴を再度通読し、以下のパターンを1つ残らず抽出する：

抽出パターン：

パターン	例	スキルへの反映方法
直接的な否定	「それじゃない」「違う」「やめて」	Gotchasに「やってはいけないこと」として明記
方向修正	「こうじゃなくて、こうして」	手順の該当Stepを修正後の方法に書き換え
暗黙の前提の明示	「当然Xだと思ってた」	前提条件に追加
品質基準の提示	「もっと丁寧に」「雑すぎ」	判断基準・成功条件を具体化
優先順位の指定	「Aよりも先にBをやって」	手順の順序を修正、理由を付記
例外ケースの指摘	「Xの場合はYしないで」	条件分岐を追加
ツール選択の指定	「そのツールではなくこっち」	デフォルトツールを変更

分析手順：

1. 会話を最初から最後まで通読する
2. ユーザーが何かを修正・否定・補足したメッセージを全て列挙する
3. 各メッセージについて「なぜユーザーはこう言ったのか」を推論する
4. その推論をSKILL.mdの該当箇所にwhyごと反映する（「Xする。なぜなら〜」の形式）
5. 同じ失敗が起きないよう、指示を十分に具体的にする

3-3. リトライ・失敗箇所の言語化

会話中にリトライや失敗があった箇所も重要な暗黙知：

• リトライした箇所 → 失敗原因と解決策を手順に明記
• 「あ、これは...」と気づいた箇所 → その気づきを言語化して追記
• ユーザーが介入せず自力で修正した箇所 → 修正前の間違いをGotchasに記載（次回も同じ間違いをする可能性がある）

3-4. SKILL.md への反映

洗い出した情報を適切なセクションに追記：

• 環境前提 → 「前提条件」
• 手順詳細 → 各Step
• 判断基準 → 該当StepまたはGotchas
• 落とし穴 → 「Gotchas」
• ユーザー修正 → 該当Step + Gotchas（修正理由をwhyとして付記）

---

[Phase 3.5] 1行1行の自明性チェック（剪定）

Phase 3で暗黙知を追記した後、SKILL.md全体が膨らんでいる。ここで逆方向のチェックを行い、不要な行を削除する。

公式ベストプラクティスの核心原則: 「エージェントが既に知っていることは書かない。判断基準: この指示がなければエージェントは間違えるか？」

チェック方法

SKILL.mdの本文を1行ずつ読み、各行に対して以下の2つの問いを立てる：

問い	Yesなら	Noなら
Q1: この行がなくても、エージェントは正しく動作するか？（自明か？）	削除候補	残す
Q2: この行がないとき、同じタスクで実際に失敗が起きるか？	残す	削除候補

判定マトリクス：

Q1（自明か）	Q2（ないと失敗するか）	判定
自明	失敗しない	削除する — トークンの無駄
自明	失敗する	残す — 自明に見えるが実は重要（Gotchasに移動を検討）
自明でない	失敗しない	残すが簡潔に — 補助情報として価値あり
自明でない	失敗する	絶対に残す — スキルの核心

具体的にありがちな削除対象

• 「エラーが発生した場合は適切に処理する」 → 自明かつ具体性なし
• HTTPやJSON等の一般知識の説明 → エージェントは知っている
• 「ベストプラクティスに従う」 → 具体的でないため価値なし
• 「注意深く確認する」 → 自明
• ツールの基本的な使い方の説明（エージェントが既に知っているもの）

結果

削除・簡潔化した行数を記録しておく（Phase 7の完了報告で使用）。

---

[Phase 4] スクリプトの整理・バンドル

会話中にスクリプトを作成していない場合はこのPhaseをスキップする。

4-1. バンドル判定

判定	基準	配置先
バンドル	スキル実行に毎回必要	scripts/
参照	設定例・データ形式の例	references/
不要	一時的なデバッグ用	バンドルしない

4-2. スクリプトのクリーンアップ（公式ガイドライン準拠）

バンドルするスクリプトは以下の基準で整理：

必須（公式の"hard requirement"）：

• 対話型プロンプト（TTY入力）を排除。全入力をCLIフラグ・環境変数・stdinで受ける
• 必須引数が欠けた場合、明確なエラーメッセージとUsageを表示
• --helpオプションの追加

推奨：

• ハードコードされたパスを引数化または相対パス化
• 不要なデバッグ出力の削除
• 構造化出力を優先（JSON, CSV）。データはstdout、診断はstderrに分離
• 依存関係のインライン宣言（Python: PEP 723 → uv run、JS: npm: specifier → deno run）
• バージョンの固定（npx eslint@9.0.0等）
• 冪等性の確保（リトライしても安全）

4-3. SKILL.md への記載

## Available scripts セクションに各スクリプトを記載：

## Available scripts

- `scripts/xxx.py` — {1行説明}。実行: `uv run scripts/xxx.py --help`

---

[Phase 5] reviewing-skills によるレビュー & 自動修正（必須）

このフェーズは必ず実行する。スキップ不可。

Phase 2-4で作成したSKILL.mdを、公式ベストプラクティスに基づいてレビュー・修正する。

5-1. なぜこのフェーズが必要か

Phase 2-4は「作業内容の忠実な記録」に集中している。しかし以下の品質観点は見落としやすい：

• descriptionのトリガー精度（pushy enough か？）
• Progressive Disclosureの適用（500行以内に収まっているか？）
• エージェントが既に知っている情報の冗長な記述
• 命令形・一貫した用語の使用
• 参照ファイルの読み込み条件の明確さ
• nameの命名規則違反

reviewing-skillsはこれらを網羅的にチェックする。

5-2. レビューの実行

Skill({ skill: "reviewing-skills" })

対象スキル: Phase 2-4で作成した .claude/skills/{スキル名}/SKILL.md

5-3. 指摘事項の修正

レビュー結果を重大度順に修正する：

1. Critical（必須修正）: descriptionが不十分、500行超過、name不一致 等
2. Warning（推奨修正）: Progressive Disclosure未適用、例不足、用語不統一 等
3. Info（任意）: さらに簡潔にできる箇所、テンプレート追加の提案 等

5-4. 再レビュー

修正後、再度 reviewing-skills を実行して問題が解消されたことを確認する。 最大3回まで修正→再レビューを繰り返す。3回で解消しない場合はユーザーに報告する。

---

[Phase 6] 完了報告

全Phaseが完了したら以下を表示：

スキルの作成が完了しました

スキル名: {スキル名}
パス: .claude/skills/{スキル名}/
説明: {descriptionの内容}

作成されたファイル:
- SKILL.md ({行数}行)
- scripts/xxx.py（あれば）
- references/yyy.md（あれば）

暗黙知の言語化（Phase 3で追記した項目）:
- Gotchas: {N}件
- 条件分岐: {N}件
- エラー対処: {N}件

レビュー結果（Phase 5）:
- {問題なし / N件のCritical・M件のWarningを修正済み}