Cursor Skill 开发：把工程经验变成 AI 可执行的技能

本文是【AI 专题精讲】系列第 12 篇。 上一篇：大模型微调实战：从 LoRA 到部署上线的完整方案 下一篇：Harness Engineering：从”AI 辅助”到”驾驭 AI”的工程效能革命

---

这篇文章你会得到什么

团队里总有些”隐性知识”——部署流程、代码规范、发布 checklist、故障排查步骤。这些知识要么在某个人脑子里，要么散落在 Wiki 和聊天记录中。每次新人入职或换人值班，都得重新”师傅带徒弟”。

如果能把这些工程经验直接教给 AI，让它像一个老员工一样执行标准化流程呢？

这就是 AI Skill（技能） 的价值：把隐性的工程知识变成显性的、AI 可直接执行的标准化能力。

今天以 Cursor 的 Skill 机制为例（其他 AI IDE 的思路类似），从设计思想到实战开发，完整走一遍。

---

从”告诉 AI 怎么做”到”AI 自己知道怎么做”

你一定遇到过这种场景

每次让 AI 帮你部署项目，都要说：

“先 SSH 到 8.135.x.x，然后 cd 到 /var/www/blog，执行 git pull，再 pnpm install，再 pnpm build……”

每次让 AI 帮你发 npm 包：

“先检查 version 有没有改，然后确认登录状态，再 npm publish，发完之后打 tag……”

重复说第三遍的时候你就烦了。而且不同人说的流程还不一样——有人漏了打 tag，有人忘了 frozen-lockfile。

Skill 解决的就是这个问题

一次编写，永久执行。把标准流程写成 Skill，AI 就像一个永远记得所有步骤、永远不犯低级错误的新员工：

方式	首次成本	后续成本	一致性	可传承
口头传授	低	每次重复	❌ 靠记忆	❌ 人走知识散
Wiki 文档	中	翻文档找命令	⚠️ 文档可能过时	⚠️ 有但不好用
Shell 脚本	高	低	✅ 固定	✅ 但不灵活
AI Skill	中	零	✅ 标准化	✅ AI 直接执行

Skill 相比纯脚本的优势：它是自然语言 + 结构化指令的结合。脚本只能走固定路径，Skill 可以让 AI 根据上下文判断走哪个分支、跳过哪些步骤、怎么处理异常。

---

AI IDE 的四大扩展机制

在深入 Skill 之前，先理清楚它在整个扩展体系中的位置。以 Cursor 为例，有四种机制让你”教”AI 做事：

Rule（规则）——约束 AI 的行为

“写 TypeScript 时用函数式组件，不要 class 组件”

---
description: TypeScript 编码规范
globs: "**/*.ts"
alwaysApply: false
---

# 错误处理
- try/catch 必须有明确的错误日志
- 禁止空 catch 块

# 命名
- 变量用 camelCase
- 常量用 UPPER_SNAKE_CASE

Rule 像”纪律”——告诉 AI 不该做什么、应该遵守什么。

Skill（技能）——教 AI 完成任务

“帮我部署博客到服务器”

---
name: deploy-blog
description: 部署博客到 ECS 服务器。当用户提到部署博客、更新博客、发布博客时触发。
---

# 部署博客

## 流程
1. 确认用户意图
2. SSH 到服务器执行部署脚本
3. 报告结果

Skill 像”技能”——教 AI 怎么做一件具体的事。

Hook（钩子）——自动守护

“每次编辑文件后自动格式化”

{
  "version": 1,
  "hooks": {
    "afterFileEdit": [
      { "command": ".cursor/hooks/format.sh" }
    ]
  }
}

Hook 像”守卫”——无需手动触发，事件发生时自动执行。

Subagent（子智能体）——专家委派

“让 Code Review 专家审查这段代码”

---
name: code-reviewer
description: 代码审查专家，自动审查代码质量和安全性。
---

你是高级代码审查员，审查重点：
- 逻辑正确性
- 安全漏洞
- 性能问题

Subagent 像”专家顾问”——有独立上下文的专门助手。

