create-skill

スキルの作成

小さく観測可能な契約を定めてスキルを初期化し、.claude/skills/ にシンボリックリンクを作成して、Claude Code が検出できるようにします。不変のワークフローガイダンスは SKILL.md に記述し、決定論的な処理や条件に応じた詳細はスクリプトとリファレンスに分けます。

モデルの最適化

新しいスキルとその内容はすべて、GPT-5.6 と Claude Fable 5 向けに最適化してください。以下の要約はリマインダーであり、最新のガイドの代わりにはなりません。複雑で長時間実行するスキル、複数のツールを使うスキル、またはオーケストレーション中心のスキルを設計または作成する前に、両方のガイドを読んでください。推奨事項は変更されることがあります。

• GPT-5.6 のプロンプト作成ガイダンス：目標、成功条件と停止条件、制約、根拠、権限の境界、ツールの振り分け、出力形式、検証方法を指定した、簡潔で成果を優先するプロンプトを推奨します。重複した枠組みは取り除き、代表的なタスクで変更を評価してください。
• Claude Fable 5 のプロンプト作成ガイダンス： 意図と境界を説明する簡潔な指示を使い、過度な規定やスコープの拡大を避け、労力を意図的に調整し、進捗の主張はツールで得た根拠に基づかせてください。必要に応じて、長時間実行時の検証と枠組みを明示してください。

引数

• skill-name（必須）：ケバブケースの名前（例：my-skill）。指定がない場合、または無効な場合は停止します。

--global、明示的な保存先パス、その他のスコープ上書きは拒否します。呼び出し時の作業ディレクトリだけがサポート対象のスコープです。

解決済みパス

<scope> をスキルの呼び出し元の作業ディレクトリに設定します。ソースは <scope>/.agents/skills/<name>/ に作成し、Claude Code 用のシンボリックリンクは <scope>/.claude/skills/<name> に作成します。ネストされたプロジェクトやワークスペースから呼び出された場合に、スコープをリポジトリのルートへ変更してはいけません。~/.agents、~/.claude、~/.codex、その他のグローバルなインストールディレクトリにスキルを作成したり、変更したりしてはいけません。

シンボリックリンクのリンク先は常に相対パス ../../.agents/skills/<name> です。

スキルの構成

<name>/
├── SKILL.md       # Required: frontmatter + lean workflow (aim for <500 lines)
├── agents/
│   └── openai.yaml # Required: Codex metadata; disables implicit invocation
├── scripts/       # Optional: helper code (prefer TypeScript via bun run; Python via uv)
├── references/    # Optional: long-form docs loaded on demand
└── assets/        # Optional: templates / fonts / images used in OUTPUT (never loaded into context)

エージェントは、段階的開示を通じてスキルを3段階で読み込みます。

1. 検出 — 起動時に表示されるのは name と description だけです。トリガーを description の冒頭に記載します。
2. 有効化 — タスクが一致すると、SKILL.md の本文全体が一度読み込まれます。
3. 実行 — scripts/ はコンテキストに読み込まれずに実行されます。references/ は SKILL.md から明示的にリンクされている場合にのみ読み込まれます。

SKILL.md はワークフローに集中させてください。大量の内容は scripts/（決定論的なロジック）または references/（ドキュメント）に移します。

作成時の契約

構成を選ぶ前に、内容を次のように分けてください。

• 不変条件：有効な実行で必ず維持する必要がある条件。
• 望ましい既定値：明示的なユーザーの意図やリポジトリの根拠によって変更される可能性のある条件。
• 条件付きの例とリファレンス：該当する分岐が有効な場合にのみ読み込む内容。

成果、権限の境界、停止条件、完了を示す根拠を定義してください。同じ契約を満たす安全な方法が複数ある場合、実行方法を一つに固定しないでください。ユーザー向けワークフローでは、開始、進捗、判断、ブロッカー、完了の各イベントのうち、通知すべきものと、それぞれに必要な最小限の内容も定義してください。

内容を分割する場合

scripts/ を使う場合

• 呼び出すたびに同じコードを書き直すことになる場合（例：PDF の回転、JSON の変換、curl のラッパー）。
• 柔軟性よりも決定性が重要な場合（解析、検証、コード生成、冪等なセットアップ）。
• シェルパイプラインが約 5 行を超える場合、または適切なエラー処理が必要な場合。
• 長いヒアドキュメントが SKILL.md 内に繰り返し登場する場合。

スクリプトはトークン効率に優れています。エージェントはスクリプトを読み込まずに呼び出せます。CLI のシグネチャを SKILL.md に記載し、実装は scripts/ に置いてください。

