Cursor Skills 使用教學：技能目錄、SKILL.md 字段、/ 調用與規則遷移

本文根據 Cursor 官方文檔《Agent Skills》整理，資料核對於 2026-10-11。沒有登入 Cursor 帳號操作，介面入口名稱取自官方文檔原文，以實際介面為準。Cursor 的規則文件怎麼寫見《Cursor Rules 怎麼寫》。

適用於誰

• 搜「cursor skills 使用教學」「cursor skills 配置」「cursor skills 安裝」的人；
• 已經在 Claude Code 或 Codex 裏攢了一批技能，想讓 Cursor 也用上的人；
• 分不清 Cursor 裏規則（Rules）、命令和技能各管什麼的人。

結論先說

1. 技能放在 .agents/skills/ 或 .cursor/skills/（項目級），個人級是 ~/.agents/skills/ 或 ~/.cursor/skills/。
2. Cursor 會直接讀 Claude Code 和 Codex 的技能目錄：.claude/skills/、.codex/skills/ 以及它們在主目錄下的對應位置，都在兼容列表裏，不用複製。
3. 兩種調用：智能體判斷相關時自動使用；或者在 Agent 對話框裏輸入 / 選擇技能，只對這一條消息生效。
4. disable-model-invocation: true 讓技能只能手動調用；paths 讓技能只在處理匹配的文件時出現。
5. 舊的規則和斜槓命令可以用 /migrate-to-skills 一鍵轉成技能。

一、技能目錄

每個技能是一個包含 SKILL.md 的文件夾，例如 .agents/skills/my-skill/SKILL.md。可選的子目錄和開放規範一致：scripts/（智能體可以運行的代碼）、references/（按需加載的補充文檔）、assets/（模板、圖片、數據文件）。

嵌套和 monorepo：

• Cursor 會遞歸遍歷技能根目錄，找到其中任何位置的 SKILL.md。中間用來分類的文件夾只起整理作用，技能的名稱取自它自己所在的文件夾；
• 子項目文件夾裏自己的 .cursor/skills/ 或 .agents/skills/ 也會被識別，並且那些技能只對該文件夾內的文件生效，不需要再寫 paths。

二、SKILL.md 的字段

一個最小示例（按官方字段說明編寫）：

markdown
---
name: api-conventions
description: Apply this project's REST API conventions. Use when adding or changing API routes, request validation, or error responses.
paths: "src/api/**/*.ts"
---

# 接口約定

- 路由文件放在 src/api/ 下，一個資源一個文件。
- 錯誤響應統一使用 { code, message } 結構。

SKILL.md 的通用寫法見《SKILL.md 怎麼寫》。

三、怎麼調用

想關掉自動調用，在 frontmatter 裏加 disable-model-invocation: true。帶有副作用的流程（發佈、跑遷移）適合這樣設。

用 paths 限定範圍：設成例如 "**/*.py"，技能只在智能體處理匹配的文件時才出現；對所有文件都適用的技能不要設這個字段。

四、查看和創建

• 查看：打開側邊欄的 Customize，進入 Skills。插件帶來的技能和項目技能與規則一起列在 Agent Decides 一組裏；
• 創建：手動新建文件夾和 SKILL.md，或者在對話裏用內置的 /create-skill，它會生成文件夾結構和 SKILL.md。

五、從 GitHub 安裝

官方文檔的說法是：技能不能直接導入，要打包在插件裏。步驟：

1. 打開 Customize，選擇 From GitHub Repository。倉庫裏必須有 .cursor-plugin/marketplace.json；
2. 或者把倉庫添加為團隊的插件市場；
3. 安裝插件，其中的技能會和其他技能一起出現在 Customize 裏。

如果對方倉庫只是一堆技能文件夾、沒有做成 Cursor 插件，可以自己把需要的技能文件夾放進 .cursor/skills/ 或 .agents/skills/。也可以用通用的命令行工具，見《npx skills add 怎麼用》。無論哪種方式，裝之前都先看一遍內容，見《Skill 安全嗎：安裝前檢查什麼》。

六、把舊的規則和命令轉成技能

內置的 /migrate-to-skills 會把符合條件的規則和斜槓命令轉換成技能，輸出在 .cursor/skills/ 裏，轉換後要檢查一遍。

從這張表也能看出 Cursor 對兩者的分工：始終生效、或者按文件類型固定生效的約束，留在規則裏；由智能體判斷何時使用的流程和知識，做成技能。

七、雲端智能體和同步

• ~/.cursor/skills/ 裏的技能預設只在本機。要讓雲端智能體也能用，在 Settings → Agents 裏打開 Sync Skills for Cloud Agents；
• ~/.agents/skills/ 和項目技能不參與這個同步；
• 同步的技能只屬於你自己。要和同事共享，把技能發佈到團隊的插件市場，或者直接提交在倉庫裏。

常見問題

Q：同一個技能，.cursor/skills/ 和 .claude/skills/ 各放一份會怎樣？

官方文檔沒有說明同名時的處理方式。保持一份即可：既然 Cursor 能讀 .claude/skills/ 和 .agents/skills/，多個工具共用的技能放一個目錄就夠了。

Q：技能沒有被自動使用？

先輸入 / 手動調用確認技能能被找到；再檢查 name 是否和文件夾同名、有沒有設 disable-model-invocation、paths 是否把當前文件排除在外；最後改 description，思路見《Skill 不觸發怎麼辦》。

Q：技能和 MCP 有什麼關係？

技能是說明和腳本，MCP 是外部工具的連接。Cursor 裏 MCP 的配置見《Cursor MCP 配置教學》。

Q：子代理和技能是一回事嗎？

不是。Cursor 文檔把它們分開介紹，子代理用 /create-subagent 創建，是帶有專門角色的獨立工作者。

參考資料

• Agent Skills（Cursor 官方文檔）：https://cursor.com/docs/skills
• Specification（Agent Skills 官方規範）：https://agentskills.io/specification