四者的关系

┌─────────────────────────────────────────────┐
│               你的一句指令                     │
│         "帮我部署博客到服务器"                  │
└──────────────────┬──────────────────────────┘
                   ▼
┌──────────────────────────────────────────────┐
│  Rule（约束层）                                │
│  - 部署前必须确认                              │
│  - 禁止直接操作生产数据库                       │
└──────────────────┬───────────────────────────┘
                   ▼
┌──────────────────────────────────────────────┐
│  Skill（能力层）                               │
│  - 读取部署配置                                │
│  - 执行 SSH + 构建 + 重启                      │
│  - 报告部署结果                                │
└──────────────────┬───────────────────────────┘
                   ▼
┌──────────────────────────────────────────────┐
│  Hook（守护层）                                │
│  - 部署完成后自动通知                           │
│  - 失败时自动回滚                              │
└──────────────────┬───────────────────────────┘
                   ▼
┌──────────────────────────────────────────────┐
│  Subagent（专家层）                             │
│  - 部署前让安全专家审查变更                      │
│  - 部署后让测试专家验证                          │
└──────────────────────────────────────────────┘

选型建议：

你想要…	用
约束 AI 的行为规范	Rule
教 AI 完成一个具体任务	Skill
在某个事件后自动执行	Hook
委派给一个专门的 AI 角色	Subagent

---

Skill 开发规范

文件结构

skill-name/
├── SKILL.md              # 必需：主指令文件
├── reference.md          # 可选：详细参考
├── examples.md           # 可选：使用示例
└── scripts/              # 可选：工具脚本
    └── validate.sh

存放位置

类型	路径	作用域
个人 Skill	~/.cursor/skills/skill-name/	你所有项目可用
项目 Skill	.cursor/skills/skill-name/	项目内共享，可提交到 Git

选择建议：通用流程（部署、发包）放个人目录；项目特有规范放项目目录。

SKILL.md 结构

每个 Skill 必须包含 YAML frontmatter：

---
name: deploy-project
description: Deploy or update projects to ECS server via SSH, or publish npm packages locally. Use when the user mentions deploying, publishing, updating, or releasing any project.
---

# Deploy Project

Automate project deployment and publishing.

## Workflow
1. Identify which project to deploy
2. Confirm with user before executing
3. Execute commands
4. Report results

frontmatter 字段

字段	要求	说明
name	必填，最长 64 字符，小写字母 + 数字 + 连字符	Skill 的唯一标识
description	必填，最长 1024 字符	关键：AI 靠它决定什么时候触发

description 的写法（核心）

description 是 Skill 被发现和触发的关键。写不好，AI 就不知道什么时候该用这个 Skill。

三条原则：

1. 用第三人称：description 会被注入到 AI 的系统提示词中

# ✅ 好
description: Deploy projects to ECS server via SSH. Use when the user mentions deploying or publishing.

# ❌ 坏
description: I help you deploy projects.

2. 包含触发词：想想用户会怎么说

# ✅ 具体，包含多种触发场景
description: >-
  Deploy or update projects to ECS server via SSH, or publish npm
  packages locally. Use when the user mentions deploying, publishing,
  updating, or releasing any project such as blog, resume, or CLI tools.

# ❌ 太模糊
description: Helps with server tasks.

3. 同时写 WHAT 和 WHEN：

# WHAT: 这个 Skill 做什么
# WHEN: 什么时候触发
description: >-
  Generate commit messages by analyzing git diffs (WHAT).
  Use when the user asks for help writing commit messages
  or reviewing staged changes (WHEN).

---

四种 Skill 设计模式

模式一：Template（模板模式）

适合：需要固定格式输出的场景。

---
name: changelog-generator
description: >-
  Generate changelogs from git history. Use when the user
  mentions changelog, release notes, or version history.
---

# Generate Changelog

## Output Template