特別な理由があって TypeScript がヘルパーに適さない場合を除き、bun run scripts/<name>.ts で実行する scripts/*.ts を優先してください。データ、テキスト、ファイルの処理には Python も適しています。Python ヘルパーは python や python3 を直接使わず、uv run scripts/<name>.py で実行してください。

references/ を使う場合

• トピックの説明、例、スキーマが約 100 行を超える場合。
• 内容が条件によって関連する場合（バリアント、フレームワーク、ドメイン固有など）。分割することで、無関係なコンテキストを除外できます。
• 詳細な API、DB スキーマ、ポリシー、大規模なテンプレートが SKILL.md の大半を占めてしまう場合。
• 長い説明が特定の分岐でのみ必要な場合。

経験則：

• 1 階層のみ — SKILL.md から references/placeholder.md に直接リンクし、リファレンスから別のリファレンスは参照しないでください。
• 100 行を超えるファイルには、先頭に目次を追加してください。
• 10,000 語を超えるファイルでは、ファイル全体を読まずにエージェントがセクションを見つけられるよう、SKILL.md に grep パターンを記載してください。
• 重複させない — 各情報は SKILL.md かリファレンスのどちらか一方に記載し、両方には記載しないでください。個別にインストールされるスキル間でリファレンスを共有するのではなく、各スキルを自己完結させてください。
• 各リファレンスについて、いつ読むべきかを示す一文を SKILL.md に記載してください。

リファレンスの構成パターン

パターン A — 概要ガイド＋トピック別リファレンス

SKILL.md
references/
├── forms.md
├── api.md
└── examples.md

SKILL.md では基本的な手順を説明し、詳細な内容はリファレンスに記載します。

パターン B — ドメイン別またはバリアント別の分割

SKILL.md           # workflow + selection logic
references/
├── aws.md
├── gcp.md
└── azure.md

エージェントはユーザーが選択したバリアントのみを読み込みます。無関係なプロバイダーがコンテキストに含まれることはありません。

パターン C — 条件付きの詳細

基本的なケースは SKILL.md に記載し、エッジケース用の高度なファイル（tracked-changes.md、ooxml.md など）にリンクします。

スキルに追加してはいけないもの

• README.md、INSTALLATION.md、CHANGELOG.md、QUICK_REFERENCE.md — 不要です。
• スキルの作成方法に関するメモ、テストログ、一時ファイル。
• 実行時にエージェントが使用しないもの。

ワークフロー

1. Agent Skills のドキュメントを取得する

フロントマターやコンテンツを作成する前に、必ず最新の仕様を取得してください。

• https://agentskills.io

WebFetch を使って、現在のフロントマターのスキーマ、命名規則、段階的開示の規約を確認してください。推測しないでください。仕様は更新されます。

2. 検証する

• kebab-case ではない名前、または解決後のパスにある既存のスキルと衝突する名前は拒否してください。
• <scope> が呼び出し時の作業ディレクトリであり、ホームディレクトリ直下やグローバルなスキルディレクトリではないことを確認してください。
• <scope>/.agents/skills/<name>/ または <scope>/.claude/skills/<name> がすでに存在する場合は、そこで中止してください。

3. 作成ガイドを読み、契約と構成を定義する

契約や構成を決める前に、references/writing-great-skills.md を読んでください。予測可能性を高める要素と、文章・コード・スキーマのどれを使うかの判断について説明しています。

観察可能な成果、前提条件、推奨されるデフォルト、権限、ルーティング、停止条件、完了の証拠を定義してください。内容ごとに配置先を決めます。

• ワークフローでヘルパーコードを呼び出しますか？→ bun run で実行する scripts/<name>.ts を優先してください。Python のほうが適している場合は、uv run で scripts/<name>.py を実行してください。
• 実際のバリデーターで処理するスキーマですか？→ 両方を同梱し、検証方法を記載してください。
• 参照用のスキーマ説明、長い例、バリエーションガイド、ドメイン知識ですか？→ references/<topic>.md
• スキルがユーザーの出力先に書き込むテンプレートやファイルですか？→ assets/
• 上記のいずれにも該当しませんか？→ SKILL.md のみを配置してください。

まずディレクトリツリーの概要を作成し、その構成で実際に必要なサブディレクトリだけを作成してください。

4. スキルを作成する

mkdir -p "<scope>/.agents/skills/<name>/agents"
# Add only the subdirectories the layout calls for:
# mkdir -p "<scope>/.agents/skills/<name>/scripts"
# mkdir -p "<scope>/.agents/skills/<name>/references"

<scope>/.agents/skills/<name>/SKILL.md を作成し、次の内容を記述してください。

• フロントマターをアルファベット順に並べ、description を最後に配置します。検出時に参照されるのは description のみです。本文ではなく、ここにトリガーとなるフレーズを優先して記述してください。
• 短い # Title。
• スキルの機能を説明する1行の要約。
• Claude の動作を指定する disable-model-invocation と user-invocable フィールド。Claude のデフォルトに意図的に依存する場合のみ省略してください。その場合の値は disable-model-invocation: false、user-invocable: true です。
• 必要に応じて ## Arguments を記述し、簡潔な命令形のワークフローを作成します。順序が重要な場合のみ手順を固定し、それ以外は契約を示して、リポジトリ内の証拠に基づいて実行できるようにしてください。
• ワークフローで必要になる references/ 内のすべてのファイルへの明示的なリンクを記載し、それぞれに、いつ読むべきかを説明する1行の注記を付けてください。
• 同梱するスクリプトには、実行環境のコマンド（bun run scripts/<name>.ts または uv run scripts/<name>.py）を含む CLI のシグネチャを記載し、ファイルを読まなくてもエージェントが呼び出せるようにしてください。

SKILL.md は500行未満を目指してください。中核となるワークフローではないセクションが約50行を超える場合は、その内容を references/ に移し、リンクしてください。

<scope>/.agents/skills/<name>/agents/openai.yaml を作成し、次の内容を記述してください。

policy:
  allow_implicit_invocation: true

allow_implicit_invocation は、SKILL.md の disable-model-invocation を反転した値にしてください。後から Codex UI メタデータや MCP／ツールの依存関係を追加する場合は、同じファイルに統合し、このポリシーを維持してください。

5. Claude Code のシンボリックリンクを作成する

Claude Code が独自の検出パスからスキルを見つけられるよう、必ず相対シンボリックリンクを作成してください。

mkdir -p "<scope>/.claude/skills"
ln -s "../../.agents/skills/<name>" "<scope>/.claude/skills/<name>"

6. 検証する

• パッチ適用ツールはファイルをモード0644で作成します。最初の検証を実行する前に、scripts/ と tests/ 内の実行可能ファイルすべてに chmod 755 を実行してください。スキャフォールドされたテストの初回実行時に Permission denied (os error 13) で失敗する場合は、これが原因です。
• test -f "<scope>/.agents/skills/<name>/SKILL.md"
• test -f "<scope>/.agents/skills/<name>/agents/openai.yaml"
• readlink "<scope>/.claude/skills/<name>" がソースディレクトリを指していることを確認します。
• scripts/* と tests/* の実行可能ファイルすべてに test -x を実行します。これにより、chmod の漏れを見逃さず、後で権限エラーが発生するのを防げます。
• ### 🧩 Skill created: <name>、作成したパスのツリー、実行した検証内容を正確に記載した ### ✅ Verified で締めくくってください。ソースとシンボリックリンクの両方の絶対パスをリンクしてください。
• 新しいスキルのコミットを提案してください。ホストプロジェクトの既存の指示でコミットを求められている場合は、追加の確認をせずにコミットしてください。

メモ

• フロントマターのルール：フィールドをアルファベット順に並べます。ただし、description は必ず最後に配置します。
• Codex はスキルを読み込む前に、SKILL.md のフロントマターを YAML として解析します。description 内の Triggers: "foo" のような、引用符で囲まれていないコロンと空白の組み合わせをスカラー値に含めないでください。ラベルを省くか、値全体を引用符で囲んでください。
• 「使用するタイミング」の情報は、本文（アクティベーション時のみ）ではなく、description（発見時）に記載します。
• SKILL.md 全体で命令形／不定詞形を使用します。
• SKILL.md 内のすべてのパス（例：references/placeholder.md、scripts/example.sh）は、スキルディレクトリからの相対パスです。
• 新しいスキルにはすべて agents/openai.yaml を含め、policy.allow_implicit_invocation は SKILL.md に基づいて設定します。逆の順序にしてはいけません。
• bun run で実行する TypeScript ヘルパースクリプトを優先します。Python は uv run を使い、生の python や python3 は使わないでください。
• スキル内の Bash スクリプトは、Codex がデフォルトで組み込みの Bash を使用するため、Bash 3.2（/bin/bash）と互換性を持たせてください。
• スキル独自の出力仕様で別途求められていない限り、ヘルパーの標準出力、コマンド、パス、フロントマター、生成されるスキルの内容には装飾を加えないでください。