Cursor 中优雅使用 Agent Skills：从 0 到一套可复用的“技能系统”

这篇文档是为博客平台（如 CSDN）准备的版本，去掉了本机路径、代理等敏感信息，只保留通用思路和可复用步骤。你可以直接复制内容到博客中发布。

一、先搞清楚：Skills 在项目里长什么样？

在 Anthropic 的 Agent Skills 标准下，一套完整的技能系统，通常包含三部分：

.claude/skills/
- 每个 Skill 一个子目录，里面有：
  - SKILL.md：技能说明书（任务、步骤、约束、示例……）
  - scripts/：可选脚本（Python / TS / Shell 等）
  - references/：可选参考文档
- 例如：
```
.claude/ skills/ frontend-design/ SKILL.md doc-coauthoring/ SKILL.md ...
```

AGENTS.md

把项目里安装的所有 Skills 列成一个“目录 + 使用说明”，给 Agent 看。

典型结构（简化）：

<skills_systempriority="1"><available_skills><skill><name>frontend-design</name><description>用于设计高质量前端界面...</description></skill><skill><name>doc-coauthoring</name><description>用于写技术文档、方案、报告...</description></skill>...</available_skills></skills_system>

openskillsCLI 工具
- 用来安装、列出、读取、同步 Skills：
  - openskills install ...
  - openskills list
  - openskills read <skill-name>
  - openskills sync

一句话总结：
.claude/skills/是技能仓库，AGENTS.md是目录，openskills是打理它们的工具。

二、本机环境准备（一次性）

你只需要准备一套 Node 环境和一个 CLI 工具。

1. 安装 Node 20+（推荐）

Skills 工具链通常要求 Node 20+，用你喜欢的版本管理工具即可（nvm / Volta 等）：

node-v# 建议 >= 20.x

如果你用 nvm：

nvminstall20nvm use20

2. 全局安装 OpenSkills

npmi -g openskills

验证一下：

openskills --version

看到版本号就说明安装成功。

三、在项目里安装官方 Skills（生成`.claude/skills`）

假设你的项目根目录是：

cd/path/to/YOUR_PROJECT

在项目根目录执行：

# 把 Anthropic 官方 skills 安装到当前项目（-p = project，-y = 不交互全选）openskillsinstall-p -y anthropics/skills

成功后，你的项目结构会多出一段：

YOUR_PROJECT/ .claude/ skills/ algorithmic-art/ frontend-design/ doc-coauthoring/ ...

每个目录下都有一个SKILL.md，可以自己打开学习。

提示：如果你后面想加自己的 Skill（比如团队内部的“写单测 skill”），只要在.claude/skills/your-skill-name/下写一个SKILL.md即可。

四、生成`AGENTS.md`：注册技能清单

同样在项目根目录：

cd/path/to/YOUR_PROJECT# 如果没有 AGENTS.md，就先创建空文件test-f AGENTS.md||:>AGENTS.md# 用 OpenSkills 把当前项目已有 skills 写入 AGENTS.mdopenskillssync

执行完之后，打开AGENTS.md，你会看到一个<skills_system>区块，里面列出了所有 Skills 的<name>和<description>。

到这一步为止，你的项目已经具备了：

.claude/skills/：技能内容
AGENTS.md：技能目录 + 使用说明

之后不管换哪台机器、哪个 IDE，只要把这个项目拉下来，这套技能系统都在。

五、在 Cursor 中启用 Agent Skills

下面以 Cursor 为例（支持 Skills 的 IDE 都类似）：

1. 打开 Nightly 渠道（只做一次）

打开 Cursor 设置：Settings → Beta
将更新通道切换为Nightly

2. 打开 Agent Skills 功能

打开：Settings → Rules
找到Agent Skills或类似选项
打开开关

这样 Cursor 在帮你写代码时，就会自动考虑当前项目的AGENTS.md和.claude/skills/。

六、在 Cursor 里实际使用 Skills

场景 1：显式调用某个 Skill（推荐在学习 / 调试时用）

假设你想用frontend-design帮你写一个登录页面的 UI，在 Cursor 中：

打开项目根目录。
在一个相关文件中按Cmd+L（Chat 模式）。
输入类似提示：

Bash("openskills read frontend-design")

然后继续说：

基于刚才读取到的 frontend-design skill，帮我设计一个登录页面的 UI，并生成对应的 React 组件代码。

Cursor 背后的 Agent 会：

实际执行openskills read frontend-design；
把.claude/skills/frontend-design/SKILL.md的内容纳入上下文；
按 skill 里的设计原则来写代码（而不是默认的“AI 风格渐变 + 宋体/默认字体”）。

场景 2：让技能指导你的文档结构

同理，如果你在写技术文档，想要有一个好的结构，可以：

Bash("openskills read doc-coauthoring")

接着：

根据 doc-coauthoring skill，帮我为当前模块写一份技术设计文档，包含：背景、目标、架构设计、关键流程、风险与权衡。

生成出来的文档，会更「像是有固定模板」的系统化内容，而不是随手写两段感想。

场景 3：不提技能名，看 Agent 会不会自动用 Skill

等你对 Skills 体系熟悉之后，可以尝试“隐式调用”：

在项目里某个目录下新建一个空的main.py，
只用自然语言描述任务，例如：

帮我在当前目录下实现一个命令行 Todo 程序，要求： - 可以添加/列出/标记完成/删除待办 - 启动时从 JSON 文件加载，退出时保存 - 结构要清晰、易扩展，方便今后增加优先级、截止日期等功能

如果你在AGENTS.md里注册了一个类似python-todo-skill的技能，且描述贴合上面任务，那么 Agent 很可能会自动参考这个 Skill 的设计，生成一个具备：

TodoItem数据模型
TodoApp业务类
分层交互函数（print_items/print_menu/handle_choice/main）

这样的结构化实现。

这时你可以通过对比：

生成的代码结构
Skill 里推荐的结构（SKILL.md）

来判断它有没有“听从 Skill 的指导”。

七、显式 vs 隐式：什么时候用哪种方式？

显式调用（清晰、可控）
- 用在：
  - 第一次用某个 Skill；
  - 在调试、迭代 Skill；
  - 希望强制 Agent 必须按照某个 Skill 的 SOP 来做。
- 写法：先Bash("openskills read xxx")，再给具体任务。
隐式调用（自然、顺手）
- 用在：
  - 日常开发，懒得每次都提 Skill 名；
  - 你已经习惯某套设计方式，希望 Agent 的“默认写法”就是那样。
- 前提：
  - AGENTS.md和.claude/skills配置完善；
  - 每个 Skill 的描述足够清晰，便于模型做语义匹配。