```markdown
# Changelog vX.Y.Z (YYYY-MM-DD)

## ✨ New Features
- Feature description (#PR)

## 🐛 Bug Fixes
- Fix description (#PR)

## 🔧 Internal
- Refactoring or tooling changes (#PR)

Steps

1. Run git log --oneline since last tag
2. Categorize commits by conventional prefix
3. Fill template
4. Present for review

### 模式二：Workflow（流程模式）

适合：多步骤、有顺序依赖的复杂流程。

```markdown
---
name: npm-publish
description: >-
  Publish npm packages with full checklist. Use when the user
  mentions npm publish, release package, or version bump.
---

# npm Publish

## Pre-publish Checklist
- [ ] Version bumped in package.json
- [ ] CHANGELOG updated
- [ ] All tests passing
- [ ] Committed and pushed to GitHub

## Workflow
1. **Verify**: Run `npm whoami` to confirm login
2. **Test**: Run `npm test`
3. **Confirm**: Ask user to confirm version and publish
4. **Publish**: Run `npm publish`
5. **Tag**: `git tag vX.Y.Z && git push --tags`
6. **Report**: Show publish result and npm page URL

模式三：Conditional（条件分支模式）

适合：根据不同条件走不同路径的场景。

---
name: deploy-project
description: >-
  Deploy projects to server or publish to npm.
  Use when user mentions deploy, publish, update, or release.
---

# Deploy Project

## Project Registry

### Blog (SSH Deploy)
| Field | Value |
|-------|-------|
| Trigger | 博客, blog |
| Server path | /var/www/blog |
| Command | `ssh root@x.x.x.x 'cd /var/www/blog && bash deploy.sh'` |

### AI Review Pipeline (npm Publish)
| Field | Value |
|-------|-------|
| Trigger | ai-review-pipeline, review pipeline |
| Local path | ~/projects/ai-review-pipeline |
| Command | `npm publish` |

## Workflow
1. **Identify** project from user message
2. **Match** to registry above
3. **Confirm** with user before executing
4. **Execute** corresponding command
5. **Report** result

模式四：Feedback Loop（反馈循环模式）

适合：质量敏感、需要验证的场景。

---
name: db-migration
description: >-
  Create and validate database migrations.
  Use when user mentions migration, schema change, or alter table.
---

# Database Migration

## Workflow
1. Generate migration SQL
2. **Validate**: Run `python scripts/validate_migration.py`
3. If validation fails:
   - Review error message
   - Fix the migration
   - Re-validate (repeat until pass)
4. **Only proceed when validation passes**
5. Apply to dev environment
6. Confirm with user before applying to staging

---

实战一：项目部署 Skill

这是我自己在用的一个真实 Skill。管理着多个项目的部署——有的走 SSH 部署到 ECS，有的走 npm publish。

完整的 SKILL.md

---
name: deploy-project
description: >-
  Deploy or update projects to ECS server via SSH, or publish
  npm packages locally. Use when the user mentions deploying,
  publishing, updating, or releasing any project such as resume,
  blog, ai-review-pipeline, ai-commit, ai-i18n, or mentions
  server update/deployment.
---

# Deploy Project

Automate project deployment and publishing.
Always confirm with the user before executing.

## Server Info

- Host: `your-server-ip`
- User: `root`
- SSH: `ssh root@your-server-ip`
- Node: v22 (nvm), pnpm, pm2
- Proxy: `http://127.0.0.1:7890` (for OpenAI)

## Workflow

1. **Identify** which project(s) to deploy from user message
2. **Confirm** with user using AskQuestion tool before executing
3. **Execute** the corresponding command via Shell tool
4. **Report** the result (success or failure with error details)

## Project Registry

### 1. Blog (技术博客)

| Field | Value |
|-------|-------|
| Trigger | 博客, blog, 技术博客 |
| Type | Server deploy (SSH) |
| Server path | /var/www/blog |
| Process | Static (Nginx) |

