Cursor Skills 深度解析：从定义到实践

一、Skills 的本质与核心价值

Skills 是 AI 编辑器的可复用能力单元，它将人类专家的经验、团队的最佳实践、标准化的操作流程封装成结构化的指令集，使 AI 能够像人类专家一样思考和行动。这种能力封装的核心价值在于将隐性知识显性化、将个人经验团队化、将临时操作流程化。

1.1 Skills 的演进路径

从简单的规则到复杂的技能系统，Skills 经历了三个阶段的演进：

阶段	代表形式	特点	局限性
规则阶段	动态规则、自动补全	基于文本匹配，简单直接	难以表达复杂逻辑，维护成本高
命令阶段	斜杠命令（/command）	显式调用，功能明确	需要用户记忆命令，学习曲线陡峭
技能阶段	结构化 Skill 文件	自然语言描述，上下文感知	需要标准化定义，但功能最强大

1.2 Skills 的核心优势

• 上下文感知：AI 能根据当前对话内容自动判断是否应用相关 Skill
• 知识沉淀：将团队最佳实践固化为可复用的 Skill
• 降低门槛：新人无需记忆复杂命令，AI 自动提供指导
• 版本可控：通过 Git 管理 Skill 的演进历史

二、Skills 的完整定义体系

2.1 Skill 文件结构规范

一个完整的 Skill 由以下部分组成：

my-skill/
├── SKILL.md          # 核心定义文件
├── scripts/          # 可执行脚本（可选）
│   ├── deploy.sh
│   └── validate.py
├── references/       # 参考资料（可选）
│   └── REFERENCE.md
└── assets/           # 静态资源（可选）
    └── config-template.json

2.2 SKILL.md 的 YAML Frontmatter

Frontmatter 是 Skill 的元数据层，必须包含以下字段：

---
name: my-skill
description: 简要描述此技能的功能及使用时机。
license: MIT
compatibility: requires-node-18
metadata:
  category: development
  tags: ["deployment", "ci-cd"]
disable-model-invocation: false
---

关键字段详解：

• name：唯一标识符，必须与文件夹名称一致，仅限小写字母、数字和连字符
• description：技能的功能描述，用于 AI 判断相关性
• license：许可证信息，确保合规使用
• compatibility：运行环境要求，如 Node.js 版本、系统依赖等
• metadata：自定义元数据，用于分类、搜索、过滤
• disable-model-invocation：控制是否自动调用

2.3 Skill 内容结构

Frontmatter 之后的内容是 Skill 的核心指令，建议采用以下结构：

# 技能名称

为 Agent 提供的详细指令。

## 使用时机
- 在以下情况使用此技能：
  - 当用户询问关于部署的问题时
  - 当代码需要部署到生产环境时
  - 当需要验证部署配置时

## 指令
1. 首先检查当前分支是否为 develop 或 main
2. 运行测试套件确保代码质量
3. 使用以下命令部署到目标环境：
   ```bash
   ./scripts/deploy.sh staging

4. 验证部署结果并报告状态

注意事项

• 生产环境部署需要审批流程
• 部署前必须通过所有测试
• 回滚脚本位于 scripts/rollback.sh

## 三、Skills 的加载与作用域

### 3.1 加载优先级体系

Skills 的加载遵循严格的作用域优先级，确保最具体的规则优先应用：

| 作用域 | 路径示例 | 优先级 | 说明 |
|--------|----------|--------|------|
| **项目级** | `.agents/skills/` | 最高 | 项目特定 Skill，覆盖所有用户 |
| **项目级** | `.cursor/skills/` | 高 | Cursor 项目特定 Skill |
| **用户级** | `~/.agents/skills/` | 中 | 用户全局 Skill，跨项目共享 |
| **用户级** | `~/.cursor/skills/` | 低 | Cursor 用户全局 Skill |
| **兼容层** | `.claude/skills/` | 兼容 | 兼容 Claude 生态 |
| **兼容层** | `.codex/skills/` | 兼容 | 兼容 Codex 生态 |

**优先级冲突处理**：当多个 Skill 名称相同时，优先级高的 Skill 会覆盖优先级低的。这种设计确保了项目特定配置可以覆盖用户全局配置，而用户全局配置可以覆盖编辑器默认配置。

### 3.2 多编辑器兼容策略

Cursor 通过兼容层支持多编辑器生态：

```javascript
// 兼容层映射逻辑
const compatibilityMap = {
  'claude': {
    source: '.claude/skills/',
    target: '.cursor/skills/',
    transform: (skill) => {
      // 转换 Claude 特定格式为 Cursor 格式
      return transformClaudeToCursor(skill);
    }
  },
  'codex': {
    source: '.codex/skills/',
    target: '.cursor/skills/',
    transform: (skill) => {
      // 转换 Codex 特定格式为 Cursor 格式
      return transformCodexToCursor(skill);
    }
  }
};

