前言¶
用 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