**Command:**
```bash
ssh root@your-server-ip 'export NVM_DIR="$HOME/.nvm" \
  && [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh" \
  && cd /var/www/blog && bash deploy.sh'

2. AI Review Pipeline

Field	Value
Trigger	ai-review-pipeline, review pipeline
Type	npm publish (local)
Local path	~/projects/ai-review-pipeline

Pre-publish checklist (remind user):

• Update version in package.json
• Commit and push to GitHub first
• After publish: git tag vX.Y.Z && git push --tags

Command:

cd ~/projects/ai-review-pipeline && npm publish

Confirmation Template

Before executing, ALWAYS use AskQuestion to confirm:

Title: "项目部署确认"
Question: "确认要 {action} 吗？"
Options: ["确认执行", "取消"]

Error Handling

• SSH fails: check network / SSH key config
• pnpm build fails: show last 30 lines of output
• npm publish fails: check npm login, 2FA, version conflicts

### 设计要点分析

**1. description 包含所有触发词**

…resume, blog, ai-review-pipeline, ai-commit, ai-i18n, or mentions server update/deployment.

用户说"部署博客"、"发布 ai-review-pipeline"、"更新服务器"都能触发。

**2. 结构化的项目注册表**

每个项目用统一的表格格式：Trigger、Type、Path、Command。AI 可以精确匹配。

**3. 强制确认机制**

Before executing, ALWAYS use AskQuestion to confirm

部署是高风险操作，必须有人工确认步骤。

**4. 错误处理指南**

告诉 AI 遇到不同错误怎么处理，而不是让它自由发挥。

### 使用效果

写好这个 Skill 之后，日常使用就是一句话：

部署博客

AI 会自动：
1. 识别出要部署"Blog"项目
2. 弹出确认对话框
3. 执行 SSH 命令
4. 报告部署结果

整个过程 **零重复说明**。

---

## 实战二：代码规范 Skill

团队里每个人写的代码风格不同，Code Review 的标准也不统一。可以把规范做成 Skill。

```markdown
---
name: code-standards
description: >-
  Enforce team coding standards and review code quality.
  Use when the user asks for code review, style check,
  or mentions coding standards.
---

# Team Code Standards

## Review Checklist

### TypeScript / JavaScript
- 函数不超过 50 行，超过必须拆分
- 禁止 `any`，必须明确类型
- 异步操作必须有 try/catch + 有意义的错误信息
- 组件 props 必须定义 interface

### Git Commit
- 使用 Conventional Commits 格式
- Subject 不超过 72 字符
- Body 说明 why，不只是 what

### API Design
- RESTful 命名，复数名词
- 统一错误响应格式：`{ code, message, data }`
- 分页使用 `page` + `pageSize`

## Review Output Format

对每个问题，标注严重级别：

- **Critical** (必须修复): 逻辑错误、安全漏洞、数据丢失风险
- **Warning** (建议修复): 性能问题、代码异味、缺少错误处理
- **Info** (可选优化): 命名改进、代码简化、注释补充

## Example

Input: 一段有 `any` 类型和空 catch 的代码

Output:

Code Review

Critical

• L15: 使用了 any 类型，应改为 UserResponse
• L23: 空 catch 块，异常被静默吞掉

Warning

• L8-45: 函数超过 50 行，建议拆分 validation 逻辑

Info

• L3: 变量名 d 含义不清，建议改为 userData

---

实战三：PR 管理 Skill

---
name: pr-workflow
description: >-
  Manage pull request workflows including creation, review,
  and merge. Use when user mentions PR, pull request, merge
  request, or code review workflow.
---

# PR Workflow

## Creating a PR

1. Ensure current branch is up to date with remote
2. Run `git diff main...HEAD` to review all changes
3. Generate PR title and body:

### PR Template
```markdown
## Summary
<1-3 bullet points describing the changes>

## Changes
- File-by-file breakdown of significant changes

## Test Plan
- [ ] Unit tests pass
- [ ] Manual testing completed
- [ ] Edge cases considered

4. Create PR: gh pr create --title "..." --body "..."
5. Report PR URL to user

Reviewing a PR

1. Fetch PR info: gh pr view <number>
2. Review diff: gh pr diff <number>
3. Apply team code standards (see code-standards skill)
4. Post review: gh pr review <number> --body "..."

Post-Merge Cleanup

1. Switch to main: git checkout main && git pull
2. Delete local branch: git branch -d <branch>
3. Confirm remote branch deleted

---

## Skill 开发的核心原则

### 原则一：简洁至上

AI 的上下文窗口是共享的——Skill、对话历史、代码上下文都在抢空间。**每个 token 都有成本**。

默认假设：AI 已经很聪明了。只写它不知道的。

```markdown
# ❌ 啰嗦（AI 本来就知道）
SSH (Secure Shell) is a cryptographic network protocol
for operating network services securely over an
unsecured network. To use SSH, you need to...