这种设计使得 Skill 可以在不同编辑器间迁移，降低了生态切换成本。

四、Skills 的实践应用

4.1 禁用自动调用模式

某些 Skill 需要显式调用，这时需要设置 disable-model-invocation: true。这种模式特别适合：

• 敏感操作：如删除数据库、修改生产配置
• 复杂流程：需要用户确认的多步骤操作
• 实验性功能：尚未稳定的新能力

---
name: database-migration
description: 执行数据库迁移脚本
disable-model-invocation: true
---
# Database Migration

此技能用于执行数据库迁移操作。

## 使用方式
在聊天中输入 `/database-migration` 来触发此技能。

## 操作步骤
1. 确认当前环境
2. 备份数据库
3. 执行迁移脚本
4. 验证迁移结果

4.2 脚本集成模式

Skills 可以集成可执行脚本，实现自动化操作。脚本应遵循以下原则：

• 自包含：不依赖外部环境变量
• 错误处理：提供清晰的错误信息和退出码
• 可配置：支持参数化配置

---
name: deploy-app
description: 部署应用到目标环境
---
# Deploy App

## 使用方式
运行部署脚本：`scripts/deploy.sh <environment>`

## 部署流程
1. 环境检查
2. 构建应用
3. 部署到目标环境
4. 健康检查

## 预部署验证
在部署前，运行验证脚本：
```bash
python scripts/validate.py --env staging

### 4.3 参考资料管理

将详细参考资料分离到单独文件，避免 SKILL.md 过于冗长：

my-skill/
├── SKILL.md # 简洁的核心指令
├── references/
│ ├── REFERENCE.md # 详细参考资料
│ ├── API_DOCS.md # API 文档
│ └── BEST_PRACTICES.md # 最佳实践
└── assets/
└── config-template.json # 配置模板

这种分离策略符合**关注点分离**原则，使 Skill 保持简洁，同时提供完整的知识支持。

## 五、Skills 的迁移与演进

### 5.1 从规则迁移到 Skills

Cursor 内置了 `/migrate-to-skills` 技能，帮助将现有规则转换为 Skills。迁移过程分为两个阶段：

**第一阶段：识别可迁移的规则**

```javascript
// 迁移逻辑示例
function migrateRules(rules) {
  return rules.filter(rule => {
    // 1. 排除 alwaysApply: true 的规则（有显式触发条件）
    if (rule.alwaysApply === true) return false;
    
    // 2. 排除有特定 globs 模式的规则（触发条件复杂）
    if (rule.globs && rule.globs.length > 0) return false;
    
    // 3. 排除用户规则（不存储在文件系统）
    if (rule.source === 'user') return false;
    
    // 4. 保留需要迁移的规则
    return true;
  });
}

第二阶段：转换规则为 Skills

function convertToSkill(rule) {
  return {
    name: rule.name || generateSkillName(rule),
    description: rule.description || '从规则迁移而来',
    content: generateSkillContent(rule),
    disableModelInvocation: rule.type === 'slash-command' // 斜杠命令转为显式调用
  };
}

5.2 迁移策略对比

规则类型	是否迁移	原因
Dynamic Rules (alwaysApply: false)	✅ 迁移	无显式触发条件，适合 Skill 的上下文感知
Slash Commands	✅ 迁移	显式调用，转为 disable-model-invocation: true
Always Apply Rules	❌ 不迁移	有显式触发条件，与 Skill 行为不同
Glob 模式规则	❌ 不迁移	触发条件复杂，难以用 Skill 表达
用户规则	❌ 不迁移	不存储在文件系统，无法持久化

六、Skills 的团队协作实践

6.1 团队 Skill 管理策略

在团队环境中，Skills 的管理需要遵循以下原则：

1. 版本控制：所有 Skill 纳入 Git 管理
2. 命名规范：统一的命名约定
3. 文档完善：每个 Skill 都有完整的文档
4. 测试验证：确保 Skill 按预期工作

6.2 团队 Skill 共享方案

# .cursor/rules 或团队 Skill 配置
team-skills:
  - name: code-review
    source: git@github.com:team/code-review-skills.git
    path: skills/
    version: v1.2.0
    auto-update: true
    
  - name: deployment
    source: git@github.com:team/deployment-skills.git
    path: skills/
    version: main
    auto-update: false

6.3 Skill 的版本锁定

通过 joySkills.lock 文件锁定 Skill 版本：

# joySkills.lock
skills:
  - name: code-review
    version: v1.2.0
    commit: a1b2c3d4e5f678901234567890abcdef12345678
    source: git@github.com:team/code-review-skills.git

这种锁定机制确保团队所有成员使用完全相同的 Skill 版本，避免因 Skill 更新导致的协作问题。

七、React 开发单页面 H5 的 Skill 实践案例

7.1 Skill 设计目标

