angent Skills 上手指南

最近我在用 Cursor 做项目时，一个感受很明显：AI 写不写得好，很多时候不取决于模型有多强，而是你有没有把“怎么做事”这套方法固定下来。Cursor 里的 Agent Skills（有些地方也会写成 angent skills）就干这个：把一套可复用的工作方式沉淀成“技能”，以后遇到类似任务，直接复用，不用每次从头解释一遍。

这篇就按上手角度讲清楚：它是什么、什么时候用、怎么装怎么用，最后再给一组在 Cursor 里能直接套用的提示词。

1. angent Skills 是什么

我更愿意把它理解成一份“项目内的工作说明书”，核心目标是让 AI 的输出更稳定、更贴合你的团队习惯。

它通常包含三部分：

1. 你希望 AI 按什么流程做事：比如先读哪些文件、先给方案再改代码、改完要跑哪些命令验证
2. 你希望 AI 遵守哪些风格/约束：命名、目录结构、组件导出方式、是否允许引入新依赖、是否允许改动某些文件
3. 你希望 AI 给到什么交付物：代码、文档、测试清单、迁移步骤、风险点说明

和 Cursor Rules 的区别可以这么记：

• Rules 更像“通用交规”（全局偏好/项目规范）
• Skills 更像“专项 SOP”（做某类任务的固定套路）

两者叠加之后，效果通常比单独用其中一个要稳定得多。

2. 什么时候用 angent Skills（使用场景）

我用下来，下面几类场景特别适合做成 skill：

2.1 重复且容易走样的工作

比如：

• 新增一个页面/组件时，目录、导出、样式方案总是要解释一遍
• 写工具函数时，总有人忘了边界处理、忘了错误提示
• 写文档时，总是写不全“背景/方案/测试/回滚”

把这些写成 skill 之后，你只要说“按 skill 做”，AI 就会自动按步骤补齐。

2.2 需要跨文件、跨模块协作的改动

比如：

• 重构：拆分组件、抽 hooks、统一 utils、改 API 层调用
• 新特性：会牵涉路由、状态管理、接口、UI、埋点

这类任务最怕 AI 在某个文件里“局部优化”导致全局不一致。skill 里把“先扫结构、再列影响面、最后小步改动”的流程写死，会稳很多。

2.3 团队规范多、踩坑多的项目

项目越大，越需要让 AI 遵守一些“不能碰”的红线，比如：

• 禁止覆盖 .env
• 生产环境禁用 mock
• 只允许最小改动，避免牵一发动全身

这些放在 skill 里，等于每次都带着护栏在做事。

3. 如何安装（创建）一个 angent Skill

以项目级 skill 为例（推荐，跟着仓库走，团队共享最方便），常见结构是：

• .cursor/skills/<skill-name>/SKILL.md：技能正文
• .cursor/skills/<skill-name>/.skill-meta.json：技能元信息（名称、描述、触发场景等）

你可以从“先写一个最小可用版”开始，不用一口气写得很复杂。一个实用的 SKILL.md 通常包含：

• 适用范围：什么任务该用它，什么任务别用它
• 输入要求：AI 开始前需要哪些上下文（@某些目录/文件、接口文档、截图等）
• 执行步骤：明确到“先做什么，再做什么”
• 输出格式：比如必须带测试计划、必须列出影响文件清单

如果你已经有 Cursor Rules，也建议在 skill 里写一句：“遵守项目 Rules”，避免两边冲突时 AI 自己发挥。

4. 如何使用（在 Cursor 里怎么触发）

使用方式说白了就两条：

4.1 让 AI “按某个 skill 的流程”执行任务

你可以在对话里直接说：

• “按 xxx skill 的流程做”
• “严格遵循 skill 里的步骤，先给方案再改代码”

如果你希望更稳一点，建议把相关上下文一起带上（Cursor 里最常用的是 @ 引用文件/目录）。

4.2 给足上下文，别让 AI 猜

技能再好，如果上下文缺失，AI 也只能猜。我的经验是：

• 改代码：至少带上涉及的目录或关键文件（比如 @src/xxx/ 或 @某个组件文件）
• 改配置：把配置文件直接引用进来（比如 @package.json、@vite.config.ts）
• 修 bug：带报错堆栈、复现路径、期望行为

5. Cursor 中可直接套用的提示词示例

下面这些示例我尽量写得“像平时真会这么说”，你可以按需替换其中的文件引用。

5.1 新增功能（跨文件改动）

按我们项目的 angent skill 流程实现这个需求：新增「文章目录 TOC」组件。

上下文：
- @source/_posts/（文章结构参考）
- @themes/（主题目录）

要求：
1. 最小改动，不要大范围重构主题
2. 先给实现方案（涉及哪些文件、怎么插入），确认后再开始改
3. 需要考虑移动端展示
4. 给出自测清单

5.2 修复问题（带复现与边界）

按 angent skill 的排查流程帮我定位问题：本地 hexo serve 正常，但部署后部分图片 404。

已知信息：
1. 复现路径：打开文章「Cursor入门与实践」页，图片加载失败
2. 期望：线上和本地表现一致

上下文：
- @_config.yml
- @_config.fluid.yml
- @source/_posts/cursor.md

要求：
1. 先分析可能原因并给验证步骤
2. 不要引入新依赖
3. 如果需要改动，优先改配置而不是改每篇文章

5.3 写文档（要求输出结构固定）

按 angent skill 的文档模板写一份「项目部署说明」。

上下文：
- @README.md
- @.github/workflows/deploy.yml

输出要求：
1. 必须包含：背景、部署流程、常见失败原因、回滚方式
2. 步骤用可执行的命令/菜单路径描述
3. 不要写空话，能直接照着做

5.4 批量改动（强调风险控制）

按 angent skill 流程做一次“安全的批量替换”：
把文章里所有 http://www.jiatt.top 的图片链接，整理成一个可选方案（不直接改），并说明改动风险。

上下文：
- @source/_posts/

要求：
1. 先统计影响范围（多少文件、多少处）
2. 给两种方案：全量替换 vs 仅替换最近文章
3. 不要直接落地改动，先给我一个执行计划

结语

angent Skills 这东西，说到底就是把你平时“怎么做事”的经验写下来。它不玄学，反而很工程：流程写清楚、约束写清楚、输出写清楚，AI 自然就不太容易跑偏。

如果你已经在用 Cursor Rules，那下一步基本就是：把你最常做、最容易返工的那 1～2 件事，先做成 skill。等你用顺了，再慢慢补齐更多场景。