《Cursor文檔》-Agent 技能

Agent Skills 是一項開放標準，用於爲 AI 智能體擴展專業能力。技能將特定領域的知識和工作流打包，使智能體能夠執行特定任務。

什麼是技能？¶

技能是可移植、納入版本控制的功能包，用於讓智能體學會執行特定領域的任務。技能可以包含腳本、模板和參考資料，智能體可藉助工具使用這些內容。

可移植¶

技能可用於任何支持 Agent 技能 標準的智能體。

納入版本控制¶

技能以文件形式存儲，可在您的代碼倉庫中追蹤，或通過 GitHub 代碼倉庫鏈接安裝。

可操作¶

技能可以包含腳本、模板和參考資料，智能體可藉助工具使用這些內容。

漸進式¶

技能按需加載資源，高效利用上下文。

技能的工作原理¶

Cursor 啓動時，會自動從技能目錄中發現技能，並將其提供給 智能體 使用。智能體會看到可用的技能，並根據上下文判斷何時適用。

你也可以在 智能體聊天 中輸入 /，然後搜索技能名稱以手動調用技能。以這種方式調用的技能會附加到一條消息。要讓技能在整個會話期間保持啓用，請使用 Option+Enter (Mac) 或 Alt+Enter (Windows) 將其作爲自定義模式使用。請參閱自定義模式。

Cursor 內置技能¶

Cursor 提供了一組內置技能，幫助您優化日常工作流。這些技能由 Cursor 管理，與您自行添加的技能一同顯示。

您可以在智能體聊天中輸入 /，然後選擇相應名稱來運行任何內置技能。當您的請求明確符合其用途時，智能體也可能自動使用某些內置技能。

技能目錄¶

技能會自動從以下位置加載：

爲保持兼容性，Cursor 還會從 Claude 和 Codex 目錄加載技能：.claude/skills/、.codex/skills/、~/.claude/skills/ 和 ~/.codex/skills/。

每個技能都應爲一個包含 SKILL.md 文件的文件夾：

.agents/
└── skills/
    └── my-skill/
        └── SKILL.md

技能還可以包含用於存放腳本、參考資料和資源的可選目錄：

.agents/
└── skills/
    └── deploy-app/
        ├── SKILL.md
        ├── scripts/
        │   ├── deploy.sh
        │   └── validate.py
        ├── references/
        │   └── REFERENCE.md
        └── assets/
            └── config-template.json

嵌套技能目錄¶

技能目錄可以包含子目錄，便於按類別、團隊或域名對相關技能進行分組。Cursor 會遞歸遍歷技能根目錄，並識別找到的所有 SKILL.md：

.cursor/
└── skills/
    ├── shipping/
    │   ├── land-it/
    │   │   └── SKILL.md
    │   └── careful-merge-conflicts/
    │       └── SKILL.md
    ├── debugging/
    │   └── using-datadog-mcp/
    │       └── SKILL.md
    └── workflow/
        └── tdd/
            └── SKILL.md

類別文件夾僅用於歸類。技能的標識由包含 SKILL.md 的文件夾決定 (如此處的 land-it、tdd 等) ，而非其父級類別。

Cursor 還會識別嵌套項目子目錄中的技能。代碼倉庫中任意位置的 .cursor/skills/ (或 .agents/skills/) 文件夾都會被識別，因此在單體倉庫中，可以將技能與其適用的 package 放在同一位置：

my-monorepo/
├── .cursor/skills/         # 倉庫級技能
│   └── land-it/SKILL.md
└── apps/
    └── web/
        └── .cursor/skills/  # 應用專屬技能
            └── deploy-web/SKILL.md

嵌套項目目錄中的技能會自動作用於該目錄內的文件。在上面的示例中，智能體僅在處理 apps/web/ 下的文件時纔會顯示 deploy-web；而倉庫級 .cursor/skills/ 中的技能則可在任何位置使用。這與 paths frontmatter 字段類似——無需爲嵌套技能設置 paths，即可將其限定在所在目錄內。

SKILL.md 文件格式¶

每項技能均通過一個包含 YAML frontmatter 的 SKILL.md 文件定義：

---
name: my-skill
description: 簡短說明此技能的功能及使用場景。
---

# 我的技能

爲代理提供的詳細說明。

## 何時使用

- 在...情況下使用此技能
- 此技能在...方面有幫助

## 說明

- 爲代理提供的逐步指導
- 特定領域的約定
- 最佳實踐和模式
- 如果需要向用戶澄清需求，請使用“詢問問題”工具

