create-skill

スキルとコマンドの生成

構造化されたスキルまたはスラッシュコマンドを生成します。どちらも YAML フロントマターを含む Markdown ファイルで、トリガー方法と説明が異なるだけで、構造は共通しています。

フェーズ 0：要件を把握する

$ARGUMENTS を解析して、種類のヒントを確認します。$ARGUMENTS が空、または情報が不十分な場合は、AskUserQuestion を使って要件を収集します。ユーザーは必要な成果物の種類や最適な設計を明確に把握していないことがよくあります。

AskUserQuestion を使って、以下の情報を収集します。

1. 主な目的 — 何を実行するものですか？
2. トリガーとなる状況 — どのようなときに起動すべきですか？
3. 入力／出力 — 何を受け取り、何を生成しますか？
4. 複雑さ — シンプル、標準、複雑のどれですか？
5. 実行要件 — コンテキストを分離しますか？専門エージェントに委任しますか？ 目的とトリガーとなる状況が少なくとも明確になったら、フェーズ 1 に進みます。残りの項目は生成中に決めてもかまいません。

フェーズ 1：生成する

生成全体を通して、以下の原則を適用します。生成されたスキル本文のトークンは呼び出しのたびに予算を消費し、Claude は的確な指示から適切に推論できるため、命令形を使い、簡潔に記述します。例よりも指示を優先します。あらゆる入力に一般化できるよう、理由を添えてルールを明示します。

新しいスキルディレクトリを作成する場合（既存ファイルの編集ではない場合）：

python3 ${CLAUDE_PLUGIN_ROOT}/skills/create-skill/scripts/init_skill.py <name> --path <dir> [--resources scripts,references,assets] [--examples]

終了コード 0 = ディレクトリを作成しました。ステップ 1 に進みます。 終了コード 1 = 名前が競合しています。上書きするか、名前を変更するか、ユーザーに確認します。

ステップ 1 — 種類を選ぶ

• スキル： トリガーを豊富に含む三人称の説明（「このスキルは……の場合に使用します」）。ルーティングによって自動的に起動されます。
• コマンド： 簡潔で動詞から始まる、60 文字未満の説明。/ メニューからユーザーが起動します。

ステップ 2 — フロントマターを記述する

${CLAUDE_PLUGIN_ROOT}/skills/create-skill/references/frontmatter-options.md を読み、全フィールドの一覧、説明のパターン、ツール選択のフレームワーク、実行修飾子を確認します。

説明の密度に関するルール： 説明は 150 トークン未満（絶対上限は 200 トークン）にします。説明は毎セッション読み込まれます。250 文字を超える説明はスキル一覧で省略されます。フェーズ 0 でユーザーが実際に使った言葉からトリガーフレーズを導き出し、言い換えは避けます。トークン予算、強力なルーティングパターン、トリガーの導出原則については、frontmatter-options.md を参照してください。

外延的な記述ではなく内包的な記述を、生成するすべての内容に適用します。 例を挙げてルールを暗示するのではなく、理由とともにルールを直接示します。「引用されたフレーズはユーザーの発言をそのまま使う必要があります。ルーティングが文字どおりのトークンと照合するためです」という内包的なルールは、スキルが遭遇するあらゆる入力に一般化できます。外延的な方法では、読者がルールを逆算する必要があり、推論が 1 段階ではなく 2 段階になります。また、特定の例の形にしか対応できません。このスキルは、その後の生成を導く指示を生成するため、推論の質は後続にも伝播します。

ステップ 3 — 説明の発見可能性を検証する

本文を記述する前に、説明が適切にルーティングされることを確認します。次の例を頭の中で作成します。

1. 起動すべきプロンプトを 3 つ — このスキルを起動すべき現実的なユーザーメッセージ。スキルについて聞いたことのないユーザーが使いそうな素朴な表現を、少なくとも 1 つ含めます。
2. 起動すべきでないプロンプトを 3 つ — 近接する分野のメッセージで、似てはいるものの起動すべきでないもの。説明が広すぎないかを確認します。

評価します。説明は、起動すべきプロンプトをすべてカバーしていますか？起動すべきでないプロンプトを、妥当な形で除外できますか？カバー範囲が不十分なら、説明を修正します。不足しているトリガーフレーズを追加する、近接分野を除外できるよう表現を絞る、または否定的なトリガー（「X には使用しない」）を追加します。

