create-skill

创建技能

技能是教授 Agent 专项工作流的 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. 目的——一项具体任务或工作流。
2. 触发条件——Agent 应在何时应用此技能？
3. 信息缺口——Agent 尚不了解哪些内容（项目规则、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

Frontmatter（必填）

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

Description（发现能力至关重要——使用第三人称，说明做什么 + 何时使用，并包含触发词）：

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

编写规则

1. 简洁——假定模型能力足够；只添加不明显的领域或项目事实。
2. 渐进式披露——在 SKILL.md 中写入要点；将较长的参考内容放在 reference.md 中。从 SKILL.md 最多链接一层。
3. 优先设定一个默认选项——例如一种库或一种工作流；仅在必要时提供备用方案。
4. 措辞稳定——每个概念统一使用一个术语；避免写“直到 X 月”这类过时说明，除非将旧内容收纳在简短的“已弃用”说明下。
5. 路径——仅使用正斜杠（scripts/foo.py）。

大致篇幅：SKILL.md 尽量远低于 200 行；如果内容变长，就将详细内容拆分出去。

范围：每个技能（及父技能）只负责一项工作

• 单一职责——每个技能只包含一项主要工作流或决策树。如果触发条件和步骤差异很大（例如“创建问题”与“创建 PR”与“完整的工单 → PR 流程”），就拆分为更小、更专用的技能。
• 优先采用小技能并组合使用——两到三个专注的技能可以避免无关细节过早进入上下文。父级（或编排）技能可以说明何时遵循各个子工作流，并链接到它们的 SKILL.md；避免将子技能的完整内容复制到父技能中。
• 适合使用一个大型技能的情况——一个始终整体执行、并共享一份紧密检查清单的端到端流程；

MCP、CLI 工具和其他技能

• 优先使用 CLI 和仓库命令来解决相同问题——Agent 擅长处理这些命令，而且与发现 MCP 工具及其架构相比，这些命令通常给上下文带来的额外噪声更少。例如：使用 gh 处理 PR/issue，使用 AGENTS.md 中的 pnpm 脚本。
• MCP 是否启用由用户决定——并非所有人都启用了相同的服务。如果某项技能需要特定 MCP 才能按说明运行，请明确说明：
  • 在 frontmatter 描述中添加提示（例如“需要 Linear MCP 才能……”），以便尽早发现不匹配。
  • 在靠近顶部的位置添加简短的 Prerequisites（或 Requirements）区块：说明所需的集成、用途，以及缺少该集成时的备用方案（例如网页界面、gh，或“请用户粘贴……”）。
• 引用其他技能——使用从仓库根目录开始的路径（例如 .claude/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: 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.