04-Skills自定义开发

04-Skills 自定义开发Skills 是教 AI 如何完成特定任务的说明书。学会自定义 Skills让 AI 按照你的标准工作。一、Skills 基础概念1.1 什么是 SkillsSkills 是存储在.cursor/skills/目录下的 Markdown 文件用于定义代码规范标准化工作流程复用常用代码模板类比理解:Skills AI 的工作手册 - 代码审查 Skill 告诉 AI 如何审查代码 - API 开发 Skill 告诉 AI 如何写 API - 测试生成 Skill 告诉 AI 如何写测试1.2 Skills 的作用场景效果代码规范统一所有生成的代码都符合团队规范减少重复说明一次定义多次复用提升输出质量AI 按专业标准执行任务降低沟通成本不需要每次都详细说明要求二、Skills 目录结构2.1 位置说明项目级 Skills仅当前项目可用 └── .cursor/skills/ ├── python-style-guide/ │ └── SKILL.md └── api-development/ └── SKILL.md 全局 Skills所有项目可用 └── ~/.cursor/skills/ (Windows: C:/Users/用户名/.cursor/skills/) └── my-global-skill/ └── SKILL.md2.2 文件结构一个 Skill 目录可以是「只有SKILL.md」的最小形态复杂场景下再按需增加附属文件。入口永远是SKILL.mdCursor / Agent 会优先读它其它文件不会自动「一次性全部注入」通常需要你在SKILL.md里写清楚「详见某文件」或对话时用引用。skill-name/ ├── SKILL.md # 必填Skill 入口含 YAML 头 规则摘要 ├── reference.md # 可选长文补充条款、迁移说明、FAQ ├── examples.md # 可选分场景示例与反例 ├── templates/ # 可选可复制的代码骨架.py、.ts、.j2 等 │ └── service.py.j2 ├── scripts/ # 可选辅助脚本校验、生成、格式化说明 │ └── check_style.py ├── assets/ # 可选配图、OpenAPI 片段、小数据样例非代码 │ └── diagram.png └── README.md # 可选给人看的说明模型一般仍以 SKILL.md 为主2.3 各组成部分怎么用细化路径作用建议在 SKILL.md 里怎么写使用方式SKILL.md定义name、description和短而全的核心规则description决定模型何时应用本 Skill。用列表写硬性约束末尾加一节「延伸阅读」指向下方其它文件。对话中技能名或符合description时由模型加载。reference.md规范全文、版本对照表、禁止项清单等篇幅长、不适合作首屏的内容。写一行详细条款见同目录 reference.md。复杂任务时你自己或模型打开该文件也可用reference.md拉进上下文。examples.md按场景组织输入 → 期望输出 → 常见错误适合教 Agent「像团队里这样做」。写完整示例见 examples.md生成 X 类代码前先对照场景 A/B。写类似功能时 该文件减少反复口述。templates/固定结构的占位代码如 CRUD Service、FastAPI 路由壳。可用纯.py或用 Jinja2.j2带占位符。写明新建模块时从 templates/foo.py 复制并替换 {{ModuleName}}。让模型「按模板填空」或你手动复制后再让 AI 改业务逻辑。scripts/本机可执行的小工具如ruff check封装、生成器、检查 SKILL 是否被违反。Skill不会自动代替你执行脚本除非你在对话里明确说「运行 scripts/xxx」。写合并前可运行 scripts/check_style.py 做本地校验需 Python 3.11。终端执行或委托 Agent「在项目根目录执行该脚本并解释输出」。assets/图表、示例 JSON、小型配置片段不适合塞进 SKILL.md 正文。写架构图见 assets/arch.png样例请求体见 assets/sample.json。引用对应文件模型结合图文理解需求。README.md给同事的仓库式说明安装步骤、与 SKILL.md 的关系。可选避免与 SKILL.md 重复长篇规则。主要用于人读模型仍以 SKILL.md 为权威。实践要点不要堆满一个文件SKILL.md控制在「一眼能扫完」的长度细节下沉到reference.md/examples.md。路径写相对、稳定在SKILL.md里用同目录下的 templates/xxx这种描述避免写死你机器的绝对路径。scripts 与 MCP 的区别MCP 是给 AI 的协议化工具scripts/是普通命令行程序由你或 Agent 在终端里跑不会因为有了 Skill 就自动注册成 MCP。引用方式在 Cursor 里对具体文件使用.cursor/skills/skill-name/examples.md或打开后 文件名与「只挂 Skill 名」相比上下文更聚焦。最小目录与完整目录对比# 最小入门 my-skill/ └── SKILL.md # 完整团队规范级 my-skill/ ├── SKILL.md ├── reference.md ├── examples.md ├── templates/ │ └── api_route.py.j2 └── scripts/ └── validate.py三、创建 Skills 实战3.1 步骤1创建目录# 在项目根目录创建mkdir-p.cursor/skills/python-code-style# 或在用户目录创建全局 Skillmkdir-p~/.cursor/skills/python-code-style3.2 步骤2编写 SKILL.md--- name: python-code-style description: 生成符合团队规范的 Python 代码当用户要求编写 Python 代码时使用 --- # Python 代码规范 ## 命名规范 - 类名PascalCase如 UserService - 函数/变量snake_case如 get_user_by_id - 常量UPPER_SNAKE_CASE如 MAX_RETRY_COUNT - 私有成员下划线前缀如 _internal_method ## 代码格式 - 使用 4 空格缩进 - 最大行长度100 字符 - 使用双引号字符串 - 函数间空 2 行 ## 类型注解 - 所有函数参数和返回值必须添加类型注解 - 使用 from __future__ import annotations 支持 Python 3.9 - 复杂类型使用 typing 模块 ## 文档字符串 - 使用 Google Style Docstrings - 包含 Args、Returns、Raises 段落 - 示例代码放在 Examples 段落 ## 错误处理 - 使用自定义异常类 - 异常类名以 Error 结尾 - 日志记录使用 structlog ## 示例 python from __future__ import annotations import structlog from typing import Optional logger structlog.get_logger() class UserNotFoundError(Exception): 用户不存在时抛出 pass class UserService: 用户服务类 def get_user(self, user_id: int) - Optional[User]: 根据ID获取用户信息 Args: user_id: 用户ID Returns: 用户对象不存在时返回 None Raises: UserNotFoundError: 用户不存在时 Examples: service UserService() user service.get_user(1) try: # 实现代码 pass except Exception as e: logger.error(获取用户失败, user_iduser_id, errorstr(e)) raise UserNotFoundError(f用户 {user_id} 不存在) from e### 3.3 步骤3测试 Skill在 Cursor 中打开 Chat输入“写一个用户注册的函数”检查生成的代码是否符合 SKILL.md 中的规范--- ## 四、Skills 编写规范 ### 4.1 Frontmatter 格式 yaml --- name: skill-name # 小写字母、数字、连字符 description: 描述这个 Skill 的作用 # 第三人称说明做什么和何时用 ---命名规则:项目规则示例name小写、连字符分隔、最多 64 字符python-style-guidedescription第三人称、说明触发时机当用户要求编写 Python 代码时使用4.2 内容编写原则原则说明示例精简只写 AI 不知道的信息不写 Python 基础语法具体提供明确的规则和标准“使用 Google Style Docstrings”可执行给出可复制的代码模板提供完整示例代码长度SKILL.md 建议不超过 500 行详细内容放 reference.md4.3 路径格式# ✅ 正确使用正斜杠 模板位置: templates/api_template.py # ❌ 错误使用反斜杠 模板位置: templates\api_template.py五、实战 Skills 示例示例1API 开发 Skill--- name: fastapi-api-dev description: 生成 FastAPI 接口代码当用户开发 Web API 时使用 --- # FastAPI API 开发规范 ## 项目结构project/├── app/│ ├──init.py│ ├── main.py # FastAPI 应用入口│ ├── models/ # Pydantic 模型│ ├── routers/ # API 路由│ └── services/ # 业务逻辑├── tests/└── requirements.txt## 路由规范 - 使用 APIRouter 组织路由 - 路由前缀使用复数名词如 /users - 端点函数名使用动词名词如 create_user ## Pydantic 模型规范 - 请求模型后缀 Request如 UserCreateRequest - 响应模型后缀 Response如 UserResponse - 使用 Field 添加描述和约束 ## 示例代码 python from fastapi import APIRouter, HTTPException from pydantic import BaseModel, Field from typing import List router APIRouter(prefix/users, tags[users]) class UserCreateRequest(BaseModel): name: str Field(..., min_length1, max_length50, description用户名称) email: str Field(..., patternr^[\w\.-][\w\.-]\.\w$, description邮箱地址) class UserResponse(BaseModel): id: int name: str email: str router.post(/, response_modelUserResponse) async def create_user(request: UserCreateRequest) - UserResponse: 创建新用户 # 实现代码 pass router.get(/{user_id}, response_modelUserResponse) async def get_user(user_id: int) - UserResponse: 获取用户信息 # 实现代码 pass### 示例2测试生成 Skill markdown --- name: pytest-test-gen description: 生成 pytest 单元测试当用户要求为代码写测试时使用 --- # Pytest 测试规范 ## 测试文件结构 - 测试文件前缀 test_ - 与被测试文件同名如 user.py → test_user.py - 放在 tests/ 目录下 ## 测试函数规范 - 函数前缀 test_ - 函数名描述测试场景如 test_create_user_with_valid_data - 使用 Arrange-Act-Assert 结构 ## Fixture 使用 - 数据库连接使用 fixture - Mock 外部依赖 - 每个测试独立不依赖执行顺序 ## 示例 python import pytest from unittest.mock import Mock, patch from app.services.user import UserService pytest.fixture def user_service(): return UserService() pytest.fixture def mock_db(): return Mock() def test_create_user_with_valid_data(user_service, mock_db): 测试使用有效数据创建用户 # Arrange user_data {name: 张三, email: zhangsanexample.com} mock_db.add.return_value None # Act with patch(app.services.user.get_db, return_valuemock_db): result user_service.create_user(user_data) # Assert assert result.name 张三 assert result.email zhangsanexample.com mock_db.add.assert_called_once() mock_db.commit.assert_called_once() pytest.mark.parametrize(invalid_email, [ invalid, example.com, user, , ]) def test_create_user_with_invalid_email(user_service, invalid_email): 测试使用无效邮箱创建用户应抛出异常 # Arrange user_data {name: 张三, email: invalid_email} # Act Assert with pytest.raises(ValueError, matchInvalid email format): user_service.create_user(user_data)--- ## 六、Skills 高级用法 ### 6.1 使用 templates 目录my-skill/├── SKILL.md└── templates/├── api_template.py└── model_template.py在 SKILL.md 中引用: markdown ## 模板文件 - API 模板: templates/api_template.py - 模型模板: templates/model_template.py6.2 组合多个 Skills多个 Skills 可以同时生效AI 会综合所有 Skill 的要求。.cursor/skills/ ├── python-code-style/ # 基础代码规范 ├── fastapi-api-dev/ # API 开发规范 └── pytest-test-gen/ # 测试规范6.3 条件触发 Skills使用 description 控制触发时机:---name:data-processing# 只在处理数据相关任务时触发description:数据处理和分析当用户要求处理 CSV/Excel/JSON 数据时使用---七、常见问题Q1: Skill 没有生效检查项:目录位置是否正确.cursor/skills/SKILL.md 文件名是否正确必须大写YAML frontmatter 格式是否正确description 是否清晰明确调试方法:1. 检查 Cursor 是否加载了 SkillChat 中会显示使用的 Skills 2. 简化 SKILL.md 内容逐步测试 3. 重启 Cursor 编辑器Q2: 多个 Skills 冲突解决:检查 Skills 是否有矛盾的规则使用更具体的 description 限制触发范围合并相似的 SkillsQ3: Skill 内容太长建议:核心规则放在 SKILL.md详细说明放在 reference.md示例代码放在 examples.md八、下一步学习完成本指南后建议学习05-SubAgent并行任务.md - 多代理并行处理08-实战Python数据分析工具.md - Skills 实战应用