前言¶
用 Cursor 写代码久了，总会遇到一类「似曾相识」的场景：每次合并前都要跑 lint、tsc 和测试；每次发预览分支都要走同一套部署命令；你纠正 Agent 一句「这里不能用 raw SQL，必须走 repository 层」，下个会话它又会忘掉。
这些步骤本身并不复杂，难的是它们会在不同任务里反复出现。Agent 每次都要重新推导，你每次都要重复说明，时间就这样耗在「肌肉记忆」上。
Agent Skills 的出现，本来就是为了把这类可复用的工作流固化下来。但问题是：当你还没意识到某个流程值得封装时，它往往已经重复了三四遍。building-skills-from-patterns 正是针对这个空白——它是一条「元技能」，教 Agent 识别重复模式，并把它沉淀成 .cursor/skills/ 下的 SKILL.md，让后续会话自动加载、按需触发。
本文基于 awesome-cursor-skills 仓库中的官方 SKILL.md 原文，以及 Cursor 官方 Skills 文档 交叉核实，介绍这条元技能是什么、何时该用、怎么安装，以及如何配合 Rules 与 Hooks 分工。
这是什么¶
building-skills-from-patterns 是一条面向 Cursor Agent 的元技能（meta-skill），维护在 GitHub 仓库 spencerpauly/awesome-cursor-skills 的 resources/building-skills-from-patterns/ 目录下。
它的核心定位可以用一句话概括：当同一套多步工作流在 Cursor 里反复出现时，把它捕获成可复用的 SKILL.md，研究一次、编码一次、永久复用。
Skills 本质上是可版本控制的 SKILL.md 文件包，遵循 Agent Skills 开放标准，在 Cursor、Claude Code、Codex CLI 等支持该标准的工具中均可使用。与 Anthropic 官方的 skill-creator（侧重从零创建与 eval 评测）不同，building-skills-from-patterns 更强调从日常重复中被动发现模式，适合已经有一堆「口头约定」、却还没写成文件的团队。
核心功能与亮点¶
1. 明确的触发条件¶
官方 SKILL.md 列出了三类典型触发场景：
- 用户三次及以上要求同一操作序列，例如「提交前永远先跑 lint、tsc、test」。
- Agent 发现自己在每个任务里都在重新推导同一套步骤，例如「这个仓库预览分支怎么部署」。
- 用户的纠正听起来像一条策略（policy）。若需要始终生效，应配合
suggesting-cursor-rules写成 Rule；若是有分支、有步骤的流程（procedure），则更适合写成 Skill。
这三条判断标准很实用：它帮你在「该写 Rule 还是该写 Skill」之间做分流，避免把所有约定都堆进 Rules，导致上下文膨胀。
2. 四步标准化工作流¶
触发后，Agent 按以下流程执行：
-
命名模式（Name the pattern）
取一个短 slug，小写加连字符，如verifying-api-before-merge、releasing-mobile-build。 -
起草 SKILL.md（Draft）
在.cursor/skills/<slug>/SKILL.md创建文件。若向 awesome-cursor-skills 上游贡献，则放在resources/<slug>/SKILL.md。 -
校验（Validate）
检查 description 是否足够具体以便 Agent 匹配；步骤是否可执行、不含密钥或机器专属路径。 -
告知用户（Point the user to it）
说明文件位置，并提示下次在该工作区开聊时 Agent 会自动发现。
3. 与 Rules、Hooks 的分工表¶
官方文档用一张对照表厘清三种机制：
| 机制 | 适用场景 |
|---|---|
| Skill | 按需调用的流程，含分支步骤与工具使用 |
Rule（.cursor/rules/） |
始终生效的约定、风格、文件模式 |
Hook（.cursor/hooks.json） |
文件保存、Agent 停止等事件后的自动化 |
简单记法：「每次保存都跑 X」→ Hook；「全局代码风格」→ Rule；「当我要求发布/合并时才走的多步流程」→ Skill。
4. 写作规范与最佳实践¶
- 每个 Skill 只覆盖一条工作流，避免「万能大 Skill」。
- 工作流演进时更新已有 Skill，不要另起炉灶造成重复。
- 正文保持精简：标题、何时使用、编号步骤、注意事项；命令写具体，少废话。
description字段要写清「做什么 + 何时触发」，这是 Agent 自动匹配的关键。
安装与启用¶
目录结构¶
Cursor 启动时会自动扫描以下路径中的 Skill（官方文档）：
| 路径 | 作用域 |
|---|---|
.cursor/skills/ |
项目级 |
.agents/skills/ |
项目级 |
~/.cursor/skills/ |
用户级（全局） |
~/.agents/skills/ |
用户级（全局） |
为兼容 Claude Code 与 Codex CLI，也支持 .claude/skills/、.codex/skills/ 及对应的用户目录。
每个 Skill 是一个文件夹，内含 SKILL.md；可选子目录包括 scripts/、references/、assets/。
安装 building-skills-from-patterns¶
方式一：手动复制（推荐）
mkdir -p .cursor/skills/building-skills-from-patterns
curl -o .cursor/skills/building-skills-from-patterns/SKILL.md \
https://raw.githubusercontent.com/spencerpauly/awesome-cursor-skills/main/resources/building-skills-from-patterns/SKILL.md
方式二：克隆仓库后复制
git clone https://github.com/spencerpauly/awesome-cursor-skills.git
cp -r awesome-cursor-skills/resources/building-skills-from-patterns .cursor/skills/
方式三：从 GitHub 远程导入
在 Cursor 侧边栏打开 Customize → Rules → Add Rule → Remote Rule (Github)，填入仓库 URL。此方式适用于导入整个规则/技能仓库，具体以 Cursor 界面为准。
启用与调用¶
- 自动发现：文件就位后，重启 Cursor 或新开 Agent 会话即可。Agent 会根据
description判断何时加载。 - 手动调用：在 Agent 聊天框输入
/，搜索building-skills-from-patterns或其中文描述关键词。 - 查看已安装 Skill：Customize → Skills，在 Agent Decides 区域可看到项目与用户级 Skill。
该 Skill 的 frontmatter 含 user-invocable: true，表示用户可通过名称显式唤起。
在其他 AI 编程工具中使用¶
SKILL.md 是开放标准格式。Claude Code 通常使用 .claude/skills/；Codex CLI 使用 .codex/skills/。把同一文件夹复制到对应目录即可，frontmatter 中的 name 需与父文件夹名一致。
典型用法示例¶
场景：合并前检查流程反复出现¶
假设你在三个 PR 里都告诉 Agent：「先 npm run lint，再 npx tsc --noEmit，最后 npm test，全过再提交。」
此时可主动对 Agent 说：
我们合并前的检查流程已经重复多次了，请按 building-skills-from-patterns
把它沉淀成一个 Skill。
Agent 会按元技能流程产出类似结构：
---
name: verifying-api-before-merge
description: 合并前运行 lint、tsc 与测试。在用户要求合并、提交 PR 或说「检查一遍再合」时使用。
user-invocable: true
---
# 合并前 API 验证
## 何时使用
- 用户要求 merge、land PR 或提交前验证
- 涉及 API 层改动的 feature 分支
## 步骤
1. 从 lockfile 检测包管理器（npm / pnpm / yarn）
2. 运行 lint：`npm run lint`
3. 运行类型检查：`npx tsc --noEmit`
4. 运行测试：`npm test`
5. 全部通过后再执行 git 操作
## 注意事项
- 任一步失败则停止，向用户报告具体错误
- 不要跳过测试直接 commit
文件保存为 .cursor/skills/verifying-api-before-merge/SKILL.md 后，下次你说「帮我合这个 PR」，Agent 有机会自动匹配并执行，而不必你再口述一遍。
与 Cursor 内置 Skill 的配合¶
Cursor 2.4 起内置多条相关 Skill，可组合使用：
| 内置 Skill | 作用 |
|---|---|
/create-skill |
引导创建 Agent Skill 的目录结构与 SKILL.md |
/migrate-to-skills |
将符合条件的动态 Rule 与斜杠命令迁移为 Skill |
/create-rule |
创建始终生效的 Cursor Rule |
推荐路径：先用 building-skills-from-patterns 识别重复流程并起草内容，若格式不确定再调用 /create-skill 补全结构；若旧项目里已有大量动态 Rule，可用 /migrate-to-skills 批量转换。
SKILL.md frontmatter 参考¶
Cursor 官方要求的必填字段：
---
name: my-skill # 小写字母、数字、连字符；与文件夹名一致
description: 一句话说明做什么、何时触发；Agent 靠它做相关性匹配
---
常用可选字段：
paths：glob 模式，限定 Skill 仅对匹配文件生效disable-model-invocation: true：仅用户用/skill-name显式调用时不自动匹配user-invocable: true：允许用户在/菜单中搜索调用
适用场景与注意事项¶
适合谁¶
- 已在 Cursor 中形成固定流程，但尚未文档化的个人开发者或小团队。
- 维护 monorepo、多包仓库，不同子目录有各自部署/测试惯例的工程师。
- 想系统了解 Skill 生态、从「用别人的 Skill」进阶到「自造 Skill」的读者。
适合沉淀成 Skill 的模式¶
- 多命令串联的发布、部署、验证流程
- 依赖特定 MCP 工具或 CLI（如
gh、kubectl）的操作序列 - 需要分支判断（staging / production）但仍属「按需触发」的任务
不适合写成 Skill 的情况¶
- 始终生效的代码风格 → 用 Rule（
.cursor/rules/） - 保存文件即触发 → 用 Hook（
.cursor/hooks.json） - 一次性、不会再做的任务 → 直接对话即可，不必封装
常见坑¶
-
description 太笼统
「帮助开发」这类描述无法被 Agent 匹配。应写「在用户提到 deploy preview 时，按以下步骤……」 -
步骤依赖未说明的仓库布局
官方要求步骤可执行，或明确写「从 lockfile 检测包管理器」，避免 Agent 猜路径。 -
混入密钥或本机绝对路径
Skill 会进 Git，Secrets 应走环境变量，路径用相对路径或检测逻辑。 -
与 Rule 重复
同一条「永远不要用 var」写进 Skill 和 Rule 会浪费上下文。策略归 Rule，流程归 Skill。 -
一个 Skill 包打天下
官方明确建议 one skill per workflow；复杂域可按子目录分组，例如.cursor/skills/shipping/land-it/SKILL.md，Cursor 会递归发现。
小结¶
building-skills-from-patterns 解决的不是「会不会写 SKILL.md」，而是「什么时候该写、写完后放哪、和 Rule/Hook 怎么分工」。它把团队里口头重复了多遍的流程，变成 Agent 下次能自动加载的 muscle memory。
若你已经在 Cursor 里第三次解释同一条流程，不妨让 Agent 按这条元技能把它固化下来。官方 Skill 原文与示例 frontmatter 见：
- Skill 目录：https://github.com/spencerpauly/awesome-cursor-skills/tree/main/resources/building-skills-from-patterns
- Cursor Skills 文档：https://cursor.com/docs/skills
- Agent Skills 开放标准：https://agentskills.io
