agent-skills 在 Cursor 中的接入实战：skills 目录同步与 .mdc 项目规则配置

本文以 agent-skills 仓库的 docs/cursor-setup.md 为主体，讲解如何将这套面向 AI 编码代理的工程工作流技能包接入 Cursor：用 .cursor/skills/ 承载完整技能工作流、用 .cursor/rules/*.mdc 承载简短策略，并给出同步命令、规则文件格式、验证步骤与排错方法。读完后你能在任何仓库中独立完成一次可复现的 Cursor + agent-skills 配置，并理解技能路由背后的 frontmatter 契约。

Cursor 当前的两级上下文模型：rules 与 skills

Cursor 将上下文约束拆成两层，agent-skills 的接入方式就是围绕这两层展开的：

层级	路径	职责
项目规则（Project rules）	.cursor/rules/*.mdc	始终生效或按文件范围生效的指令（alwaysApply、globs）
项目技能（Project skills）	.cursor/skills/<skill-name>/SKILL.md	Agent 自动发现的工作流；当任务与技能 description 匹配时被读取
用户规则（User rules）	Cursor Settings → Rules	账号级别的策略
用户技能（User skills，可选）	~/.cursor/skills/	在所有工作区全局可用的技能

Rules 与 skills 的分工

• Rules —— 简短、稳定的策略（例如“使用约定式提交”“为公开 Python API 添加类型注解”）。原则是一个文件只写一个关注点，避免粘贴大段指南。
• Skills —— 来自本仓库的分步流程（test-driven-development、code-review-and-quality 等）。不要把整个 SKILL.md 正文复制进 rules：那会让 .cursor/skills/ 与规则文件重复维护同一份内容，白白消耗上下文窗口。

遗留方案对照（新配置应避开）

遗留做法	推荐替代
根目录 .cursorrules 文件	.cursor/rules/*.mdc
把 SKILL.md 复制进 .cursor/rules/	放在 .cursor/skills/<name>/SKILL.md
“把 10 个技能都设为 always-on 规则”	1～2 条精简的 alwaysApply 路由规则 + 按需加载的技能

推荐的项目目录布局

agent-skills 的 docs/cursor-setup.md 给出的目标结构如下（agent-skills/ 可以是 git submodule 或 vendored clone，仅作上游源）：

your-project/
├── .cursor/
│   ├── rules/                    # 简短的 .mdc 策略（你自己编写）
│   │   └── agent-skills.mdc      # 可选：一条“使用项目技能”的路由指引
│   └── skills/                   # Cursor Agent 实际加载的内容
│       ├── using-agent-skills/
│       ├── test-driven-development/
│       ├── code-review-and-quality/
│       └── …                     # 从 agent-skills 同步 + 你自己的技能
└── agent-skills/                 # 可选：git submodule 或 vendor clone
    └── skills/                   # 仅作为上游源

关键原则：对 Agent 而言，事实源（source of truth）是 .cursor/skills/。仓库里的 agent-skills/skills/（或克隆的上游 addyosmani/agent-skills 仓库）只是上游——必须把它同步进 .cursor/skills/，而不是只改上游就期望 Cursor 能看到。这与上游仓库的实际组织方式一致：从 README.md 的项目结构看，skills/ 下每个技能一个目录、目录内唯一必需文件是 SKILL.md，配套可选材料放在技能目录内的 references/ 或附加 markdown 文件中（例如 skills/constraint-driven-development/references/floor-guard.md、skills/idea-refine/frameworks.md），这些都会随目录一起被 rsync 带进 .cursor/skills/。

安装：把 skills 同步进 .cursor/skills/

从本地 agent-skills 克隆同步

首次完整同步（克隆位于项目根目录或其他位置均可）：

mkdir -p .cursor/skills
rsync -a /path/to/agent-skills/skills/ .cursor/skills/

首次复制但不覆盖已有自定义技能（保留你手写的同名技能）：

rsync -a --ignore-existing /path/to/agent-skills/skills/ .cursor/skills/

上游更新后重新同步：

rsync -a /path/to/agent-skills/skills/ .cursor/skills/

SKILL.md 的 frontmatter 契约

每个技能目录必须包含带 YAML frontmatter 的 SKILL.md，最少包含：

---
name: test-driven-development
description: Drives development with tests. Use when implementing logic, fixing bugs, or changing behavior.
---

Cursor 依据 description（及相关元数据）判断何时应用某个技能。这条约束在上游的 docs/skill-anatomy.md 中有完整的格式规范，结合源码可以确认几个影响 Cursor 实际行为的细节：

• name 必须是小写连字符命名，且与目录名一致。以 skills/test-driven-development/SKILL.md 为例，目录名、name 字段、Cursor 技能列表里显示的名字三者完全对齐；
• description 上限 1024 字符，写法是“第三人称说明技能做什么 + 一个或多个 Use when 触发条件”，要同时讲清 what 和 when；
• 不要在 description 里概括流程步骤。skill-anatomy 明确解释：description 会被注入系统提示，若其中包含过程摘要，Agent 可能照着摘要执行而不再读取完整 SKILL.md——这正是“路由靠 description、正文靠按需加载”这一 Cursor 模型得以成立的前提。

最小项目规则：.cursor/rules/agent-skills.mdc

创建一个 .cursor/rules/agent-skills.mdc，作为技能的“路由入口”（原文档给出的完整示例）：

---
description: Use agent-skills workflows from .cursor/skills
alwaysApply: true
---

Before non-trivial technical work:

1. Route via `.cursor/skills/using-agent-skills/SKILL.md`.
2. Read and follow the matching skill under `.cursor/skills/<name>/SKILL.md`.
3. Open `reference.md` in that folder when the skill links to it.
4. Prefer project skills over guessing; user does not need to say "read skill" each time.

仓库特定的规范（代码风格、语言约定、技术栈）应写成独立的 .mdc 文件，每个文件聚焦一个主题。规则文件的标准格式：

---
description: Shown in Cursor rule UI
alwaysApply: false
globs: "**/*.{ts,tsx}"
---