# ✅ 简洁（只写 AI 不知道的）
## Server Info
- Host: `your-server-ip`
- User: `root`
- Node: v22 (nvm), pnpm, pm2

目标：SKILL.md 控制在 500 行以内。

原则二：渐进式披露

核心流程放 SKILL.md，详细参考放单独文件：

deploy-project/
├── SKILL.md           # 核心：流程 + 项目注册表
├── troubleshooting.md # 详细：各种错误的排查步骤
└── scripts/
    └── health-check.sh # 工具：部署后健康检查

SKILL.md 里引用：

## Troubleshooting
For detailed error resolution, see [troubleshooting.md](troubleshooting.md)

AI 只在需要时才去读详细文件，节省 token。

注意：引用只保持一层深度。不要在 reference.md 里再引用 sub-reference.md。

原则三：设置合适的自由度

根据操作的风险等级，给 AI 不同程度的自由：

自由度	适用场景	示例
高（文字描述）	多种做法都行	Code Review 指南
中（伪代码/模板）	有标准流程但允许变通	PR 模板生成
低（精确脚本）	高风险、需要一致性	数据库迁移、生产部署

部署命令要精确到字符（低自由度）；Review 反馈格式可以灵活（高自由度）。

原则四：安全先行

对于高风险操作，必须有安全机制：

## Safety Rules
- ALWAYS confirm with user before executing destructive operations
- NEVER run commands on production without explicit approval
- NEVER expose API keys, passwords, or tokens in output
- If unsure about any step, ASK rather than proceed

---

个人 Skill vs 项目 Skill

什么放个人目录

~/.cursor/skills/
├── deploy-project/     # 你管理的所有项目的部署
├── git-workflow/        # 你个人的 Git 习惯
└── writing-style/       # 你的技术写作风格

特点：跨项目通用，与个人工作习惯相关。

什么放项目目录

.cursor/skills/
├── api-standards/       # 本项目的 API 设计规范
├── db-migration/        # 本项目的数据库迁移流程
└── deploy-staging/      # 本项目的 staging 部署

特点：项目特有，团队共享，提交到 Git。

团队共享策略

项目 Skill 提交到 Git 后，团队成员 clone 即可使用。建议：

1. 在 README 中说明：告诉新人项目有哪些 Skill

## AI Skills

本项目包含以下 AI Skills（.cursor/skills/）：
- `api-standards`: API 设计规范审查
- `db-migration`: 数据库迁移生成和验证
- `deploy-staging`: Staging 环境部署

2. 版本管理：Skill 的变更也走 PR Review
3. 定期更新：流程变了及时更新 Skill，就像更新文档一样

---

反模式：这些坑要避开

反模式一：大而全的 Skill

# ❌ 一个 Skill 干所有事
---
name: do-everything
description: Handles all project tasks including deploy, test, review, and documentation.
---

# Everything Skill
## Deploy
...（200 行）
## Test
...（150 行）
## Review
...（100 行）
## Docs
...（80 行）

问题：Skill 太大，每次触发都加载全部内容，浪费 token；而且 description 模糊，触发不精准。

正确做法：拆成 deploy、test、code-review、docs 四个独立 Skill。

反模式二：写 AI 本来就知道的

# ❌ 不需要教 AI 什么是 SSH
SSH (Secure Shell) is a protocol that provides a secure
channel over an unsecured network. It uses port 22 by
default and supports password and key-based authentication...

# ✅ 只写你的特定配置
## Server
- Host: your-server-ip, User: root
- Auth: SSH key (no password)

反模式三：时效性信息

