《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 了解详情。

相关内容¶

• 技能帮助信息