# Your rule content

各 frontmatter 字段的用途：

字段	用途
alwaysApply: true	本项目的所有对话都注入该规则
globs	上下文里出现匹配文件时注入
alwaysApply: false 且无 globs	Agent 按需请求 / 在 Cursor UI 中手动启用的规则

注意第 1 条路由规则指向的 skills/using-agent-skills/SKILL.md 是技能包中的“元技能”：从源码看，它内置了一棵完整的任务发现树（Task arrives → 按开发阶段分支到 interview-me / spec-driven-development / test-driven-development / code-review-and-quality 等具体技能），并定义了六条全局运行行为（声明假设、主动管理困惑、必要时反驳、保持简洁、范围纪律、验证优先）。这正是 Cursor 侧只放一条薄路由规则、把厚重流程留在技能正文里的设计意图。

用户级技能（可选）

把希望全局生效的技能复制或安装到 ~/.cursor/skills/ 下，适合放与技术栈相关、但不属于 agent-skills 的通用指南（例如某种语言的模式库）。对于当前仓库的工作流，.cursor/skills/ 中的项目级技能具有优先地位。

验证接入是否生效

1. Settings → Rules：项目里的 .mdc 文件应出现在规则列表中；
2. Agent 对话：来自 .cursor/skills/ 的技能应出现在技能列表中（取决于你的 Cursor 版本是否暴露该 UI）；
3. 行为验证：执行一个能映射到某技能的任务（例如“先写测试再加一个功能”），且不点名任何文件——路由正常时，Agent 应自行打开 test-driven-development 技能。

Agent 使用技能的四步路由

接入完成后，Agent 侧的使用模型是：