创建一个名为 react-h5-boilerplate 的 Skill，帮助开发者快速创建 React H5 单页面应用。该 Skill 应包含：

• 项目初始化
• 基础组件库集成
• 路由配置
• 状态管理
• API 调用封装
• 构建部署流程

7.2 Skill 实现

---
name: react-h5-boilerplate
description: 快速创建 React H5 单页面应用，包含路由、状态管理和 API 调用
license: MIT
metadata:
  category: frontend
  tags: ["react", "h5", "typescript", "vite"]
---
# React H5 Boilerplate

此技能用于快速初始化 React H5 单页面应用，提供现代化的开发体验。

## 使用时机
- 开始新的 React H5 项目时
- 需要标准化的项目结构时
- 需要集成 TypeScript 和现代工具链时

## 初始化项目

### 1. 创建项目结构
```bash
# 使用 Vite 创建 React + TypeScript 项目
npm create vite@latest my-app -- --template react-ts

# 进入项目目录
cd my-app

# 安装依赖
npm install

# 安装常用依赖
npm install react-router-dom axios
npm install -D @types/react @types/react-dom

2. 项目结构说明

my-app/
├── src/
│   ├── components/     # 可复用组件
│   ├── pages/         # 页面组件
│   ├── hooks/         # 自定义 Hooks
│   ├── services/      # API 服务层
│   ├── store/         # 状态管理
│   ├── utils/         # 工具函数
│   └── styles/        # 样式文件
├── public/            # 静态资源
├── index.html         # HTML 模板
└── package.json       # 项目配置

3. 路由配置

// src/router/index.tsx
import { createBrowserRouter } from 'react-router-dom';
import HomePage from '../pages/Home';
import AboutPage from '../pages/About';

const router = createBrowserRouter([
  {
    path: '/',
    element: <HomePage />,
  },
  {
    path: '/about',
    element: <AboutPage />,
  },
]);

export default router;

4. 状态管理（使用 Zustand）

// src/store/counterStore.ts
import { create } from 'zustand';

interface CounterState {
  count: number;
  increment: () => void;
  decrement: () => void;
}

export const useCounterStore = create<CounterState>((set) => ({
  count: 0,
  increment: () => set((state) => ({ count: state.count + 1 })),
  decrement: () => set((state) => ({ count: state.count - 1 })),
}));

5. API 调用封装

// src/services/api.ts
import axios from 'axios';

const api = axios.create({
  baseURL: process.env.REACT_APP_API_URL || 'https://api.example.com',
  timeout: 10000,
  headers: {
    'Content-Type': 'application/json',
  },
});

// 请求拦截器
api.interceptors.request.use(
  (config) => {
    const token = localStorage.getItem('token');
    if (token) {
      config.headers.Authorization = `Bearer ${token}`;
    }
    return config;
  },
  (error) => Promise.reject(error)
);

// 响应拦截器
api.interceptors.response.use(
  (response) => response.data,
  (error) => {
    console.error('API Error:', error);
    return Promise.reject(error);
  }
);

export default api;

6. 组件示例

// src/components/Button/index.tsx
import React from 'react';
import './Button.css';

interface ButtonProps {
  children: React.ReactNode;
  onClick?: () => void;
  variant?: 'primary' | 'secondary' | 'danger';
  disabled?: boolean;
}

const Button: React.FC<ButtonProps> = ({
  children,
  onClick,
  variant = 'primary',
  disabled = false,
}) => {
  return (
    <button
      className={`btn btn-${variant} ${disabled ? 'disabled' : ''}`}
      onClick={onClick}
      disabled={disabled}
    >
      {children}
    </button>
  );
};

export default Button;

7. 构建与部署

# 开发环境
npm run dev

# 构建生产版本
npm run build

# 预览生产版本
npm run preview

# 部署到服务器
# 使用 scripts/deploy.sh 脚本
./scripts/deploy.sh staging

八、Skills 的测试与验证

8.1 Skill 测试策略

每个 Skill 应包含测试用例，确保其正确性：

# 在 SKILL.md 中添加测试部分
## 测试用例

### 测试 1: 项目初始化
**场景**: 用户要求创建新的 React H5 项目
**预期**: Skill 提供完整的初始化命令和项目结构说明
**验证**: 运行 `npm create vite@latest` 并检查项目结构

### 测试 2: 路由配置
**场景**: 用户需要添加新页面
**预期**: Skill 提供路由配置示例
**验证**: 检查路由配置是否正确

### 测试 3: API 调用
**场景**: 用户需要调用 API
**预期**: Skill 提供 API 封装示例
**验证**: 检查 API 调用是否正常工作

8.2 自动化测试脚本

// test/skill-test.js
const { execSync } = require('child_process');
const fs = require('fs');

describe('react-h5-boilerplate skill', () => {
  test('should provide correct initialization commands', () => {
    const skillContent = fs.readFileSync('skills/react-h5-boilerplate/SKILL.md', 'utf8');
    expect(skillContent).toContain('npm create vite@latest');
    expect(skillContent).toContain('react-ts');
  });

  test('should have proper project structure', () => {
    const skillContent = fs.readFileSync('skills/react-h5-boilerplate/SKILL.md', 'utf8');
    expect(skillContent).toContain('src/');
    expect(skillContent).toContain('components/');
    expect(skillContent).toContain('pages/');
  });
});

九、Skills 的演进与维护

9.1 Skill 版本管理

随着技术栈的演进，Skill 需要定期更新：

1. 定期审查：每季度审查一次 Skill 的有效性
2. 版本发布：使用语义化版本控制
3. 向后兼容：确保旧版本仍能工作
4. 弃用通知：提前通知用户弃用计划

9.2 技能库管理工具

使用 joyskills-cli 管理团队 Skill 库：

# 添加 Skill 到团队库
joyskills add skills/react-h5-boilerplate

# 发布新版本
joyskills publish v1.2.0

# 查看更新
joyskills update

# 锁定版本
joyskills install team://skills/react-h5-boilerplate@v1.2.0

十、总结与最佳实践

10.1 Skills 设计原则

1. 单一职责：每个 Skill 只解决一个具体问题
2. 明确边界：清晰定义使用时机和限制
3. 易于理解：使用自然语言，避免技术黑话
4. 可测试：包含测试用例，确保可靠性
5. 可维护：结构清晰，便于后续修改

10.2 团队协作建议

1. 建立 Skill 目录：按功能分类管理 Skill
2. 制定命名规范：统一命名约定
3. 文档化流程：记录 Skill 的使用场景和效果
4. 定期评审：确保 Skill 的质量和相关性
5. 版本控制：所有变更通过 Git 管理

一、Cursor Skills 核心认知：脱离基础配置的本质理解

1.1 Skills 不是配置文件，是 AI 代理的「专业手册」

很多开发者会将 Cursor Skills 简单等同于编辑器的自定义规则或快捷命令，这是对功能的核心误解。从本质上来说，Skills 是写给 Cursor AI 代理的标准化业务/开发指南。

传统的 AI 代码助手只能基于通用编程知识提供支持，无法理解特定项目的技术栈规范、业务逻辑、团队约定；而 Skills 相当于为 AI 代理定制了「专属知识库」，当开发者在项目中编写代码时，AI 会自动读取匹配的 Skills 内容，按照预设的规范、指令、逻辑完成开发工作，彻底解决「AI 生成代码不符合项目规范」「不理解业务需求」「重复沟通成本高」的痛点。

Skills 的核心价值体现在三点：标准化开发流程、私有化业务适配、自动化效率提升。它不依赖开发者手动触发，AI 会根据项目上下文自动匹配并应用；也可以通过显式命令调用，满足定制化需求。

1.2 Skills 的核心工作机制：自动匹配与显式调用

Cursor Skills 有两种核心工作模式，这是实践中必须掌握的核心逻辑，决定了技能的使用方式和适用场景：

1. 自动匹配模式（默认）
   无需开发者任何操作，Cursor AI 会实时分析当前的代码上下文、文件类型、开发需求、关键词，自动检索项目级、用户级的所有 Skills，判断技能与当前场景的相关性，一旦匹配成功，立即将技能中的指令、规范、逻辑注入 AI 思考过程，生成符合要求的代码或解决方案。
   例如：开发 React 项目时，AI 自动匹配「React 开发规范技能」，生成的代码自动遵循项目的组件命名、hooks 使用、样式规范。

2. 显式调用模式（禁用自动调用）
   通过在技能配置中设置 disable-model-invocation: true，关闭 AI 自动匹配能力，技能仅能通过 /技能名称 的斜杠命令手动触发。这种模式适用于特定的工具型、流程型技能，例如「项目打包部署」「接口文档生成」「代码格式化校验」等非高频、需主动触发的功能。

两种模式互补，覆盖了日常开发中「高频通用规范」和「低频专用工具」的全场景需求，这也是 Cursor Skills 灵活性的核心体现。

1.3 Skills 的文件结构核心价值：模块化与轻量化

Cursor Skills 规定的文件夹结构（SKILL.md + scripts/ + references/ + assets/）并非强制的格式约束，而是为了实现模块化管理和轻量化调用：

• SKILL.md：核心指令文件，存储 AI 必须读取的核心规范、使用时机、执行步骤，要求简洁明了，保证 AI 快速加载核心信息；
• scripts/：可执行脚本目录，存放自动化脚本（Shell、Python、JS 等），AI 可直接调用脚本完成自动化操作，脱离纯文本指令的限制；
• references/：扩展参考文档目录，存放详细的技术文档、业务说明、接口定义等，AI 仅在需要时加载，避免核心文件臃肿；
• assets/：静态资源目录，存放模板文件、配置文件、图片等，用于代码生成、项目初始化等场景。

这种结构的核心设计理念是**「核心信息优先，扩展信息按需加载」**，保证 AI 在处理开发需求时，不会被冗余信息干扰，同时满足复杂项目的扩展需求。这也是实践中组织 Skills 的核心原则：核心指令精简，扩展内容分离。

1.4 Skills 的层级优先级：项目级 > 用户级，兼容优先

Cursor 支持项目级（.agents/skills/、.cursor/skills/）和用户级（_{/.agents/skills/、}/.cursor/skills/）技能，同时兼容 Claude、Codex 的技能目录，这一设计的实践意义在于**「全局通用 + 项目定制」的分层管理**：

• 用户级技能：存放全局通用的技能，例如「通用前端开发规范」「Git 提交规范」「Python 基础语法规范」，适用于所有本地项目，一次编写，全局生效；
• 项目级技能：存放当前项目专属的技能，例如「XX 产品 React 业务规范」「XX 项目部署流程」，仅对当前项目生效，优先级高于用户级技能，避免全局规范与项目定制规范冲突。

实践中，无需关心目录的兼容性差异，只需遵循「通用技能放用户级，项目专属技能放项目级」的原则，Cursor 会自动识别并加载所有合法目录下的技能，无需手动配置路径。

二、Cursor Skills 实践核心：编写规范与高阶用法

2.1 技能编写的核心原则：可执行、可理解、可复用

Cursor Skills 的效果完全取决于编写质量，脱离实践的技能无法发挥价值。在编写技能时，必须遵循三大核心原则：

1. 可执行：技能中的指令必须是 AI 能够直接执行的具体操作，而非抽象描述。例如不要写「优化 React 代码」，而要写「React 组件必须使用函数式组件 + Hooks，禁止使用类组件；组件命名采用大驼峰，hooks 命名采用小驼峰」；
2. 可理解：语言简洁直白，符合 AI 的理解逻辑，避免使用行业黑话、模糊词汇，分点罗列指令，让 AI 快速抓取核心信息；
3. 可复用：技能模块化设计，一个技能对应一个核心功能，避免大而全的技能文件。例如拆分「React 组件规范」「React 样式规范」「React 接口请求规范」三个技能，而非合并为一个。

2.2 核心配置项的实践用法（非基础介绍，聚焦使用场景）

（1）name 与 description：AI 匹配的核心关键词

name 是技能的唯一标识，description 是 AI 判断技能相关性的核心依据。实践中，description 必须包含场景关键词和功能关键词，这是 AI 自动匹配的关键。
例如：编写 React H5 开发技能时，description 不能写「React 开发」，而要写「用于 React 单页面 H5 项目开发，包含移动端适配、组件规范、hooks 使用、样式开发等指令，适用于移动端 H5 页面开发场景」。

（2）disable-model-invocation：模式切换的核心配置

该配置是区分技能类型的关键：

• 标准开发规范类技能（如代码规范、业务逻辑规范）：不配置该字段，使用自动匹配模式，AI 全程遵循规范开发；
• 工具流程类技能（如项目初始化、打包部署、代码校验）：配置为 true，仅手动调用执行，避免 AI 无意义自动触发。

（3）compatibility 与 metadata：扩展信息的实践用法

compatibility 用于声明技能的运行环境依赖，例如「React 18+、Vite 5.0+、移动端 Chrome 内核」，AI 会根据环境判断是否适用技能；metadata 用于存放自定义元数据，例如团队名称、版本号、更新时间，用于技能管理和共享。

2.3 脚本集成：Skills 的自动化能力升级

scripts/ 目录是 Cursor Skills 从「文本指令」升级为「自动化工具」的核心，实践中可集成任意可执行脚本，实现 AI 驱动的自动化操作：

1. 前端项目常用脚本：
   • JS/TS 脚本：项目初始化、依赖安装、代码格式化、接口生成；
   • Shell 脚本：项目打包、部署、本地服务启动；
2. AI 调用脚本的规则：
   在 SKILL.md 中使用相对路径引用脚本，明确脚本的执行参数、执行时机、预期结果。例如：执行 scripts/init-react-h5.js 命令，自动初始化 React H5 项目基础结构。
3. 脚本实践要求：
   脚本必须自包含，无需外部依赖；具备完善的错误提示，执行失败时 AI 可根据提示反馈给开发者；边界情况处理完善，适配不同的项目环境。

2.4 技能共享与迁移：团队协作的核心实践

Cursor Skills 支持从 GitHub 安装远程技能，同时支持内置的 /migrate-to-skills 命令迁移旧版规则，这是团队协作中统一开发规范的核心手段：

1. 团队共享技能：将团队统一的开发规范、业务技能上传至 GitHub，团队成员通过远程规则安装，实现全团队 AI 开发规范统一，彻底解决多人开发代码风格不一致的问题；
2. 规则迁移：旧版 Cursor 的动态规则、斜杠命令可一键迁移为 Skills，其中智能规则迁移为自动匹配技能，斜杠命令迁移为显式调用技能，保证历史配置无缝升级，无需重新编写。

三、Cursor Skills 实战：开发极简 React 单页面 H5 应用

本章节通过从零开发一个 React 单页面 H5 首页的完整流程，实战演示 Cursor Skills 的编写、调用、自动匹配、脚本集成全流程。该 H5 页面包含：移动端适配、顶部导航栏、轮播图、功能菜单、底部版权栏，是最典型的移动端单页面应用。

3.1 实战准备：项目环境与技能目录创建

1. 创建 React + Vite 项目（基础环境，无需手动编写代码，后续由 AI 基于 Skills 生成）：
   我们仅需创建空项目，核心工作是编写定制化 Skills，让 AI 按照我们的规范完成开发。
2. 创建项目级 Skills 目录：
   在项目根目录创建 .cursor/skills/ 文件夹，作为本次实战的技能目录，我们将编写两个核心技能：
   • react-h5-dev：React H5 开发规范技能（自动匹配模式）；
   • init-h5-project：H5 项目初始化技能（显式调用模式，含自动化脚本）。

3.2 实战技能1：react-h5-dev —— React H5 开发规范自动匹配技能

该技能是核心规范技能，AI 会在开发 React H5 代码时自动匹配，严格遵循规范生成代码，无需手动触发。

3.2.1 技能文件结构

.cursor/
└── skills/
    └── react-h5-dev/
        └── SKILL.md

3.2.2 SKILL.md 完整内容（实践级指令，非基础格式）

---
name: react-h5-dev
description: 适用于 React 18 + Vite 单页面 H5 项目开发，包含移动端适配规范、函数式组件/Hooks 规范、CSS 样式规范、组件结构规范，AI 生成代码时自动遵循该技能
compatibility: React 18+, Vite 5.0+, 移动端浏览器适配
metadata:
  version: 1.0.0
  team: frontend-group
---
# React H5 开发核心规范
## 一、技术栈约束
1. 必须使用 React 18 函数式组件 + Hooks，禁止使用类组件；
2. 样式使用原生 CSS + CSS 变量，适配移动端 rem 布局；
3. 路由使用 react-router-dom 最新版本，仅单页面无需多路由；
4. 禁止使用第三方 UI 库，纯手写原生组件保证轻量化。

## 二、移动端适配规范
1. 基准字号设置为 375px 设计稿下 16px，使用 rem 单位：1rem = 16px；
2. 媒体查询适配 320px - 480px 移动端屏幕；
3. 禁止固定像素宽度，所有尺寸使用相对单位；
4. 触摸区域最小尺寸 44px，保证移动端交互体验。

## 三、组件开发规范
1. 组件命名：大驼峰命名法，例如 Home、NavHeader；
2. Hooks 命名：小驼峰命名法，必须以 use 开头，例如 useSwiper、useWindowSize；
3. 组件结构：导入依赖 → 定义组件 → 导出组件，逻辑与 UI 分离；
4. 状态管理：仅使用 useState/useEffect，禁止复杂状态库。

## 四、样式开发规范
1. 全局样式重置：清除默认边距、盒模型设置为 border-box；
2. CSS 变量统一管理主题色、字体、间距；
3. 样式类名：短横线命名法，例如 nav-header、swiper-container；
4. 禁止嵌套过深的样式，保持样式扁平化。

## 五、H5 页面结构要求
单页面必须包含：顶部导航栏、轮播图区域、功能菜单区域、底部版权栏，布局居中，适配所有移动端设备。

3.2.3 技能实践效果

当我们在项目中编写 Home.jsx 文件时，Cursor AI 会自动读取该技能，生成的代码会完全遵循：函数式组件、Hooks、rem 适配、原生 CSS、标准页面结构等所有规范，无需我们手动提醒 AI 遵循规则。

3.3 实战技能2：init-h5-project —— H5 项目初始化显式调用技能

该技能是工具型技能，关闭自动调用，仅通过 /init-h5-project 命令触发，AI 会调用内置脚本，自动初始化项目依赖、配置文件、全局样式，实现一键初始化。

3.3.1 技能文件结构（集成 scripts 脚本）

.cursor/
└── skills/
    └── init-h5-project/
        ├── SKILL.md
        └── scripts/
            └── init.js

3.3.2 SKILL.md 完整内容

---
name: init-h5-project
description: 一键初始化 React H5 项目，安装依赖、配置移动端适配、创建全局样式文件
disable-model-invocation: true
compatibility: Node.js 16+, React 18+
---
# H5 项目初始化技能
## 使用方式
在 Cursor 聊天框输入 `/init-h5-project` 触发技能，AI 自动执行初始化流程。

## 执行步骤
1. 自动执行 scripts/init.js 脚本，安装项目依赖：react-router-dom、axios；
2. 自动创建全局样式文件 src/index.css，写入移动端适配样式；
3. 自动创建项目基础目录：components/、pages/、assets/；
4. 自动修改 main.jsx 引入全局样式。

## 约束说明
仅用于项目初始化，执行完成后提示「初始化成功」，无需重复执行。

3.3.3 scripts/init.js 自动化脚本（可直接执行）

该脚本用于自动安装依赖、创建项目目录，AI 可直接调用执行：

const fs = require('fs');
const { execSync } = require('child_process');

// 1. 安装项目依赖
console.log('正在安装依赖...');
execSync('npm install react-router-dom axios', { stdio: 'inherit' });

// 2. 创建项目基础目录
const dirs = ['src/components', 'src/pages', 'src/assets'];
dirs.forEach(dir => {
  if (!fs.existsSync(dir)) {
    fs.mkdirSync(dir, { recursive: true });
  }
});

// 3. 生成全局适配样式
const cssContent = `/* 全局样式重置 + 移动端适配 */
* {
  margin: 0;
  padding: 0;
  box-sizing: border-box;
}
html {
  font-size: 16px;
}
@media (max-width: 375px) {
  html {
    font-size: 14px;
  }
}
@media (min-width: 480px) {
  html {
    font-size: 18px;
  }
}
body {
  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
  line-height: 1.5;
  color: #333;
  background-color: #f5f5f5;
}
/* 主题变量 */
:root {
  --primary-color: #409eff;
  --text-color: #333;
  --bg-color: #fff;
}
`;
fs.writeFileSync('src/index.css', cssContent);

console.log('项目初始化脚本执行完成！');

3.3.4 技能实践效果

在 Cursor 聊天框输入 /init-h5-project，AI 立即调用该技能，执行 init.js 脚本，一键完成依赖安装、目录创建、全局样式配置，无需手动操作任何配置文件。

3.4 实战核心流程：AI 基于 Skills 开发 React H5 页面

完成两个技能的编写后，我们无需手动编写一行代码，仅通过自然语言指令，让 Cursor AI 基于定制化 Skills 完成整个 H5 页面开发：

3.4.1 第一步：显式调用初始化技能

在 Cursor 聊天框输入：/init-h5-project
AI 执行结果：自动安装依赖、创建目录、生成全局样式，反馈「项目初始化成功」。

3.4.2 第二步：自动匹配规范技能，生成首页组件

在聊天框输入自然语言需求：生成 React H5 单页面首页，包含顶部导航、轮播图、4个功能菜单、底部版权栏
此时 Cursor AI 自动匹配 react-h5-dev 技能，严格遵循我们预设的规范生成代码：

AI 生成的 src/pages/Home.jsx 代码（完全遵循技能规范）

import { useState, useEffect } from 'react';
import '../index.css';

// 函数式组件，遵循 Hooks 规范
const Home = () => {
  // 轮播图状态
  const [currentSwiper, setCurrentSwiper] = useState(0);
  const swiperList = [
    { id: 1, img: 'https://picsum.photos/375/180' },
    { id: 2, img: 'https://picsum.photos/375/180' },
    { id: 3, img: 'https://picsum.photos/375/180' }
  ];

  // 轮播图自动切换
  useEffect(() => {
    const timer = setInterval(() => {
      setCurrentSwiper(prev => (prev + 1) % swiperList.length);
    }, 3000);
    return () => clearInterval(timer);
  }, [swiperList.length]);

  // 功能菜单数据
  const menuList = [
    { id: 1, name: '首页', icon: '🏠' },
    { id: 2, name: '分类', icon: '📦' },
    { id: 3, name: '购物车', icon: '🛒' },
    { id: 4, name: '我的', icon: '👤' }
  ];

  return (
    <div className="home-container">
      {/* 顶部导航栏：遵循样式规范 */}
      <header className="nav-header">
        <h1>React H5 首页</h1>
      </header>

      {/* 轮播图区域：rem 适配 */}
      <section className="swiper-container">
        <img src={swiperList[currentSwiper].img} alt="轮播图" className="swiper-img" />
      </section>

      {/* 功能菜单区域 */}
      <section className="menu-container">
        {menuList.map(item => (
          <div key={item.id} className="menu-item">
            <span className="menu-icon">{item.icon}</span>
            <p className="menu-name">{item.name}</p>
          </div>
        ))}
      </section>

      {/* 底部版权栏 */}
      <footer className="footer">
        <p>© 2025 React H5 实战项目 版权所有</p>
      </footer>
    </div>
  );
};

export default Home;

AI 自动生成的配套样式（追加至 index.css）

/* 首页样式：遵循扁平化、移动端适配规范 */
.home-container {
  width: 100%;
  min-height: 100vh;
  padding-bottom: 2rem;
}
.nav-header {
  height: 3rem;
  background-color: var(--primary-color);
  display: flex;
  align-items: center;
  justify-content: center;
  color: #fff;
  font-size: 1.2rem;
}
.swiper-container {
  width: 100%;
  height: 11.25rem;
  margin: 0.5rem 0;
}
.swiper-img {
  width: 100%;
  height: 100%;
  object-fit: cover;
}
.menu-container {
  display: flex;
  flex-wrap: wrap;
  padding: 1rem;
  gap: 1rem;
  background-color: #fff;
  margin: 0.5rem;
  border-radius: 0.5rem;
}
.menu-item {
  width: calc(25% - 0.75rem);
  display: flex;
  flex-direction: column;
  align-items: center;
  gap: 0.5rem;
  min-height: 4rem;
}
.menu-icon {
  font-size: 1.5rem;
}
.menu-name {
  font-size: 0.8rem;
  color: var(--text-color);
}
.footer {
  position: fixed;
  bottom: 0;
  width: 100%;
  height: 2rem;
  background-color: #fff;
  display: flex;
  align-items: center;
  justify-content: center;
  font-size: 0.8rem;
  color: #999;
  border-top: 1px solid #eee;
}

3.4.3 第三步：渲染页面，完成项目

继续输入指令：将 Home 组件渲染到 main.jsx 中，启动项目
AI 自动修改 src/main.jsx：

import React from 'react';
import ReactDOM from 'react-dom/client';
import Home from './pages/Home';
import './index.css';

ReactDOM.createRoot(document.getElementById('root')).render(
  <React.StrictMode>
    <Home />
  </React.StrictMode>
);

最终，我们仅通过调用技能 + 自然语言指令，在 Cursor Skills 的支撑下，零代码编写完成了一个完整的 React 单页面 H5 应用，且所有代码完全符合我们预设的开发规范。

3.5 实战总结：Skills 带来的核心价值

1. 规范统一：AI 生成的代码 100% 遵循项目定制规范，无需手动修改、无需反复沟通；
2. 效率提升：初始化、代码生成、配置修改全流程自动化，开发时间缩短 80% 以上；
3. 低成本上手：无需精通 React 细节，通过 Skills 定义规范，AI 完成专业开发；
4. 可复用性：两个技能可直接复用于所有 React H5 项目，团队共享后统一规范。

四、Cursor Skills 高阶实践技巧与避坑指南

4.1 高阶技巧：多技能组合使用

复杂项目中，可将技能拆分为多个细粒度模块，AI 会自动组合匹配：

• 基础技能：通用开发规范、代码格式规范；
• 技术栈技能：React 规范、Hooks 规范；
• 业务技能：H5 适配规范、页面结构规范；
  AI 会自动合并所有匹配的技能指令，生成最贴合需求的代码。

4.2 高阶技巧：技能迭代优化

项目迭代时，无需重新编写技能，仅需修改 SKILL.md 中的指令，AI 会实时生效。例如更新 React 版本后，修改 compatibility 字段，优化组件规范后，直接更新指令内容。

4.3 避坑指南：常见实践错误

1. 技能指令过于抽象：AI 无法理解，生成代码不符合要求，必须使用具体、可执行的指令；
2. 技能文件过于臃肿：将所有规范写在一个技能中，导致 AI 加载缓慢，需模块化拆分；
3. 错误使用自动调用：工具型技能未关闭自动调用，导致 AI 无意义触发，浪费资源；
4. 脚本无错误处理：脚本执行失败后无提示，AI 无法反馈问题，必须完善脚本的异常处理。

五、结语

Cursor Skills 不是一个简单的编辑器扩展功能，而是AI 驱动开发的核心生产工具。它的本质是将开发者的开发经验、项目规范、业务逻辑转化为 AI 可理解、可执行的标准化指令，让 AI 从「通用代码生成器」升级为「项目专属开发助手」。

在前端开发，尤其是 React、Vue 等现代框架开发中，Cursor Skills 的价值尤为突出：它解决了 AI 开发中「规范不统一」「业务不理解」「重复操作多」的核心痛点。通过本文的实战案例可以看出，仅需编写两个简单的技能，就能实现 React H5 项目的全流程自动化开发，大幅降低开发成本、提升开发效率。

实践中，无需追求复杂的技能配置，核心是贴合项目需求、编写精准指令、模块化管理技能。无论是个人独立开发，还是团队协作开发，Cursor Skills 都能成为提升效率的核心利器。随着 AI 编辑器的不断发展，Skills 体系会越来越完善，掌握这一技能，将成为现代前端开发者的必备核心能力。

未来，我们可以将更多的业务逻辑、自动化流程、开发规范集成到 Skills 中，让 AI 承担更多重复性、规范性的开发工作，开发者专注于核心业务创新，真正实现「AI 赋能开发，效率最大化」的目标。