Frontmatter 字段¶

將技能限定爲僅適用於特定文件¶

使用 paths 字段將技能限定爲僅適用於匹配一個或多個 glob 模式的文件。這樣，只有當智能體讀取或編輯匹配的文件時，纔會啓用該技能，避免在處理無關工作時將特定文件的指導加入上下文。

---
name: react-component-patterns
description: Conventions for writing React components in this codebase.
paths:
  - "**/*.tsx"
  - "packages/ui/**/*.ts"
---

# React component patterns

...

您也可以傳入一個以逗號分隔的 string：

---
name: python-style
description: Style rules for Python files.
paths: "**/*.py, scripts/**/*.py"
---

模式遵循標準 glob 語法。若希望某項技能在打開任意文件時均可用，請不要設置 paths。

爲兼容較早版本的技能，仍支持使用舊版 globs 字段作爲後備；但新技能應使用 paths。

禁用自動調用¶

默認情況下，智能體判斷某項技能相關時，會自動應用該技能。設置 disable-model-invocation: true 可使技能像傳統斜槓命令一樣，只有在聊天中顯式輸入 /skill-name 時纔會被加入上下文。

將技能用作自定義模式¶

任何包含有效 frontmatter 塊的技能都可支持自定義模式，使該技能在整個會話期間始終保留在上下文中。啓用的模式會在聊天輸入框中顯示徽章。可通過可選的 icon 和 color frontmatter 字段設置其樣式：

---
name: tdd
description: Test-driven development playbook for this repo.
icon: beaker
color: green
---

圖標來自 Cursor 的圖標集，名稱包括 code、terminal、bug、git-branch、book-open、beaker、shield 和 rocket。無法識別的圖標或顏色將使用默認徽章 (閃電圖標) 。

在技能中包含腳本¶

技能可包含 scripts/ 目錄，其中存放可由智能體運行的可執行代碼。在 SKILL.md 中使用相對於技能根目錄的路徑引用腳本。

---
name: deploy-app
description: 將應用部署到預發佈或生產環境。用於部署代碼，或當用戶提及部署、發佈或環境時。
---

# 部署應用

使用提供的腳本部署應用。

## 用法

運行部署腳本：`scripts/deploy.sh <environment>`

其中，`<environment>` 可以是 `staging` 或 `production`。

## 部署前驗證

在部署之前，運行驗證腳本：`python scripts/validate.py`

智能體會讀取這些說明，並在調用技能時執行引用的腳本。腳本可使用任何語言編寫，如 Bash、Python、JavaScript，或智能體實現支持的其他可執行格式。

腳本應可獨立運行，提供清晰的錯誤消息，並妥善處理邊界情況。

可選目錄¶

技能支持以下可選目錄：

保持主 SKILL.md 簡潔，將詳細的參考資料移至單獨的文件。這樣可以更高效地利用上下文，因爲智能體會按需逐步加載資源。

查看技能¶

要查看已發現的技能，請在側邊欄中打開 自定義，然後前往 技能。從插件或您的項目安裝的技能會與規則一同顯示在 由智能體決定 部分。

從 GitHub 安裝技能¶

你可以從 GitHub 倉庫導入技能：

1. 在側邊欄中打開 自定義
2. 前往 規則，然後點擊 添加規則
3. 選擇 遠程規則 (GitHub)
4. 輸入 GitHub 倉庫 URL

將規則和命令遷移到技能¶

Cursor 2.4 內置了 /migrate-to-skills 技能，可幫助您將現有的動態規則和斜槓命令轉換爲技能。

遷移技能會轉換：

• 動態規則：使用“智能應用”配置的規則，即 alwaysApply: false (或未定義) 且未定義 globs 模式的規則。這些規則會轉換爲標準技能。
• 斜槓命令：用戶級和工作區級命令都會轉換爲設置了 disable-model-invocation: true 的技能，以保留其顯式調用行爲。

遷移方法：

1. 在智能體聊天中輸入 /migrate-to-skills
2. 智能體將識別符合條件的規則和命令，並將其轉換爲技能
3. 在 .cursor/skills/ 中評審生成的技能

alwaysApply: true 或定義了特定 globs 模式的規則不會被遷移，因爲它們具有不同於技能行爲的明確觸發條件。用戶規則也不會被遷移，因爲它們不存儲在文件系統中。

瞭解更多¶

Agent 技能 是一項開放標準。請訪問 agentskills.io 瞭解詳情。

相關內容¶

• 技能幫助信息