n8n:create-skill

创建技能

技能是教授 Agent 专项工作流的 Markdown 文件（可包含脚本）。保持 SKILL.md 简短——它与聊天、代码和其他技能共享上下文窗口。

技能存放位置

位置	使用时机
.agents/skills/<name>/	n8n 的默认位置：团队共享、纳入版本控制、与 Agent 无关的源文件。
.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. 目的 — 一项具体任务或工作流。
2. 触发条件 — Agent 应在何时应用此技能？
3. 知识缺口 — Agent 尚不了解哪些内容（项目规则、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

Frontmatter（必需）

---
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（发现能力至关重要——使用第三人称，说明是什么 + 何时使用，以及触发词）：

• 好例子：从 PDF 中提取表格并填写表单。在用户处理 PDF、表单或文档提取任务时使用。
• 不佳例子：帮助处理文档 或 我可以帮你处理 PDF

编写规则

1. 简洁 — 假设模型具备相应能力；只补充不明显的领域或项目知识。
2. 渐进式披露 — 在 SKILL.md 中写入核心内容；较长的参考资料放在 reference.md 中。从 SKILL.md 链接时，最多深入一层。
3. 优先提供一个默认方案 — 例如一种库或一种工作流；仅在需要时添加备用方案。
4. 措辞稳定 — 一个概念只用一个术语；避免注明“直到 X 月”的过时信息，除非将旧内容放在简短的“已弃用”说明下。
5. 路径 — 仅使用正斜杠（scripts/foo.py）。

建议长度： SKILL.md 尽量远低于约 200 行；如果内容变长，请将细节拆分出去。

范围：每项技能只处理一项工作（包括父级技能）

• 单一职责 — 每项技能只负责一个主要工作流或决策树。如果触发条件和步骤差异很大（例如“创建 issue”“创建 PR”和“从工单到 PR 的完整流程”），请拆分为更小的专用技能。
• 优先精简并组合使用 — 两三个重点明确的技能可以避免无关细节过早进入上下文。父级（或编排）技能可以说明何时遵循各个子工作流，并链接到它们的 SKILL.md；避免将子技能的全部内容复制到父级技能中。
• 适合使用单项大型技能的情况 — 一个始终连贯执行、且共用同一份精简清单的端到端流程；

MCP、命令行工具和其他技能

• 优先使用命令行和仓库命令来解决相同问题——Agent 擅长处理这些命令，而且与发现 MCP 工具及其架构相比，它们通常会给上下文带来更少的额外干扰。例如：使用 gh 处理 PR/议题，使用 AGENTS.md 中的 pnpm 脚本。
• MCP 对每位用户而言都是可选的——并非所有人都启用了相同的服务。如果某项技能必须依赖特定 MCP 才能按说明运行，请明确说明：
  • 在前置信息描述中添加提示（例如“需要 Linear MCP 才能……”），以便尽早发现不匹配。
  • 在靠近顶部的位置添加简短的先决条件（或要求）区块：说明所需集成及其用途，并在缺少该集成时提供替代方案（例如 Web UI、gh，或“请用户粘贴……”）。
• 引用其他技能——使用运行环境可识别的调用名称（例如，在支持命名空间时使用 n8n:create-issue，否则使用 create-issue）。对于面向用户的链接，提供从仓库根目录开始的规范路径（例如 .agents/skills/create-issue/SKILL.md）。也可以从同级文件夹使用相对链接：[create-issue](../create-issue/SKILL.md)。父级技能应委派步骤，而不是重复冗长流程。

模式（按需选择）

• 模板——给出准确的输出格式（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.