このステップでは、スキルの残りを構築する前にルーティングの見落としを見つけられます。説明のカバー範囲が十分になったら、先に進みます。

ステップ 4 — 本文を書く

構成ルール：

• 最初の文で目的を明確に述べます
• 命令形を使います（「分析する」「生成する」「特定する」など）。一人称（「私は〜します」「私は〜です」）は使いません
• 理解に必要な場合に限り、背景情報を含めます
• 複雑な構造化データにのみ XML タグを使います
• 「このスキルを使うタイミング」セクションは設けません。本文はトリガー後にのみ読み込まれるため、そこにルーティングの指針を書いてもルーティングの判断時には参照されません
• H3 より深い階層の見出しは避けます。深い階層化は、references/ に置くべき内容であることを示します
• リアルタイムデータ（git status、ファイル一覧、環境変数など）がツール呼び出しなしでスキルを強化できる場合は、動的コンテキストの挿入に感嘆符＋バッククォート構文を使います
• コードブロックを文章にまとめるときも、変数のバインディングを保持します。 コードブロックには、操作の例示とワークフローの状態の確立という 2 つの役割があります。コードブロック内で変数（BASE=...、BRANCH=...）を割り当て、その後の手順で参照する場合、バインディングを保持せずに文章へまとめると、後続の $VAR 参照が未定義になります。それらの変数を使う手順の前に、文章内で各変数を明示的に割り当てる「作業変数を導出する」前置きを追加します

スキルとコマンドは、同じ本文パターンに従います。

# Name

Brief overview (1-2 sentences).

## Process
1. Step one (imperative voice)
2. Step two
3. Step three

動的コンテンツ：

構文	用途
$ARGUMENTS	すべての引数を文字列として扱います
$1、$2、$3	位置引数（複数語の値にはシェル形式の引用符を使います）
@path/file	ファイルの内容を読み込みます
@$1	引数で指定されたファイルを読み込みます
感嘆符＋バッククォート	bash コマンドを実行し、出力を含めます
${CLAUDE_SKILL_DIR}	スキル自体のディレクトリへのパス（同梱のスクリプトやファイルを参照するときに使います）
${CLAUDE_SESSION_ID}	現在のセッション ID（ログ記録やセッション固有の出力ファイルに便利です）

例 — ライブコンテキストの挿入。 スキル本文に次のような行を記述します。

• 現在のブランチ：!`git branch --show-current`
• 最近のコミット：!`git log --oneline -5`
• 変更されたファイル：!`git diff --name-only`

続けて、「このプルリクエストを要約してください...」のような指示を追加します。

これらのコマンドはスキルの呼び出し時に実行されます。モデルには出力のみが表示され、ツール呼び出しは必要ありません。失敗する可能性が低く、出力が情報提供のみを目的とする、確実性の高い確認（git status、環境変数、ファイルツリー、プロセス出力など）に使います。失敗する可能性があるコマンドや、終了コードに応じた分岐が必要なコマンドには使わないでください。その場合は、モデルがエラーを処理できるよう、Bash ツール呼び出しが必要です。

注： 上記のバックスラッシュは、バッククォートがこのドキュメント内で実行されないようにエスケープしています。実際のスキルでは、バックスラッシュなしで !`cmd` と記述します。

ステップ 5 — スクリプト化の機会を確認する

${CLAUDE_PLUGIN_ROOT}/skills/create-skill/references/script-patterns.md を読み、生成するスキルのすべてのワークフローステップに、5 つのシグナルパターンを適用します。

シグナル	確認事項	該当する場合 →
Repeated Generation	呼び出しごとに異なるパラメーターを使って、同じ構造を生成するステップがありますか？	scripts/ 内のパラメーター化スクリプト
Unclear Tool Choice	複数のツールを脆弱な手順で組み合わせているものの、1 つの関数として自然に表現できるステップがありますか？	手順をスクリプト化
Rigid Contract	このステップの --help テキストを、今すぐ曖昧さなく記述できますか？	CLI 候補 — 設計を create-cli に委任
Dual-Use Potential	ユーザーはスキルのワークフロー外でも、ターミナルからこのステップを実行したいと思いますか？	最初から適切な CLI として設計
Consistency Critical	同一の入力に対して、このステップはビット単位で完全に一致する出力を生成する必要がありますか？	スクリプト化 — LLM による生成は不可

特定したスクリプト候補ごとに、次の手順を実行します。

