n8n:create-skill

スキルの作成

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

スキルの保存場所

保存場所	使用する場面
.agents/skills/<name>/	n8n のデフォルト：チームで共有され、バージョン管理され、エージェントに依存しないソースです。
.claude/plugins/n8n/skills/<name>/	Claude 固有のオーバーライド、または .agents/skills/<name>/ への生成済みシンボリックリンクです。
.opencode/skills/<name>/	OpenCode 固有のオーバーライドにのみ使用します。共有スキルは .agents/skills/<name>/ に配置してください。
~/.claude/skills/<name>/	すべてのプロジェクトで使用する、Claude Code 用の個人スキルです。
~/.config/opencode/skills/<name>/	すべてのプロジェクトで使用する、OpenCode 用の個人スキルです。
~/.cursor/skills/<name>/	任意の、Cursor 専用の個人スキルです。マシン全体で使用されます。

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

チームの他のメンバーと同じ方法で動作させるスキルには、.agents/skills/ を優先してください。共有スキルを追加または削除した後は、pnpm sync:skill-links を実行してください。

作成前に：要件を集める

簡潔に確認する（または推測する）項目は次のとおりです。

1. 目的 — 具体的なタスクまたはワークフローを 1 つ。
2. トリガー — エージェントがこのスキルを適用する場面。
3. 不足情報 — エージェントがまだ把握していない情報（プロジェクトのルール、URL、形式）。
4. 出力 — テンプレート、チェックリスト、厳密な形式。
5. 例 — 適合する共有スキルが .agents/skills/ にあれば、それに従います。

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

ファイル構成

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

フロントマター（必須）

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

Name — 共有 n8n スキルでは n8n:<name> 形式を使います。これにより、Claude Code では n8n プラグインの名前空間に属し、/n8n:<name> として呼び出されます。<name> の部分は、スキルのディレクトリ名と一致させる必要があります。

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

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

作成ルール

1. 簡潔にする — モデルには十分な能力があると想定し、一般的ではないドメイン情報やプロジェクト固有の事実だけを追加します。
2. 段階的に開示する — 要点は SKILL.md に、長い参照情報は reference.md に記載します。SKILL.md からのリンクは1 階層までにします。
3. デフォルトを 1 つにする — たとえば、ライブラリまたはワークフローを 1 つにします。必要な場合にのみ代替手段を用意します。
4. 用語を統一する — 概念ごとに用語を 1 つにし、「X 月まで」のような古くなりやすい記述は避けます。残す必要がある場合は、短い「非推奨」の注記にまとめます。
5. パス — スラッシュ（/）のみを使用します（scripts/foo.py）。

おおよそのサイズ： SKILL.md は 200 行を大きく下回ることを目指してください。長くなった場合は、詳細を別ファイルに分割します。

スコープ：スキル（および親スキル）ごとに 1 つのタスク

• 単一責任 — 主なワークフローまたは判断ツリーを 1 つにします。トリガーや手順が大きく異なる場合（例：「課題の作成」と「PR の作成」、「チケットから PR までの全フロー」）は、専用の小さなスキルに分割します。
• 小さく保ち、組み合わせる — 焦点を絞ったスキルを 2、3 個用意すると、不要な詳細を必要になるまでコンテキストから除外できます。親（オーケストレーター）スキルで各子ワークフローに従うタイミングを示し、子の SKILL.md にリンクできます。子スキルの内容全体を親に貼り付けるのは避けてください。
• 大きなスキル 1 つでもよい場合 — 常に一連の流れとして実行され、チェックリストを 1 つ共有する、エンドツーエンドのワークフロー。

MCP、CLI ツール、その他のスキル

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

パターン（適切なものを選択）

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

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

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

アンチパターン

• スキル内に冗長なチュートリアルを記載する（「PDF とは何か」など）。
• デフォルトを示さず、実質的に同じ選択肢を多数並べる。
• あいまいな名前を使う（helper、utils）。
• リンクされたファイルを何階層にもわたってたどらせる。
• MCP やツールが利用可能だと決めつけ、明記も代替手段の提示もしない。
• 関係のないワークフローを一つの巨大なスキルにまとめる。代わりに、小さなスキルと簡潔な親スキルを使います。

簡単なスタブの例

---
name: n8n: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.