1. Discover（发现） —— using-agent-skills 元技能把任务阶段映射到技能名；
2. Read（读取） —— 完整流程在 .cursor/skills/<name>/SKILL.md；
3. Deep dive（深入） —— 当技能声明指向支撑材料时，读取该目录内的 reference.md、references/*.md 或关联清单。从源码结构看，这类按需加载是普遍存在的：skills/idea-refine/ 附带 frameworks.md、examples.md、refinement-criteria.md，skills/constraint-driven-development/references/ 下挂有专题参考文件，它们不会常驻上下文，只在技能流程需要时才被读入；
4. Combine（组合） —— 例如一个 API 切片可以组合 incremental-implementation + api-and-interface-design。

如果 Agent 走偏，显式短语仍然有效（“follow TDD”、“use code-review-and-quality”）。

阶段 → 技能速查表

你正在…	对应技能
澄清需求	interview-me、idea-refine、spec-driven-development
规划任务	planning-and-task-breakdown
实现代码	incremental-implementation、frontend-ui-engineering、api-and-interface-design
测试	test-driven-development、browser-testing-with-devtools
调试	debugging-and-error-recovery
评审	code-review-and-quality、code-simplification
安全 / 性能	security-and-hardening、performance-optimization
Git / CI / 发布	git-workflow-and-versioning、ci-cd-and-automation、shipping-and-launch

完整的技能树以仓库内 skills/using-agent-skills/SKILL.md 为准，其中还给出了一个完整特性的典型生命周期序列（interview-me → idea-refine → spec-driven-development → planning-and-task-breakdown → … → code-review-and-quality → … → shipping-and-launch，共 16 步，并说明“并非每个任务都需要全部技能”）。

反模式：不要做什么

原文档列出的反模式与替代做法：

避免	替代做法
把所有技能粘贴进一条规则	同步到 .cursor/skills/
维护两份互相漂移的副本	从上游 rsync；把 .cursor/skills/ 提交进版本库
大量 alwaysApply: true 规则	一条路由规则 + 按 glob 聚焦的规则
只依赖 .cursorrules	迁移到 .mdc + skills
期望 agent-skills/agents/*.md 被自动加载	粘贴进对话，或提炼成一条短规则

上下文预算管理技巧

• always-on 规则保持最小：只放路由 + 1～2 条不可妥协的硬约束；
• 长清单交给技能：冗长的检查表和“借口反驳表”（rationalization tables）留在技能正文里，靠 description 路由按需加载；
• 按需添加阶段性 globs 规则：例如仅在涉及 Python 时（**/*.py）或组件目录（**/components/**）时生效；
• 验证步骤被跳过时：用技能名在对话里提醒（nudge）Agent 回到流程。

agents/ 目录在 Cursor 中不会被自动加载

agent-skills/agents/ 下是四个预配置的角色（persona）定义文件，例如 agents/code-reviewer.md（Senior Staff Engineer 视角的五维评审框架）、agents/security-auditor.md、agents/test-engineer.md、agents/web-performance-auditor.md。它们在 Cursor 中不会自动加载，可选的处理方式有三种：

• 引用对应的等价技能（如 code reviewer 对应 code-review-and-quality）；
• 把角色 markdown 一次性粘贴进对话，用于单次专项评审；
• 从中提炼一个简短清单做成 .mdc 规则。

从 agents/code-reviewer.md 的 frontmatter 可以看到，这些角色文件同样遵循 name + description 的格式，正文包含完整的评审框架（Correctness / Readability / Architecture / Security / Performance 五个维度），因此“提炼短清单”或“粘贴全文进对话”两种方式都有现成素材可用。

故障排查

症状	检查点
技能从未被使用	.cursor/skills/<name>/ 下是否有 SKILL.md？frontmatter 的 description 是否有效？
规则被忽略	扩展名是否为 .mdc？alwaysApply / globs 是否正确？
工作流过期	重新从 agent-skills/skills/ 执行 rsync
指令重复出现	从规则中删掉技能正文内容，只保留单一事实源
选错了技能	收窄自定义技能的 description；在对话中点名提醒

其中“指令重复”一项呼应了 skill-anatomy 的原则：description 只负责触发，流程正文只应存在于技能目录内一份。

新项目接入清单

• [ ] mkdir -p .cursor/skills 并从 agent-skills/skills/ 同步
• [ ] 可选：添加带路由指引的 .cursor/rules/agent-skills.mdc
• [ ] 把仓库特定规则写成独立的小 .mdc 文件
• [ ] 将 .cursor/skills/ 和 .cursor/rules/ 提交进版本库（团队共享同一套行为）
• [ ] 除非遗留工具强制要求，跳过巨型 .cursorrules 文件

延伸阅读

• docs/getting-started.md —— 与任意 Agent 的通用接入方式、最小三技能组合与生命周期加载顺序
• README.md —— 全部 25 个技能（24 个生命周期技能 + 1 个元技能）总览，以及 Cursor 章节对本指南的引用
• docs/skill-anatomy.md —— SKILL.md 的完整格式规范（frontmatter 契约与标准章节）
• docs/adoption-guide.md —— 绿地项目与既有代码库的两种落地路径