1. references/script-patterns.md からアーキタイプを選択します（init/validate/transform/package/query）
2. インターフェースが複雑な場合は、設計のために claude-skills:create-cli スキルに委任します
3. references/script-patterns.md の Python テンプレートを使って、scripts/ にスクリプトのひな形を作成します
4. 次の項目を含めて SKILL.md に組み込みます：トリガー条件、正確な実行方法、出力の解釈方法

組み込みルール： スクリプトの参照には、いつ実行するか（トリガー条件）、どのように実行するか（フラグを含む正確なコマンド）、結果をどう扱うか（終了コードの処理、重要な出力フィールド）を記載する必要があります。

ステップ 6 — 委任を確認する

最終決定の前に、既存のリソースを確認します。

Review available: skills, commands, agents, MCPs
For each workflow step, ask: "Do we already have this?"

一般的な委任パターン：

• Git コミット → Skill: claude-coding:commit

必ず完全修飾名を使用してください：

• Skill: plugin-dev:hook-development（「hook-development」だけではなく）
• SlashCommand: /plugin-dev:create-plugin（「create-plugin」だけではなく）
• Task: subagent_type=plugin-dev:agent-creator

ステップ 7 — 検証する

python3 ${CLAUDE_PLUGIN_ROOT}/skills/create-skill/scripts/validate_skill.py <skill-directory> --output json

終了コード 0 = フェーズ 2 に進みます。終了コード 1 = errors 配列を解析します。各エントリには field、message、severity があります。ディスクに書き込む前に、すべての critical および major 項目を解決してください。

フェーズ 2：成果物を提出する

出力先

種類	場所
ユーザースキル	~/.claude/skills/<name>/SKILL.md
ユーザーコマンド	~/.claude/commands/<name>.md
プロジェクトスキル	.claude/skills/<name>/SKILL.md
プロジェクトコマンド	.claude/commands/<name>.md

書き込みと確認

書き込む前に：

Writing to: [path]
This will [create new / overwrite existing] file.
Proceed?

選択理由を説明する

生成したスキル／コマンドをユーザーに提示する際は、次の点を簡潔に説明します。

• 何を設定したか、またその理由 — 「スキルではコミットにのみ git が必要なため、Bash を git コマンドだけに制限する allowed-tools を追加しました」
• 何を除外したか、またその理由 — 「検証は不要なため hooks は省略し、自動トリガーが適切なため disable-model-invocation は未設定のままにしました」
• ルーティングで想定される入力が認識されない場合は、トリガーフレーズを追加します

配布用にパッケージ化する

ユーザーが配布可能なファイルを明示的に要求した場合に限り、次を実行します。

python3 ${CLAUDE_PLUGIN_ROOT}/skills/create-skill/scripts/package_skill.py <skill-directory> [output-dir]

終了コード 0 = 出力先に .skill ファイルが作成されます。終了コード 1 = 検証に失敗しました。詳細は stdout を確認してください。

作成後

作成した内容を要約します。

• 名前と種類
• パス
• 呼び出し方法／トリガー条件
• 推奨するテストシナリオ

フェーズ 3：構造 lint

スキルをディスクに書き込んだ後、構造監査を実行するために skill-lint エージェントを呼び出します。

Use Task tool with subagent_type=claude-skills:skill-lint:
"Lint the skill at <path-to-skill-directory>. Auto-apply critical and major fixes, report
minor findings for user decision."

エージェントが完了するまで待ちます。修正が自動適用された場合は、フェーズ 4 の要約でその内容を明記します。 軽微な指摘が報告された場合は、ユーザーが判断できるよう、評価結果に含めます。

lint エージェントから応答があったら、フェーズ 4 に進みます。

フェーズ 4：評価

生成されたスキル／コマンドを採点します。

寸法	基準
明確さ（0-10）	指示が曖昧でなく、目的が明確
精度（0-10）	過度な制約を設けず、適切に具体的
効率性（0-10）	トークン効率—トークンあたりの価値を最大化
完全性（0-10）	要件を漏れなく満たし、過不足がない
使いやすさ（0-10）	実用的で、実行可能で、対象用途に適している

目標：9.0/10.0。 これを下回る場合は、最も弱い項目を改善するよう一度だけ修正してから提出します。

最終確定の前に、${CLAUDE_PLUGIN_ROOT}/skills/create-skill/references/generation-standards.md を読み込み、検証チェックリストに合格していることを確認します。

---

各フェーズを順番に実行します。