Create skills

以下の手順で新しいスキルを作成してください。

入力

スキルの説明: $ARGUMENTS

フロントマター設計の判断

まず以下の点を確認し、適切なフロントマターフィールドを決定してください。

スコープの選択

スコープ	パス	使い分け
個人用	~/.claude/skills/<skill-name>/SKILL.md	全プロジェクトで使いたい汎用スキル
プロジェクト用	skills/<skill-name>/SKILL.md	このリポジトリ専用のスキル（gh skill で配布可能）

明示的な指定がない場合はプロジェクト用（skills/）を選択してください。

フロントマターフィールドの選択

以下の判断基準でフィールドを設定してください。

name（省略可能）

• ディレクトリ名と同じなら省略可能
• 小文字・数字・ハイフンのみ、最大64文字
• /name でスラッシュコマンドになる

description（推奨）

• Claude が自動発動するかどうかの判断に使われる重要フィールド
• 「何をするか」と「いつ使うか」を両方書く
• LLM は「自分でできる」と判断したタスクにはスキルを参照しない傾向がある。そのため積極的（pushy）にトリガー条件を書く
• 悪い例: PDFからテキストを抽出する方法
• 良い例: PDFの読み取り・抽出・分割・暗号化を行うスキル。ユーザーが.pdfに言及したり加工が必要な場合は、明示されていなくても必ずこのスキルを参照すること。

argument-hint（引数がある場合）

• オートコンプリートで表示されるヒント
• 例: [PR番号]、[ファイル名] [フォーマット]

when_to_use（自動発動の制御）

• Claude がスキルを自動発動するかどうかの判断に使われる
• description より具体的なトリガー条件を記述する

disable-model-invocation: true（ユーザーのみが呼び出すスキルの場合）

• 副作用があるワークフロー（デプロイ、コミット、送信等）に設定する
• Claude が勝手に実行しないようにしたい場合に使う

user-invocable: false（Claude のみが参照する知識の場合）

• / メニューから非表示にする
• 規約・パターン等のバックグラウンド知識として使う場合

allowed-tools（ツールアクセスを明示したい場合）

• スキルがアクティブなときに許可なしで使えるツールを指定
• 例: Read, Grep, Glob、Bash(gh *)

context: fork（分離した環境で実行したい場合）

• サブエージェントとして独立したコンテキストで実行する
• agent フィールドと組み合わせて使う: Explore、Plan、general-purpose

スキルコンテンツの設計

コンテンツの種別に応じて書き方を変えてください。

リファレンス型（知識・規約を注入する）

Claude が作業中に参照する規約やパターンを記述します。disable-model-invocation は不要です。

---
name: my-convention
description: このコードベースのAPI命名規則。APIエンドポイントを書くときに参照する
---

APIエンドポイントを書く際のルール:
- REST命名規則に従う
- エラーレスポンスは統一フォーマット
...

タスク型（ステップバイステップの手順を実行する）

副作用を伴うアクション（デプロイ、PR作成等）の手順を記述します。disable-model-invocation: true を設定します。

---
name: deploy
description: アプリをプロダクションにデプロイする
disable-model-invocation: true
---

1. テストスイートを実行
2. ビルド
3. デプロイターゲットにプッシュ
...

コンテンツ執筆の原則

スキルの種別によらず、以下の原則に従ってコンテンツを書く。

命令形を使う

• 良い: レポートの冒頭に必ずエグゼクティブサマリーを含める。
• 避ける: レポートにはエグゼクティブサマリーがあるといいでしょう。

出力フォーマットを明示する

期待する出力の構造をテンプレートとして書く。「概ね〜な形式で」は避け、セクション名・順序・粒度まで明示する。

具体的な入出力例を含める

「入力: ○○」「出力: △△」の形式で 1〜2 例を添えると、品質が安定する。

MUST の乱用より「なぜ」を説明する

• 避ける: ALWAYS フォーマットを守ること。NEVER 省略すること。
• 良い: フォーマットを一貫させることで後続処理の認知負荷を下げられるため、以下の形式から逸脱しないようにする。

特定の例に過適合させない

スキルは多様なプロンプトで繰り返し使われることを前提に書く。テストした数例だけに最適化したルールは避け、意図（why）を伝えて汎用的に機能させることを優先する。

変数・動的コンテキストの利用

スキルコンテンツで使用できる変数：

変数	説明
$ARGUMENTS	スキル呼び出し時に渡された全引数
$ARGUMENTS[N] または $N	位置引数（0始まり）
${CLAUDE_SESSION_ID}	現在のセッションID
${CLAUDE_SKILL_DIR}	SKILL.md が存在するディレクトリのパス
!{コマンド} 形式	シェルコマンドを実行してその出力を注入（Claude実行前に展開）

ディレクトリ構造の作成

以下の構成でファイルを作成してください：

<skill-name>/
├── SKILL.md              # 必須。500行以下を目安に保つ
├── examples/
│   └── sample.md         # 任意。出力例があると品質が安定する
└── resources/（任意）
    ├── references/       # 大きな補足情報・詳細リファレンス
    ├── scripts/          # 再利用スクリプト
    └── assets/           # テンプレート等

SKILL.md が 500 行に近づいたら、詳細を resources/references/ に切り出して SKILL.md からポインタを書く：

詳細なAPIリファレンスは [resources/references/api.md](resources/references/api.md) を参照すること。

ドメインが複数ある場合は、SKILL.md に「どのリファレンスを読むかの選択ロジック」を書き、リファレンスごとにファイルを分割する：

cloud-deploy/
├── SKILL.md              # ワークフロー全体 + 環境ごとの分岐
└── resources/references/
    ├── aws.md
    ├── gcp.md
    └── azure.md

出力

以下を実行してください：

1. 上記の判断基準に基づいてフロントマターを決定する
2. スキルディレクトリを作成する
3. SKILL.md を作成する
4. 出力例がある場合は examples/sample.md も作成する
5. 以下を報告する：
   • 作成したファイルパス
   • 選択したフロントマターとその理由
   • 呼び出し方（/skill-name または自動発動）

チェックリスト

完成前に以下を確認すること：

• name と description が frontmatter に含まれているか
• description に「いつ使うか」と「何をするか」が両方書かれているか
• description は積極的（pushy）に書かれているか
• 指示は命令形で書かれているか
• 出力フォーマットが明示されているか
• 具体的な例が含まれているか
• MUST の乱用より「なぜ」の説明があるか
• 500 行以内に収まっているか（超える場合は resources/references/ に切り出す）

参考

出力の品質・フォーマットの参考として examples/sample.md を参照してください。