create-skill

スキルの作成

スキルは、エージェントに特定のワークフローを教える Markdown ファイル（および任意のスクリプト）です。SKILL.md は短く保ってください。コンテキストウィンドウは、チャット、コード、ほかのスキルと共有されます。

スキルの配置場所

場所	使用するタイミング
このリポジトリの .claude/skills/<name>/	n8n ではデフォルトです。チームで共有し、バージョン管理されます。リポジトリ内で作業する際、Cursor はここからプロジェクトのスキルを読み込みます（Claude Code と同じ考え方です）。
~/.claude/skills/<name>/	すべてのプロジェクトで使う、Claude Code 用の個人スキルです。
~/.cursor/skills/<name>/	任意の、Cursor 専用の個人スキルです。マシン全体で使用できます。

カスタムスキルを ~/.cursor/skills-cursor/ に配置しないでください。ここは Cursor 組み込みのスキル専用です。

チームのほかのメンバーと同じ方法に合わせる必要があるものは、リポジトリの .claude/skills/ を優先してください。

作成前に：要件を確認する

簡潔に、質問するか推測してください。

1. 目的 — 具体的なタスクまたはワークフローを 1 つ。
2. トリガー — エージェントはどのようなときにこのスキルを適用すべきか。
3. 不足情報 — エージェントがまだ知らないこと（プロジェクトのルール、URL、形式など）。
4. 出力 — テンプレート、チェックリスト、厳密な形式など。
5. 例 — 該当するものがあれば、.claude/skills/ の既存スキルを参考にする。

詳しい情報が必要な場合は、わかりやすい言葉でユーザーに質問してください。

ファイル構成

skill-name/
├── SKILL.md       # required
├── reference.md   # optional — detail the agent reads only if needed
├── examples.md    # optional
└── scripts/       # optional

フロントマター（必須）

---
name: skill-name          # lowercase, hyphens, max 64 chars
description: >-         # max 1024 chars, non-empty — see below
  ...
---

Description（見つけやすさが最も重要です。三人称で、WHAT + WHEN、トリガーワードを含めます）：

• 良い例：PDFから表を抽出し、フォームに入力します。ユーザーがPDF、フォーム、またはドキュメントの抽出を扱うときに使用します。
• 悪い例：ドキュメントを支援します または PDFについてお手伝いできます

作成ルール

1. 簡潔に — モデルには十分な能力があることを前提にし、一般には知られていないドメインやプロジェクトの情報だけを追加します。
2. 段階的に開示する — 必要な情報は SKILL.md に記載し、詳細なリファレンスは reference.md に記載します。SKILL.md からのリンクは 1 階層までにしてください。
3. デフォルトは 1 つを優先する — たとえば、ライブラリまたはワークフローを 1 つにします。必要な場合にのみ代替手段を設けます。
4. 表現を安定させる — 1 つの概念には 1 つの用語を使います。「X 月まで」といった古くなる注記は避け、必要なら短い「非推奨」注記の中に旧情報をまとめます。
5. パス — スラッシュ / のみを使用します（scripts/foo.py）。

おおよその分量： SKILL.md は 200 行を大幅に下回る長さを目指してください。長くなる場合は、詳細を別ファイルに分けます。

範囲：スキルごとに 1 つの作業（親スキルも同様）

• 単一責任 — 主なワークフローまたは判断ツリーを 1 つにします。トリガーや手順が大きく異なる場合（例：「イシューを作成」と「PR を作成」と「チケットから PR までの一連の流れ」）、目的別の小さなスキルに分割します。
• 小さく保ち、組み合わせる — 目的を絞ったスキルを 2、3 個用意すると、必要になるまで無関係な詳細がコンテキストに入りません。親（オーケストレーター）スキルでは、各子ワークフローをいつ実行するかを示し、その SKILL.md へのリンクを記載できます。子スキルの内容をすべて親に貼り付けるのは避けてください。
• 大きなスキルが適切な場合 — 常にまとめて実行し、共通の簡潔なチェックリストを使う、単一のエンドツーエンドのフロー。

MCP、コマンドラインツール、その他のスキル

• 同じ問題を解決できる場合は、コマンドラインやリポジトリのコマンドを優先してください。エージェントはこうしたコマンドをうまく扱えます。また通常、MCP ツールの検出やスキーマよりも、コンテキストに加わる余計な情報が少なくて済みます。例：PR／issue には gh、AGENTS.md に記載された pnpm スクリプト。
• MCP の利用はユーザーごとに任意です。有効にしているサーバーはユーザーによって異なります。スキルを記述どおりに機能させるために特定の MCP が必須であれば、その旨を明記してください。
  • frontmatter の説明にヒントを記載します（例：「…には Linear MCP が必要です」）。早い段階で不一致に気づけるようにします。
  • 冒頭近くに短い前提条件（または要件）ブロックを追加します。どの連携機能を何に使うのか、また利用できない場合の代替手段（例：Web UI、gh、または「ユーザーに…の貼り付けを依頼する」）を記載します。
• 他のスキルへの参照 — 人間とツールが参照できるよう、リポジトリルートからのパスを記載します（例：.claude/skills/create-issue/SKILL.md）。兄弟フォルダーからは相対リンクも使えます：create-issue。スキル名とタスクを明記し、親スキルでは長い手順を重複させず、委任してください。

パターン（状況に応じて選択）

• テンプレート — 正確な出力形式（Markdown／コードブロック）を示します。
• チェックリスト — 複数の手順がある作業には、番号付きリストまたは - [ ] の手順を使います。
• 分岐 — ワークフローの冒頭に「A の場合 → …、B の場合 → …」と記載します。
• スクリプト — 実行コマンドを記載し、スクリプトを実行するのか読むのかを明示します。

ワークフロー：作成 → 検証

1. 名前と説明 — ハイフン区切りの名前を付け、説明には適用条件を記載します。
2. 概要 — セクションは最小限にし、任意のファイルにはリンクします。
3. 実装 — まず SKILL.md を作成し、トークンを節約したりエラーを減らしたりできる場合に限り、reference.md や scripts/ を追加します。
4. 確認 — 三人称で説明し、用語に一貫性を持たせ、モデルがすでに知っている百科事典的な内容を重複させないようにします。

アンチパターン

• スキル内で冗長なチュートリアル（「PDF とは何か」など）を行う。
• 既定の選択肢がないまま、同等の選択肢を多数提示する。
• 曖昧な名前（helper、utils）を付ける。
• リンク先のファイルを何段階にもわたってたどらせる。
• MCP やツールが存在することを明記せず、代替手段も示さないまま、利用できると仮定する。
• 無関係なワークフローを小さなスキルと簡潔な親スキルに分けず、1 つの巨大なスキルにまとめる。

簡単なスタブの例

---
name: my-workflow
description: Does X using project convention Y. Use when the user asks for X or mentions Z.
---

# My workflow

1. …
2. …

## Output format

Use a fenced code block for the exact shape reviewers should see.

## More detail
See [reference.md](reference.md) if edge cases matter.