李弯湾1. Skills 自定义开发：让 AI 成为你的标准化助手
在团队协作开发中，最让人头疼的莫过于代码风格不统一、重复解释业务逻辑、新人上手成本高这些老问题。传统的解决方案是编写冗长的开发文档，但现实是这些文档往往躺在 Confluence 里积灰。现在，通过 Cursor 的 Skills 机制，我们可以把这些规范直接"教"给 AI，让它成为团队标准的执行者和传播者。
Skills 本质上是一套 Markdown 格式的指令集，就像给 AI 编写的标准化操作手册。当你在项目中定义了 Skills 后，AI 生成的代码会自动符合你预设的规范——无论是代码缩进用 4 个空格还是 2 个空格，接口响应必须包含哪些字段，甚至是异常处理应该记录哪些日志信息。这相当于为团队配备了一位永远遵循规范、不会犯低级错误的超级实习生。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. Skills 核心机制解析
2.1 Skills 的工作原理
Cursor 的 AI 在生成代码时会主动扫描项目中的 .cursor/skills/ 目录，加载所有可用的 Skills。每个 Skill 的核心是一个带有 YAML frontmatter 的 Markdown 文件（必须命名为 SKILL.md），其中包含两个关键元数据：
markdown复制---
name: python-code-style # Skill的唯一标识符
description: 生成符合团队规范的Python代码，当用户要求编写Python代码时使用
---
当用户发起代码生成请求时，AI 会：
- 分析当前任务类型（如"编写Python函数"）
- 匹配 description 符合的 Skills
- 将 Skills 内容作为前置条件注入到生成上下文中
- 输出符合所有 Skills 规范的代码
2.2 项目级 vs 全局 Skills
Skills 支持两种作用域，满足不同场景需求：
| 类型 | 存储路径 | 适用场景 | 示例 |
|---|---|---|---|
| 项目级 | .cursor/skills/ |
项目特定规范 | 电商项目的订单处理流程 |
| 全局 | ~/.cursor/skills/ (Mac/Linux) |
跨项目通用规范 | Python 基础代码风格 |
C:/Users/用户名/.cursor/skills/ (Windows) |
提示：对于企业开发，建议将核心规范设置为全局 Skills，项目特有逻辑使用项目级 Skills。这样新项目创建时就能自动继承基础规范。
2.3 Skill 的触发逻辑
Skill 的触发完全依赖于 description 字段的精准描述。以下是几种典型的 description 写法：
markdown复制# 精确匹配型
description: 当用户要求编写FastAPI路由代码时使用
# 关键词触发型
description: 处理与用户认证相关的任务，包括登录、注册、权限验证
# 文件类型关联型
description: 生成或修改.py文件时应用本规范
经验表明，description 写得越具体，Skill 的触发准确率越高。避免使用模糊表述如"写代码时使用"，这可能导致不必要的规则注入。
3. 构建完整的 Skill 体系
3.1 Skill 的标准目录结构
一个完整的 Skill 目录可以包含多种辅助文件，以下是推荐结构及每个组件的作用：
code复制api-development/ # Skill 名称
├── SKILL.md # 核心规范（必须）
├── reference.md # 详细条款说明书
├── examples.md # 场景化示例集
├── templates/ # 代码模板
│ └── crud_service.py # 可复用的代码骨架
├── scripts/ # 验证脚本
│ └── validate_api.py # 接口规范检查工具
└── assets/ # 资源文件
└── api_flow.png # API 流程图解
3.1.1 SKILL.md 编写规范
作为 Skill 的入口文件，SKILL.md 需要遵循"金字塔原则"——顶部是最重要的摘要信息，底部是扩展阅读指引。典型结构如下：
markdown复制---
name: react-component-style
description: 生成React组件代码，当创建.jsx/.tsx文件时应用
---
# React 组件规范
## 核心原则
- 使用函数组件 + TypeScript
- 禁止使用any类型
- 必须添加JSDoc注释
## 文件结构
- 组件与样式文件同名（Button.tsx + Button.module.css）
- 测试文件与组件同目录（Button.test.tsx）
## Props 规范
- 类型定义必须使用interface
- 可选参数需明确标记optional
- 事件处理器命名以on前缀开头
## 扩展阅读
- 完整类型规范见reference.md
- 典型组件示例见examples.md
- 模板文件在templates/base_component.tsx
3.2 多 Skill 的协同工作
当多个 Skills 同时被激活时，AI 会尝试合并所有规则。此时需要注意：
- 优先级问题：项目级 Skills 会覆盖全局 Skills 的同名规则
- 冲突解决：如果两个 Skills 对同一事项有不同要求，AI 可能产生混淆
- 性能影响：加载过多 Skills 可能影响生成速度
最佳实践是为不同领域创建独立的 Skills，并通过精确的 description 控制触发范围。例如：
code复制.cursor/skills/
├── python-core/ # 基础语法规范
├── django-style/ # Web框架规范
└── pytest-rules/ # 测试专用规范
4. 实战：创建 API 开发 Skill
4.1 初始化 Skill 目录
在项目根目录执行：
bash复制mkdir -p .cursor/skills/fastapi-style
cd .cursor/skills/fastapi-style
touch SKILL.md reference.md examples.md
mkdir templates scripts
4.2 编写核心规范
SKILL.md 内容示例：
markdown复制---
name: fastapi-style
description: 生成符合企业标准的FastAPI代码，当创建API路由或模型时应用
---
# FastAPI 开发规范
## 项目结构
project/
├── app/
│ ├── init.py
│ ├── main.py # 应用入口
│ ├── models/ # Pydantic模型
│ ├── routers/ # 路由模块
│ └── services/ # 业务逻辑
├── tests/ # 单元测试
└── requirements.txt # 依赖声明
code复制
## 路由规范
- 使用APIRouter组织路由
- 路由文件按业务域划分（users.py, products.py）
- 端点命名：create_xxx, get_xxx, update_xxx
## 模型规范
```python
# 请求模型示例
class UserCreateRequest(BaseModel):
name: str = Field(..., min_length=1, example="张三")
email: EmailStr = Field(..., description="用户邮箱")
# 响应模型示例
class UserResponse(BaseModel):
id: UUID
name: str
created_at: datetime
错误处理
- 使用HTTPException返回4xx/5xx
- 错误响应统一格式：
json复制{
"error": {
"code": "invalid_email",
"message": "邮箱格式不正确"
}
}
扩展模板
- 标准CRUD模板：templates/crud_router.py
- 单元测试模板：templates/test_crud.py
code复制
### 4.3 补充详细文档
在 `reference.md` 中定义更详细的规范：
```markdown
# FastAPI 详细规范
## 状态码使用标准
| 场景 | 状态码 |
|---------------------|--------|
| 创建成功 | 201 |
| 参数验证失败 | 422 |
| 权限不足 | 403 |
| 资源不存在 | 404 |
## 分页响应格式
```json
{
"items": [...],
"total": 100,
"page": 1,
"size": 20
}
日志规范
- 请求入口记录INFO日志
- 业务异常记录WARNING
- 系统错误记录ERROR
code复制
### 4.4 添加代码模板
在 `templates/crud_router.py` 中预置标准模板：
```python
from fastapi import APIRouter, Depends, HTTPException
from pydantic import BaseModel, Field
from typing import List, Optional
router = APIRouter(prefix="/{resource}", tags=["{Resource}"])
class {Resource}CreateRequest(BaseModel):
"""创建请求模型"""
pass # 根据实际字段补充
class {Resource}Response(BaseModel):
"""响应模型"""
id: int
# 补充其他字段
@router.post("/", response_model={Resource}Response)
async def create_{resource}(
request: {Resource}CreateRequest
) -> {Resource}Response:
"""创建{resource}"""
raise NotImplementedError
# 其他标准CRUD端点...
5. Skills 高级应用技巧
5.1 动态模板技术
通过 Jinja2 风格的占位符，可以创建更灵活的模板。例如在 templates/model.py.j2 中：
python复制class {{ModelName}}(BaseModel):
"""{{ModelDesc}}"""
{% for field in fields %}
{{field.name}}: {{field.type}} = Field(
{{field.default}},
description="{{field.desc}}"
)
{% endfor %}
使用时配合说明：
markdown复制## 模型生成步骤
1. 复制 templates/model.py.j2 为实际模型文件
2. 替换 {{ModelName}}、{{ModelDesc}}
3. 填充 fields 列表
5.2 自动化验证脚本
在 scripts/validate_api.py 中添加规范检查：
python复制import ast
import sys
from pathlib import Path
def check_fastapi_standards(file_path: Path):
"""检查FastAPI文件是否符合规范"""
with open(file_path) as f:
tree = ast.parse(f.read())
# 检查是否使用了APIRouter
router_used = any(
isinstance(node, ast.ImportFrom)
and node.module == 'fastapi'
and 'APIRouter' in (name.name for name in node.names)
for node in tree.body
)
if not router_used:
print(f"⚠️ {file_path}: 未使用APIRouter组织路由")
return False
return True
if __name__ == "__main__":
exit_code = 0
for path in sys.argv[1:]:
if not check_fastapi_standards(Path(path)):
exit_code = 1
sys.exit(exit_code)
在 SKILL.md 中引用：
markdown复制## 代码检查
提交前运行验证脚本：
```bash
python scripts/validate_api.py app/routers/*.py
5.3 条件化规则注入
通过特殊注释实现更精细的控制：
markdown复制<!-- 当且仅当环境为production时应用 -->
## 生产环境规范
- 必须包含全量类型注解
- 禁用print语句
- 所有端点需要@cache装饰器
<!-- 当文件路径包含test时忽略 -->
## 测试文件例外
- 允许使用魔法mock值
- 简化错误处理
6. 效能提升：Skill 组合策略
6.1 分层技能体系
构建金字塔式的 Skills 结构：
code复制.cursor/
└── skills/
├── 1-python-core/ # 基础层
├── 2-fastapi-style/ # 框架层
├── 3-auth-module/ # 业务模块层
└── 4-project-spec/ # 项目特殊规则
6.2 技能继承机制
通过 @extend 指令复用基础规则：
markdown复制---
name: advanced-fastapi
description: 扩展基础FastAPI规范，添加企业特定规则
---
@extend: fastapi-style # 继承基础规范
## 企业扩展规则
- 所有响应必须包含request_id
- 错误码使用企业标准ENUM
6.3 环境差异化配置
创建环境特定的 Skills：
code复制.cursor/
└── skills/
├── base/ # 基础规范
├── dev/ # 开发环境规则
└── prod/ # 生产环境严格规则
通过启动参数切换：
bash复制cursor --skills-dir=.cursor/skills/prod
7. 常见问题与排查指南
7.1 Skill 未生效排查流程
-
检查文件位置
- 确认在正确的
.cursor/skills/目录 - 确保
SKILL.md文件名全大写
- 确认在正确的
-
验证YAML格式
- frontmatter 必须用
---包裹 - name 只能包含小写字母、数字和连字符
- frontmatter 必须用
-
测试触发条件
python复制# test_skill.py def test_skill_loading(): """验证Skill是否被正确加载""" from cursor.skills import load_skills skills = load_skills() assert "your-skill-name" in skills -
查看调试信息
- 在 Cursor 设置中开启 Debug 模式
- 检查生成代码时加载了哪些 Skills
7.2 性能优化技巧
当 Skills 较多时，可以：
-
按需加载
markdown复制--- name: heavy-skill description: 当处理大型数据文件时使用 lazy: true # 延迟加载 --- -
拆分大文件
- 将示例代码移到
examples.md - 详细说明放在
reference.md
- 将示例代码移到
-
使用缓存
bash复制# 预编译Skills cursor --precompile-skills
7.3 团队协作方案
-
版本控制
- 将
.cursor/skills/纳入git仓库 - 使用子模块管理全局 Skills
- 将
-
变更管理
markdown复制--- name: legacy-support description: 旧系统兼容规范 deprecated: true # 标记弃用 --- -
文档生成
bash复制# 生成Skill文档网站 cursor --generate-skill-docs --output=docs/
8. 效能度量与持续改进
8.1 建立指标系统
在 scripts/metrics.py 中定义质量检查：
python复制def calculate_compliance(code: str, skill: Skill) -> float:
"""计算代码与Skill的符合度"""
total_rules = len(skill.rules)
passed = 0
for rule in skill.rules:
if rule.check(code):
passed += 1
return passed / total_rules
8.2 A/B 测试框架
创建对比分支：
code复制.cursor/
└── skills/
├── current/ # 当前规范
└── experimental/ # 试验性改进
使用脚本评估：
bash复制# 对比两个版本的生成质量
python evaluate.py --skill-a=current --skill-b=experimental
8.3 自动化演进机制
设置定期审查：
markdown复制---
name: auto-review
description: 每月1号触发规范审查
schedule: "0 0 1 * *" # cron表达式
---
## 审查流程
1. 收集过去一个月的生成样本
2. 分析常见偏差模式
3. 自动生成规范更新PR