在 AI 编程助手日益普及的今天你是否遇到过这样的困境面对一个复杂的编程问题你向 Claude、Cursor 或 Codeium 等 AI 助手提问得到的回答要么过于笼统要么需要你反复引导和“调教”才能输出符合你项目特定规范如代码风格、架构模式的解决方案。这个过程不仅耗时而且结果往往不尽如人意。本文将深入解析一个在 GitHub 上爆火的项目——mattpocock/skills它被誉为“人类满分程序员的技能库”旨在彻底解决上述痛点。通过学习并应用skills你将能教会你的 AI 助手理解你的专属开发上下文使其输出质量产生质的飞跃无论是新手入门还是资深开发者优化工作流都能从中获得巨大收益。1. 背景与核心概念什么是 Skills在深入实操之前我们首先要厘清几个核心概念这有助于理解skills项目所要解决的真正问题及其价值所在。1.1 AI 编程助手的局限性与上下文缺失当前主流的 AI 编程助手如 Claude Code、GitHub Copilot、Cursor本质上都是基于大型语言模型LLM。它们拥有海量的通用代码知识但缺乏对“你”的认知。具体来说它们不知道你的项目技术栈你是用 React TypeScript 还是 Vue 3 Vite你的代码规范函数命名是camelCase还是snake_case是否需要特定的 JSDoc 格式你的架构偏好是喜欢 Redux Toolkit 还是 Zustand 进行状态管理API 请求层是用 axios 封装还是 tanstack-query你的业务领域知识项目中有哪些特有的领域模型、业务规则和术语这种“上下文缺失”导致 AI 助手生成的代码往往是“通用解”而非“最优解”或“你的解”。你需要花费大量时间进行后期修改和调整。1.2 Skills 项目的定义与目标mattpocock/skills是一个开源仓库其核心思想是将你的开发上下文、偏好和专业知识封装成一个个可被 AI 理解和执行的“技能”Skill。你可以把skills理解为给 AI 助手编写的“超级说明书”或“定制化训练集”。它不是一个运行时库而是一套规范化的文本指令集合。这些指令告诉 AI“当我提出某类需求时请按照以下我定义的规则和范例来思考和生成代码。”项目的核心目标包括标准化提供一种统一的格式来描述开发上下文和约束。可移植编写的skills可以在不同的 AI 助手支持相应功能的之间共享和使用。社区化汇聚全球开发者的最佳实践形成一个不断增长的“技能库”任何人都可以从中汲取灵感或直接使用。1.3 核心组件Skill 与 Skill RepoSkill技能一个skill是一个独立的单元通常对应一个特定的开发任务或约束。例如“使用 React Hook Form 进行表单验证”、“遵循 Airbnb TypeScript 风格指南”、“使用本项目特定的 API 客户端发起请求”。每个skill通过自然语言清晰地描述规则并通常包含正例和反例代码片段。Skill Repo技能仓库即mattpocock/skills这个 GitHub 仓库本身。它按照技术栈、框架、语言等分类收集了众多高质量的skill文件。你可以将其视为一个官方推荐的、经过验证的“技能商店”。1.4 它与普通提示词Prompt的区别你可能会问这和我写一个详细的提示词Prompt有什么区别结构化与模块化Skill是结构化的、可复用的模块。一个复杂的项目上下文可以由多个skill组合而成易于管理而不是一个冗长且难以维护的巨型 Prompt。面向系统集成skills的设计考虑了与 AI 助手系统的集成。例如Cursor 编辑器可以直接识别并应用指定目录下的skills文件。社区与生态基于统一格式的skill可以方便地在社区中分享、评分和改进形成生态。而私人 Prompt 往往是一个黑盒。理解了这些我们就可以开始动手让skills为我们的开发效率赋能。2. 环境准备与编辑器配置skills本身不依赖特定的编程语言环境因为它本质是文本文件。其效果取决于你所使用的 AI 编程助手是否支持该功能。目前Cursor编辑器是对skills支持最完善、最原生的工具。本文将以 Cursor 为主要环境进行演示其他编辑器如 VS Code 配合相应插件可参考类似思路。2.1 安装 Cursor 编辑器访问 Cursor 官网 (https://cursor.sh)。根据你的操作系统Windows, macOS, Linux下载对应的安装包。按照安装向导完成安装。Cursor 界面与 VS Code 非常相似上手无难度。2.2 准备一个测试项目为了演示效果我们创建一个简单的 TypeScript 项目。# 在你的工作目录下打开终端 mkdir my-skills-demo cd my-skills-demo npm init -y npm install typescript types/node --save-dev # 初始化 tsconfig.json npx tsc --init2.3 创建 Skills 目录在项目根目录下创建一个名为.cursor的目录注意前面的点。这是 Cursor 识别项目特定规则的默认目录。# 在项目根目录下执行 mkdir .cursor至此基础环境准备完毕。接下来我们将在这个.cursor目录中创建我们的第一个skill。3. Skill 文件语法与结构拆解一个skill文件通常是一个.md或.txt文件其内容遵循一定的结构以确保 AI 能准确理解。虽然格式可以灵活调整但mattpocock/skills仓库中的范例为我们提供了最佳实践模板。3.1 基础结构一个完整的skill通常包含以下几个部分# Skill 名称 **描述**清晰说明这个技能的目的和适用范围。 **指令**当遇到相关场景时AI 应该遵循的核心规则。这是最重要的部分。 **示例**提供“好”的代码示例和“坏”的代码示例形成鲜明对比。 **上下文**可选说明该技能生效的上下文如文件路径*.ts、技术栈等。3.2 核心语法要点使用自然语言但务必精确避免歧义。使用“必须”、“应该”、“避免”、“不要”等明确词汇。正反例对比这是教学 AI 最有效的方式。反例能清晰界定什么是你不想要的。利用代码块将示例代码放入 language ... 代码块中并标注语言。考虑边界情况在指令中说明例外情况或特殊处理方式。3.3 一个简单的 Skill 示例让我们在.cursor目录下创建第一个技能文件typescript-naming.md。# TypeScript 命名规范 **描述**本技能规定了本项目 TypeScript 代码中变量、函数、类型和接口的命名规则。 **指令** - 使用 camelCase 命名变量、函数、方法、属性。 - 使用 PascalCase 命名类、接口、类型别名、枚举。 - 使用全大写下划线分隔 (UPPER_SNAKE_CASE) 命名常量。 - 布尔变量或函数应以 is has can 等前缀开头。 - 避免使用单个字母的变量名除了简单的循环计数器 i j k。 **示例** ✅ **好例子** typescript // 变量和函数 const userName ‘John‘; function calculateTotalPrice(items: Item[]): number { ... } const MAX_RETRY_COUNT 3; // 类和接口 interface UserProfile { ... } class DatabaseConnection { ... } type ApiResponseT { ... }; // 布尔值 const isLoading false; function hasPermission(user: User): boolean { ... }❌坏例子// 使用了蛇形命名 const user_name ‘John‘; function Calculate_Total_Price() { ... } // 常量未用大写 const maxRetryCount 3; // 类名用了小写 class databaseConnection { ... } // 布尔变量含义不清 const load false;上下文适用于项目中的所有.ts和.tsx文件。创建这个文件后当你在项目中的 .ts 文件里用 Cursor 的 AI 功能如“Chat”或“Composer”请求生成代码时它就会自动参考这些命名规则。 ## 4. 完整实战为 React TypeScript 项目配置 Skills 现在我们进行一个更贴近真实项目的实战。假设我们有一个 React TypeScript Vite 的前端项目我们将为其配置一套组合 skills以规范代码风格、API 请求和组件设计。 ### 4.1 项目初始化与技能目录规划 首先初始化一个 React 项目并创建技能目录结构。 bash # 使用 Vite 创建 React-TS 项目 npm create vitelatest my-react-app -- --template react-ts cd my-react-app npm install # 创建 Cursor 技能目录 mkdir .cursor我们计划在.cursor目录下创建以下技能文件构成一个技能集coding-style.md- 通用代码风格react-hooks.md- React Hooks 使用规范api-client.md- 统一的 API 请求规范component-design.md- 组件设计规范4.2 技能一通用代码风格 (coding-style.md)这个技能涵盖缩进、分号、引号等基础风格。# 项目通用代码风格 **描述**统一项目的代码格式化风格确保一致性。 **指令** - 使用 2 个空格进行缩进禁止使用 Tab。 - 语句末尾**不要**分号 (遵循 StandardJS 风格)。 - 使用单引号 (‘) 定义字符串仅在字符串内包含单引号时使用双引号 (“)。 - 在逗号、冒号、运算符后添加一个空格。 - 最大行宽限制为 100 个字符。 **示例** ✅ **好例子** typescript import { useState, useEffect } from ‘react‘ function MyComponent({ id, name }: MyComponentProps) { const [count, setCount] useState(0) useEffect(() { if (count 10) { console.log(‘Count is too high!‘) } }, [count]) return div className‘my-class‘{name} - {count}/div }❌坏例子import { useState, useEffect } from “react“; function MyComponent({id,name}:MyComponentProps){ const [count, setCount] useState(0); useEffect((){ if(count10){ console.log(“Count is too high!“); } },[count]); return div className“my-class“{name} - {count}/div; }上下文适用于所有.ts.tsx.js.jsx文件。### 4.3 技能二React Hooks 使用规范 (react-hooks.md) 这个技能专注于 React Hooks 的最佳实践。 markdown # React Hooks 规范 **描述**规范 React Hooks 的使用避免常见陷阱。 **指令** - 必须在 React 函数组件或其他自定义 Hook 的顶层调用 Hooks。 - 严格按照依赖数组 [deps] 声明所有外部依赖。 - 使用 useCallback 记忆化传递给子组件的回调函数特别是当子组件用 React.memo 优化时。 - 使用 useMemo 记忆化昂贵的计算值。 - 自定义 Hook 的名称必须以 use 开头。 **示例** ✅ **好例子** typescript import React, { useState, useCallback, useMemo } from ‘react‘ function ProductList({ products, onSelect }: ProductListProps) { const [filter, setFilter] useState(‘‘) // useCallback 记忆化回调 const handleSelect useCallback((id: number) { onSelect(id) }, [onSelect]) // useMemo 记忆化过滤计算 const filteredProducts useMemo(() { return products.filter(p p.name.includes(filter)) }, [products, filter]) return ( // ... 渲染逻辑 ) } // 自定义 Hook function useLocalStorageT(key: string, initialValue: T) { // ... 实现 }❌坏例子function BadComponent() { let [state, setState] useState(0) // 条件语句内调用 Hook if (state 0) { useEffect(() { // 违反顶层调用规则 console.log(state) }) } function handleClick() { // 未使用 useCallback每次渲染都创建新函数 setState(prev prev 1) } }上下文适用于所有.tsx.jsx文件中的 React 组件。### 4.4 技能三API 请求规范 (api-client.md) 这个技能定义如何与后端 API 交互。 markdown # 项目 API 客户端规范 **描述**统一所有 API 请求的发送、错误处理和数据处理方式。 **指令** - 使用项目中已定义的 apiClient 实例来自 /lib/api-client发起请求禁止直接使用 fetch 或 axios。 - 所有请求必须被 try...catch 块包裹并处理错误状态码。 - 错误处理时使用 toast.error() 显示用户友好的错误信息。 - 对于 GET 请求参数必须通过 params 对象传递。 - 对于 POST/PUT 请求数据必须放在 data 属性中。 **示例** ✅ **好例子** typescript import apiClient from ‘/lib/api-client‘ import { toast } from ‘react-hot-toast‘ async function fetchUserData(userId: string) { try { const response await apiClient.get(‘/users‘, { params: { id: userId } // GET 参数 }) return response.data } catch (error: any) { console.error(‘Failed to fetch user:‘, error) toast.error(error.message || ‘获取用户信息失败‘) throw error // 或返回默认值 } } async function updateUserProfile(userId: string, profile: Profile) { try { const response await apiClient.put(/users/${userId}, { data: profile // POST/PUT 数据 }) toast.success(‘更新成功‘) return response.data } catch (error: any) { toast.error(‘更新个人资料失败‘) throw error } }❌坏例子// 直接使用 fetch未统一处理 fetch(/api/users/${id}).then(r r.json()) // 未处理错误 const data await apiClient.post(‘/login‘, { username, password }) // 参数使用错误 await apiClient.get(/users?id${userId}) // 应使用 params 对象上下文适用于所有发起网络请求的.ts或.tsx文件。### 4.5 技能四组件设计规范 (component-design.md) 这个技能指导如何设计和编写 React 组件。 markdown # React 组件设计规范 **描述**规范函数式组件的 Props 定义、结构组织和导出方式。 **指令** - 使用 interface 定义组件的 Props 类型并以 组件名 Props 格式命名。 - 优先使用 React.FCProps 或箭头函数定义组件。 - 组件内部逻辑应清晰分层Hooks 调用 → 事件处理函数 → 渲染逻辑。 - 大型组件应拆分为更小的子组件或自定义 Hooks。 - 默认导出组件本身具名导出其 Props 类型。 **示例** ✅ **好例子** typescript import React, { useState } from ‘react‘ export interface UserCardProps { user: User onFollow: (userId: string) void isCompact?: boolean } const UserCard: React.FCUserCardProps ({ user, onFollow, isCompact false }) { const [isLoading, setIsLoading] useState(false) const handleFollowClick async () { setIsLoading(true) try { await onFollow(user.id) } finally { setIsLoading(false) } } return ( div className{user-card ${isCompact ? ‘compact‘ : ‘‘}} img src{user.avatarUrl} alt{user.name} / div className“user-info“ h3{user.name}/h3 {!isCompact p{user.bio}/p} /div button onClick{handleFollowClick} disabled{isLoading} {isLoading ? ‘处理中...‘ : ‘关注‘} /button /div ) } export default UserCard❌坏例子// Props 使用类型别名且命名随意 type Props { u: User // 属性名不清晰 } // 组件结构混乱逻辑与渲染交织 function BadUserCard({ u }: Props) { return ( div img src{u.avatar} / button onClick{() { /* 直接写复杂逻辑 */ }} 关注 /button {someCondition div{/* 嵌套过深 */}/div} /div ) }上下文适用于所有.tsx文件中的 React 组件定义。### 4.6 在 Cursor 中验证效果 完成以上四个技能文件的创建后你的 .cursor 目录结构应如下所示my-react-app/ ├── .cursor/ │ ├── coding-style.md │ ├── react-hooks.md │ ├── api-client.md │ └── component-design.md ├── src/ ├── ...现在打开 Cursor进入项目中的任何一个 .tsx 文件例如 src/App.tsx。使用 Cursor 的 AI 功能右键选择“Chat with Cursor”或使用快捷键 CmdK。 尝试输入以下指令“创建一个显示用户列表的组件需要支持搜索和分页。” 观察 Cursor 生成的代码。你会发现它生成的代码大概率会 - 使用 2 空格缩进、无分号、单引号遵循 coding-style.md。 - 规范地使用 useState useEffect useCallback 等 Hooks遵循 react-hooks.md。 - 使用 apiClient.get 来模拟获取用户数据遵循 api-client.md。 - 定义一个清晰的 UserListProps 接口并以 React.FC 形式导出组件遵循 component-design.md。 这就是 skills 的强大之处**它将你的团队规范或个人偏好从需要反复口头强调或代码审查中发现的“隐性知识”变成了 AI 在生成代码时自动遵循的“显性规则”**。 ## 5. 高级技巧与最佳实践 掌握了基础技能创建后我们来探讨如何更高效地管理和使用 skills以及一些高级模式。 ### 5.1 技能的组织与管理 1. **按领域分目录**对于大型项目可以在 .cursor 下创建子目录如 .cursor/frontend/ .cursor/backend/ .cursor/devops/。Cursor 会递归读取。 2. **使用 _global 技能**在 .cursor 目录下创建名为 _global.md 或 _global.txt 的文件其中定义的规则对整个项目全局生效无论文件在哪个子目录。适合放最顶层的通用规则。 3. **技能优先级**当多个技能规则冲突时通常更具体上下文如文件路径匹配的技能会覆盖更通用的技能。你可以通过调整技能描述的精确度来控制。 ### 5.2 编写高质量技能的要点 - **具体而非抽象**不要说“写出高质量的代码”而要说“函数长度不超过30行”、“每个文件只导出一个主要组件”。 - **提供充足的正反例**例子是最好的老师。确保反例是真实常见的错误模式。 - **说明“为什么”**在指令中简要说明规则的原因能帮助 AI 在边缘情况下做出更好判断。例如“使用 useCallback 以避免子组件因回调函数引用变化而进行不必要的重渲染。” - **定期复审和更新**随着项目技术栈和规范演进需要更新 skills 文件。 ### 5.3 利用社区技能库mattpocock/skills 你不需要从头编写所有技能。mattpocock/skills 仓库是一个宝库。 1. **访问仓库**在 GitHub 上搜索 mattpocock/skills 或直接访问 https://github.com/mattpocock/skills。 2. **浏览和查找**仓库按技术分类如 typescript/ react/ python/ general/。找到你需要的技能。 3. **复制与适配**将看中的技能文件内容复制到你的项目 .cursor 目录下并根据你的项目实际情况进行微调。**切记不要盲目照搬一定要适配**。 例如社区可能有一个 react-query.md 的技能但你的项目使用的是 SWR你就需要修改其中的具体 API 和模式。 ### 5.4 与其他 AI 助手配合 虽然 Cursor 集成得最好但 skills 的理念是通用的。你可以将 .cursor 目录下的技能文件以适当的方式提供给其他助手 - **Claude Desktop / Codeium / 通义灵码**你可以将关键技能的内容作为系统提示词System Prompt或对话上下文的一部分在开始长期对话或新会话时提供给 AI。 - **ChatGPT 等 Web 界面**在提出复杂编程问题前先将相关的技能描述粘贴到对话中作为背景信息。 ## 6. 常见问题与排查思路 在实际使用中你可能会遇到一些问题。以下是一些常见情况及解决方法。 | 问题现象 | 可能原因 | 排查与解决思路 | | :--- | :--- | :--- | | Cursor 完全忽略技能规则 | 1. 技能文件未放在正确位置项目根目录的 .cursor 下。br2. 技能文件格式错误如非 .md .txt 后缀。br3. Cursor 版本过旧。 | 1. 确认 .cursor 目录位于项目根目录且路径正确。br2. 检查文件后缀名确保是 Cursor 支持的格式。br3. 更新 Cursor 到最新版本。 | | 部分规则生效部分不生效 | 1. 规则描述存在歧义或矛盾。br2. 多个技能文件中的规则冲突。br3. AI 对某些复杂规则理解有限。 | 1. 简化并精确化指令描述使用更明确的词汇。br2. 检查 .cursor 目录下所有文件确保规则一致。可通过创建 _global 文件定义基础规则。br3. 为复杂规则提供更详细、更多样化的正反例。 | | 技能对“Chat”生效但对“Composer”不生效 | “Composer”模式可能依赖不同的上下文加载机制。 | 1. 确保技能文件在项目打开时已被加载。br2. 尝试在 Chat 中明确引用技能例如“请根据我们的 API 客户端规范见 .cursor/api-client.md来生成这段请求代码。”br3. 向 Cursor 官方反馈此问题。 | | 从社区复制的技能不适用 | 社区技能是基于特定技术栈如特定版本的库、特定的项目结构编写的。 | 1. **必须进行本地化修改**替换库名、API、文件路径等。br2. 理解该技能的核心思想然后用自己的项目术语重写。br3. 不要直接复制粘贴要将其作为模板。 | | AI 生成的代码仍包含反例模式 | 1. 技能中的反例不够典型或与正例区别不大。br2. AI 的初始 Prompt 或默认行为过于强大。 | 1. 强化正反例对比让反例是**绝对错误**的示范。br2. 在向 AI 提问时可以额外强调“请严格遵守 .cursor 目录下的组件设计规范。” | ## 7. 工程建议与生产级应用 将 skills 应用于个人项目能提升效率但将其融入团队工作流和大型项目才能发挥其最大价值。 ### 7.1 团队协作与版本控制 1. **将 .cursor 目录纳入 Git**这是最重要的步骤。将技能文件像 package.json 或 tsconfig.json 一样视为项目配置的一部分进行版本管理。 2. **制定技能编写规范**在团队内统一技能的格式、语言中英文和详细程度便于维护和理解。 3. **代码审查包含技能更新**当修改或新增技能时应发起代码审查确保规则的准确性和一致性。 4. **为新成员提供引导**在项目 README 中说明 .cursor 目录的作用让新成员在安装完 Cursor 后立即获得与团队一致的 AI 辅助体验。 ### 7.2 分层与模块化技能设计 对于复杂企业级项目建议对技能进行分层设计 - **L1 基础规范层**代码风格、命名、基础语法等。放在 .cursor/_global.md。 - **L2 框架/技术栈层**React、Vue、TypeScript、TailwindCSS 等特定技术的使用规范。放在 .cursor/frontend/react.md 等。 - **L3 项目/业务层**项目特定的 API 客户端、工具函数、业务组件规范、领域模型约定等。放在 .cursor/project/ 下。 - **L4 模块/功能层**可选针对特定功能模块如支付、用户管理的非常具体的技能。 ### 7.3 技能与代码质量工具的集成 skills 与 ESLint、Prettier、TypeScript 编译器等工具形成互补 - **ESLint/Prettier**负责在代码**编写后**进行静态检查和格式化是“硬性约束”。 - **Skills**负责在代码**生成时**就引导 AI 产出符合规范的代码是“事前预防”。 - **分工**用 skills 让 AI 生成风格一致的代码用 ESLint/Prettier 作为最终守门员并可将两者的规则对齐例如skills 中关于分号的规则应与 Prettier 配置一致。 ### 7.4 持续维护与迭代 技能库不是一成不变的。 1. **设立反馈渠道**鼓励团队成员在遇到 AI 生成代码不符合预期时不是简单修改代码而是思考是否应更新或新增一个 skill。 2. **定期回顾**在迭代复盘时可以回顾近期常见的代码审查问题看是否能通过增强 skills 来预防。 3. **关注社区动态**定期查看 mattpocock/skills 等社区仓库学习新的最佳实践并判断是否适合引入自己的项目。 通过将 mattpocock/skills 的理念和实践融入你的开发流程你实质上是在为团队的集体智慧和外部的 AI 能力之间搭建了一座标准化、可传承的桥梁。这不仅能极大提升开发效率更能显著提高代码库的长期一致性和可维护性。从今天开始为你和你的团队创建第一个 .cursor 技能文件体验从“人适应 AI”到“AI 适应人”的转变。