Agent Skills 速览

Agent Skills（常简称 Skills）是给 AI 编码助手用的说明文档：把某类任务的做法、团队约定、工具步骤写进 Markdown，模型在相关问题时优先按文档执行，而不是每次从零推断。

适用场景包括：固定代码审查清单、提交信息格式、内部 CLI/脚本用法、项目特有的目录与命名约定等。

和「系统提示 / 规则」的区别

方式	特点
用户规则、.cursor/rules	长期、全局或按仓库生效的偏好与约束
Skills	按主题拆文件，只在匹配到任务描述或显式 @ 引用时加载，适合可复用的「操作手册」

二者可以并存：规则管底线，Skills 管具体流程与细节。

目录怎么放

常见布局是「一个技能一个文件夹」，根文件必须是 SKILL.md：

skill-name/
├── SKILL.md          # 必填：主说明
├── reference.md      # 可选：附录、长文档
├── examples.md       # 可选：示例对话或输出样例
└── scripts/          # 可选：辅助脚本
    └── check.sh

存放位置大致两类：

• 个人：本机用户目录下的 skills（例如 Cursor 的 ~/.agents/skills/ 等，以当前客户端文档为准），所有项目可用。
• 项目：仓库内 .cursor/skills/（或工具文档指定的路径），和代码一起版本管理，团队共享。

内置、只读的技能目录不要手改；新增技能放在个人或项目目录即可。

SKILL.md 写什么

文件分两段：YAML 头 + 正文。

1. Frontmatter（YAML）

   • name：技能标识，小写、短横线连接。
   • description：一句话说明「做什么、何时用」。写得越像真实用户提问，越容易在对话里被自动选中。

2. 正文

   • 用二级标题拆块：目标、前置条件、步骤、注意事项、相关链接。
   • 步骤要可执行（先做什么、再做什么），避免只有口号。
   • 需要固定输出格式时，直接给模板或示例。

示例骨架（按你使用的工具调整字段名是否必填）：

---
name: my-skill-name
description: 当用户要 X 或提到 Y 时使用；说明如何完成 Z。
---

# 技能标题

## 何时使用
- 用户明确说 …
- 或涉及 … 文件/命令时

## 操作步骤
1. …
2. …

## 注意事项
- …

编写建议

• 触发条件写进 description：用自然语言描述「用户会怎么问」，比只写内部代号更有效。
• 宁可拆多个小 Skill：一个文件一个主题，比一本大杂烩更容易维护、也更容易被精准加载。
• 和仓库现状对齐：引用真实路径、真实命令；过时内容会误导模型。
• 大段参考放附件：主文件保持简短，细节放到 reference.md 或链到 wiki 其他页。

延伸阅读

• Cursor 官方文档中关于 Agent Skills 的说明（路径与 frontmatter 以当前版本文档为准）。
• 本仓库若后续在 src/ai/ 下增加子页面，可在此用列表链到各专题（提示词、MCP、工作流等）。

---

若你使用的产品对路径或 frontmatter 字段有特殊要求，以该产品最新文档为准；上表与目录约定描述的是常见模式。