# ❌ 会过时
If deploying before August 2025, use the old API endpoint.
After that, use the new one.

# ✅ 只写当前方案，旧方案折叠
## Current Endpoint
Use `https://api.example.com/v2/`

## Deprecated (do not use)
<details>
<summary>Legacy v1 API</summary>
...
</details>

反模式四：没有确认步骤的危险操作

# ❌ 直接执行，没有确认
## Deploy
Run: ssh root@server 'rm -rf /var/www/* && ...'

# ✅ 强制确认
## Deploy
1. Show user the deployment plan
2. **MUST** confirm with AskQuestion before executing
3. Execute only after explicit approval

反模式五：术语不统一

# ❌ 一会儿叫 URL，一会儿叫 endpoint，一会儿叫 route
Call the API URL...
This endpoint returns...
The route accepts...

# ✅ 选定一个术语，全文统一
Call the API endpoint...
This endpoint returns...
The endpoint accepts...

---

Skill 质量检查清单

开发完一个 Skill，对照这个清单过一遍：

核心质量

• description 具体且包含触发词
• description 同时写了 WHAT 和 WHEN
• description 用第三人称
• SKILL.md 不超过 500 行
• 全文术语统一
• 示例具体，不抽象

结构

• 文件引用保持一层深度
• 详细内容用了渐进式披露
• 流程有清晰的步骤编号
• 无时效性信息

安全

• 危险操作有确认步骤
• 不包含硬编码的密钥/密码
• 错误处理有明确指引

维护

• 项目 Skill 已提交到 Git
• README 中列出了可用 Skill
• 有定期 Review 机制

---

举一反三：其他 AI IDE 的类似机制

虽然本文以 Cursor 为例，但 Skill 的思想是通用的：

AI IDE	类似机制	说明
Cursor	Skills + Rules	Markdown 文件，YAML frontmatter
GitHub Copilot	.github/copilot-instructions.md	项目级指令文件
Windsurf	Rules	类似 Cursor Rules
Cline	.clinerules	项目级配置
Aider	.aider.conf.yml	配置文件

核心思路一样：把你的工程知识结构化，让 AI 可以理解和执行。

不管工具怎么换，这种”把隐性知识显性化、让 AI 可执行”的思维方式不会变。

---

总结

Skill 开发的本质是知识工程：

1. 识别团队中重复执行的流程和隐性知识
2. 结构化为 AI 可理解的指令格式
3. 迭代根据实际使用效果持续优化

关键要点：

要点	说明
description 是灵魂	写不好 AI 就找不到、用不了
简洁优于全面	500 行以内，只写 AI 不知道的
安全高于效率	危险操作必须有确认步骤
渐进式披露	核心放 SKILL.md，细节放引用文件
四种模式按需选	Template / Workflow / Conditional / Feedback Loop

做好 Skill 开发，你就在团队里建立了一个”AI 可执行的知识库”。新人入职不用手把手教，AI 会按标准流程执行；老人换岗知识不会断层，Skill 就是最好的交接文档。

---

本系列回顾：

编号	主题	一句话
01	RAG 文件解析	把 PDF/Word/Excel 变成 AI 能理解的文本
02	文档切片策略	固定 / 递归 / 语义三种切片对比
03	大文件上传	分片上传 + 异步处理全链路
04	Embedding 选型	OpenAI / BGE / Jina 怎么选
05	向量数据库选型	Chroma / pgvector / Pinecone / Milvus
06	RAG 检索优化	混合检索 + 重排序 + 多路召回
07	意图识别	关键词 / LLM / Embedding 三级分类
08	结构化输出	让 AI 稳定输出 JSON
09	AI 缓存	精确 + 语义两级缓存
10	Token 管理	上下文窗口和成本控制
11	大模型微调	LoRA 到部署上线
12	Cursor Skill	把工程经验变成 AI 技能（本篇）
13	Harness Engineering	驾驭 AI 的工程效能革命

---

讨论话题：你用 AI IDE 时，有哪些重复操作是可以做成 Skill 的？评论区聊聊你的想法。