1. 项目概述为什么我们需要一份通用的“技能”如果你最近深度使用过 Claude Code 或者 Cursor大概率会和我有一样的感受这玩意儿很强但有时候又“笨”得让人着急。比如你让它写一个 React 组件它可能写得又快又好但当你切换到另一个项目需要它按照你们团队的特定规范比如必须用useCallback包装所有事件处理器、必须导出Props类型来写时你又得在对话里重新解释一遍。或者当你处理一个特定领域的任务比如用 Three.js 画一个特定样式的 3D 模型每次开启新对话你都得把那些复杂的参数和公式再喂给它一次。这种重复的“调教”成本就是“技能”Skill要解决的问题。你可以把它理解为一个高度定制化的“提示词模板”或“指令集”。但与普通的提示词不同一个设计良好的 Skill 应该是可复用、可组合、可分享的。它封装了特定场景下的最佳实践、代码规范、甚至是领域知识让你和 AI 助手之间的协作效率产生质的飞跃。那么一份能让 Claude Code 和 Cursor 都“听懂”且好用的通用 Skill到底该怎么写又该去哪里寻找现成的优质资源这正是我们今天要深入拆解的核心。我将结合自己为团队搭建 AI 编码工作流的经验从设计思路、结构拆解、编写技巧到资源挖掘为你提供一份可以直接上手操作的指南。2. 通用 Skill 的核心设计哲学与结构拆解写 Skill 不是堆砌命令而是在设计一个你和 AI 之间的“协作协议”。一份通用的 Skill其核心目标是在不同的 AI 编码工具如 Claude Code, Cursor, 乃至未来其他工具上都能稳定、一致地工作。这就要求它的设计必须遵循一些底层原则。2.1 设计哲学清晰、具体、可组合首先清晰高于一切。AI 不是人它没有常识和背景知识除非你告诉它。你的 Skill 必须用最明确无歧义的语言定义输入、输出、约束条件和执行步骤。避免使用“优雅地”、“高效地”这类主观形容词取而代之的是具体的指标如“函数行数不超过 50 行”、“必须包含完整的错误处理”。其次具体化是生效的关键。与其说“遵循 React 最佳实践”不如写成“1. 使用函数组件。2. 使用 TypeScript为所有 Props 定义明确的接口。3. 对于事件处理函数使用useCallback进行记忆化。4. 对于派生状态使用useMemo。”最后可组合性决定了 Skill 的威力。一个复杂的开发任务可以被拆解为多个原子化的 Skill。例如你可以有一个“生成 React 函数组件骨架”的 Skill一个“添加 Redux Toolkit 异步 Thunk”的 Skill和一个“编写 Jest React Testing Library 单元测试”的 Skill。通过组合它们你可以快速搭建出符合全套规范的代码模块。2.2 标准结构解剖四段式框架一份通用的 Skill 通常包含以下四个部分我称之为“四段式框架”。这个框架能确保信息结构完整易于被不同 AI 模型解析。第一部分角色与上下文定义这部分告诉 AI“你是谁”以及“在什么背景下工作”。这是设定基调的关键。你是一个经验丰富的 [特定领域如前端/后端/数据科学] 工程师擅长编写高质量、可维护的 [技术栈如 TypeScript/Python] 代码。你现在正在参与一个 [项目类型如企业级中后台/高性能数据处理] 项目。为什么重要这为 AI 设定了知识边界和风格倾向。一个被定义为“经验丰富后端工程师”的 AI在建议数据库查询优化时会比一个通用 AI 给出更专业的方案。第二部分核心任务与输入输出规范这是 Skill 的心脏必须极其精确。任务描述用一句话清晰说明要做什么。例如“根据提供的功能描述和数据结构生成一个完整的 RESTful API 控制器函数。”输入格式明确用户需要提供什么信息。例如“请提供1. 资源名称如User。2. 需要的操作如GET /users,POST /users。3. 相关的数据模型字段JSON 格式。”输出格式规定 AI 应该返回什么。例如“输出一个 ESModule 格式的 Node.js 文件包含1. 导入语句。2. 使用async/await的控制器函数。3. 基本的输入验证和错误处理使用http-errors库。4. 返回标准化的 JSON 响应。”第三部分约束条件与编码规范这部分将团队或项目的具体要求具象化是保证代码一致性的核心。技术栈约束指定语言、框架、库及其版本。“使用 Python 3.9 FastAPI 框架 SQLAlchemy 2.0 风格。”代码风格链接或直接写明规范。“代码风格必须严格遵循 Airbnb JavaScript Style Guide。所有导出的函数都必须有 JSDoc/TSDoc 注释。”安全与性能要求“所有数据库查询必须使用参数化查询以防止 SQL 注入。列表查询必须支持分页默认每页 10 条。”禁止项明确红线。“禁止使用any类型。禁止使用var。禁止出现硬编码的密钥或密码。”第四部分示例Few-Shot Prompting这是大幅提升效果的王牌。提供一个甚至多个输入输出的完整示例。示例输入 资源Article 操作GET /articles/:id 获取单篇文章 DELETE /articles/:id 删除文章 字段id (integer, PK), title (string), content (text), author_id (integer) 示例输出 这里附上一段符合前述所有规范的、完整的示例代码提供一个好的示例相当于给 AI 做了次精准的“微调”它能更好地理解你的复杂要求并模仿其风格和结构。3. 从零到一手把手编写你的第一个通用 Skill理论说再多不如动手写一个。我们以一个非常实用且通用的场景为例“为现有函数生成单元测试”。这个 Skill 在代码重构和保障质量时极其有用。3.1 第一步明确场景与工具兼容性我们的目标是让这个 Skill 在 Claude Code通常通过特定提示词触发和 Cursor可以使用/指令或保存在.cursor/rules目录下的规则文件中都能工作。因此我们要编写一个“与工具无关”的、纯文本的指令集。在 Cursor 中我们可以将其保存为generate_unit_test.md并放在项目规则目录在 Claude Code 中我们可以将其作为一段对话的“系统提示”或快捷指令。3.2 第二步应用“四段式框架”进行填充下面就是我们编写完成的 Skill 内容。你可以直接复制并根据你的技术栈进行调整。# Skill: 生成高质量单元测试 ## 角色与上下文 你是一个专注于代码质量和测试驱动开发TDD的资深软件工程师。你对编写覆盖全面、边界清晰、可维护的单元测试有深刻的理解和实践经验。 ## 核心任务 你的任务是为我提供的单个函数或方法生成一套完整的单元测试代码。目标是覆盖正常流程、各种边界条件以及可能的异常情况。 ## 输入输出规范 - **输入**我会提供以下内容 1. **函数代码**需要被测试的函数的完整源代码。 2. **技术栈**使用的编程语言、测试框架、断言库以及任何相关的 Mock 库如 Jest, pytest, unittest, mocha/chai, sinon 等。 3. **上下文说明可选**该函数所在的模块、依赖的外部服务或组件如数据库、API 客户端的简要说明。 - **输出**你必须返回 1. **完整的测试文件代码**包含所有必要的导入import语句。 2. **测试套件结构**使用 describe/it (Jest/Mocha) 或类似的语义化块来组织测试用例。 3. **全面的测试用例**至少包含 - **Happy Path**验证函数在正常输入下的预期输出。 - **边界条件**针对输入参数的边界值进行测试如空字符串、零、负数、极大值、null/undefined。 - **错误处理**验证函数在接收到非法输入或依赖抛出异常时的行为是否抛出了正确的异常或返回了错误标识。 4. **Mock 策略**如果函数依赖外部模块或服务你需要清晰地展示如何正确地 Mock 它们并验证与这些依赖的交互如某个方法被调用了一次且传入了特定参数。 5. **清晰的测试描述**每个 it 或 test 块都必须有一个描述性的、人类可读的字符串说明这个用例在测什么。 ## 约束条件与规范 1. **测试独立性**每个测试用例必须完全独立不能依赖其他测试的运行状态或顺序。必须妥善处理 beforeEach, afterEach 等钩子函数。 2. **避免过度实现细节测试**测试应关注函数的行为输出、副作用而非其内部实现。避免对函数内部临时变量或未导出的私有函数进行测试。 3. **Mock 准则**优先使用框架提供的 Mock 功能如 Jest 的 jest.mock。Mock 对象的行为应尽量真实、简单。 4. **命名规范**测试文件名应为 [原文件名].test.js 或 [原文件名].spec.js 格式。测试描述使用“应该should”句式例如“it(‘should return the sum of two numbers’, …)”。 5. **覆盖率提示非强制**生成的测试应尽可能追求高逻辑覆盖率但首要目标是测试用例的准确性和可读性。 ## 示例 **输入** - 函数代码JavaScript javascript // math.js export function divide(a, b) { if (b 0) { throw new Error(‘除数不能为零’); } return a / b; }技术栈JavaScript, Jest 测试框架。输出// math.test.js import { divide } from ‘./math’; describe(‘divide function’, () { // Happy Path 测试 it(‘should return the correct quotient when dividing two positive numbers’, () { expect(divide(10, 2)).toBe(5); expect(divide(9, 3)).toBe(3); }); it(‘should handle division with negative numbers’, () { expect(divide(-10, 2)).toBe(-5); expect(divide(10, -2)).toBe(-5); }); // 边界条件/异常处理测试 it(‘should throw an error when divisor is zero’, () { // 注意测试抛出的异常时必须将函数调用包裹在一个函数中 expect(() divide(10, 0)).toThrow(‘除数不能为零’); expect(() divide(0, 0)).toThrow(‘除数不能为零’); }); it(‘should return Infinity when dividing by zero? No, it should throw.’, () { // 这是一个明确的说明强调我们的函数设计是抛出错误而不是返回 Infinity。 // 这个用例可以省略这里仅作演示。 }); // 边界条件被除数为 0 it(‘should return 0 when dividend is 0 and divisor is non-zero’, () { expect(divide(0, 5)).toBe(0); }); });### 3.3 第三步在不同工具中应用此 Skill - **在 Cursor 中** 1. 在你项目的根目录下创建 .cursor/rules 文件夹如果不存在。 2. 将上面的 Skill 内容保存为 generate_unit_test.md 文件并放入该文件夹。 3. 当你在编辑一个函数时打开 Cursor 的 Chat 面板输入 /你应该能看到一个名为 “generate_unit_test” 的规则选项。选择它然后粘贴你的函数代码AI 就会按照 Skill 的规范为你生成测试。 - **在 Claude Code或类似聊天界面中** 1. 开启一个新对话。 2. 将整个 Skill 内容从 # Skill: 生成高质量单元测试 开始作为第一条消息发送给 AI。这相当于设定了系统角色和上下文。 3. 在第二条消息中提供你的具体输入函数代码和技术栈。 4. AI 就会按照 Skill 的约定进行回复。 **注意**Skill 的生效质量很大程度上取决于你提供的“输入”是否清晰。务必一次性给全所需信息避免在后续对话中零散补充这可能导致 AI 遗忘或混淆之前的指令。 ## 4. 进阶技巧如何让 Skill 更强大、更智能 掌握了基础写法后我们可以通过一些进阶技巧让 Skill 的适应性和威力更上一层楼。 ### 4.1 利用变量和占位符实现动态化 一个死板的 Skill 适用面很窄。我们可以引入“变量”的概念让用户在使用时动态填充。在 Skill 文本中用 {{}} 包裹变量名。 例如在一个“生成 CRUD 接口”的 Skill 中你可以这样写请为我生成关于{{ResourceName}}资源的 RESTful API 代码。使用的框架是{{Framework}}数据库 ORM 是{{ORM}}。在 Cursor 中使用时它可能会提示你输入 ResourceName、Framework 等变量的值。在 Claude 对话中你需要在后续消息中明确提供这些值。这使一个 Skill 模板能用于无数种具体资源。 ### 4.2 设计链式与可组合的 Skill 复杂的开发流程可以分解。例如 - **Skill A分析需求生成 API 设计文档**输入用户故事输出OpenAPI Spec 片段。 - **Skill B根据 OpenAPI Spec 生成控制器骨架**输入Spec输出Controller 代码。 - **Skill C为控制器生成 Service 层和数据库模型**输入Controller输出Service Model。 - **Skill D为上述所有代码生成单元测试**输入各类代码文件输出测试文件。 你可以指示 AI“现在我们将依次应用 Skill A, B, C, D 来完成这个微服务的开发。” 这实际上是在进行一种“AI 工作流编排”。 ### 4.3 融入领域特定语言DSL和设计模式 对于特定领域Skill 可以封装该领域的专业知识。比如一个“Three.js 场景初始化” Skill可以内置关于 WebGL 上下文、渲染循环、相机控制器、光照设置的最佳实践代码块。用户只需要描述“我想要一个带有轨道控制、环境光和方向光的 3D 场景”AI 就能输出一个配置妥当的样板代码。 同样Skill 可以强制要求使用某种设计模式。例如“在生成状态管理逻辑时必须使用 Redux Toolkit 的 createSlice 函数并遵循 Flux 架构的标准模式。” ## 5. 优质 Skill 的寻宝图去哪找现成的资源 自己从头编写所有 Skill 效率太低。社区和官方已经积累了不少宝藏关键在于知道去哪挖。 ### 5.1 官方资源与社区精选 1. **Cursor 官方规则库**这是最直接的来源。Cursor 的社区和团队会维护一些高质量的规则。关注 Cursor 的官方文档、博客和 Discord 社区经常会有分享。一些开源项目也会在根目录的 .cursor/rules 里附带项目特定的规则这是学习的好材料。 2. **Awesome-Prompt-Engineering 类仓库**在 GitHub 上搜索 awesome prompt engineering 或 awesome chatgpt prompts你会发现很多庞大的列表。虽然不全是编码 Skill但其中“Code”分类下的内容极具参考价值。你可以从中汲取灵感改编成适合 Claude Code/Cursor 的格式。 3. **专业开发者社区**像 Dev.to, Hashnode, Medium 上的技术博客以及 Reddit 的 r/OpenAI, r/ClaudeAI, r/Cursor 等子版块经常有开发者分享他们打磨好的、用于特定任务的提示词或 Skill。例如搜索“Cursor rule for generating React components”可能会找到惊喜。 ### 5.2 从开源项目中“偷师” 这是我最推荐的方法能学到最接地气的实践。 1. **寻找高质量、规范严格的开源项目**尤其是那些使用 TypeScript、拥有完善测试和文档的项目如 Next.js, Prisma, Vite 等生态中的优秀库。 2. **逆向工程其贡献指南和代码风格**查看项目的 CONTRIBUTING.md、.eslintrc.js、tsconfig.json 和测试文件。这些文件本身就定义了项目的“技能”。你可以将这些规范翻译成 Skill 的“约束条件与编码规范”部分。 3. **提炼模式**观察该项目中多个同类文件如组件、API 路由、工具函数的结构和模式将其抽象成 Skill 的“示例”部分。 ### 5.3 利用 AI 来优化和发现 Skill 这是一个高阶玩法**用 AI 来帮你写和改进 Skill**。 1. **生成初稿**你可以对一个基础 AI 说“我想创建一个用于生成 Python FastAPI CRUD 接口的 Skill要求包含请求验证、数据库会话依赖注入和错误处理。请为我草拟一个结构清晰、指令明确的 Skill 模板。” 它会给你一个不错的起点。 2. **迭代优化**将你写的 Skill 用在真实任务上把 AI 输出中不符合预期的部分记录下来。然后带着这些“失败案例”去修改你的 Skill增加更明确的约束或更贴切的示例。这个过程本身就是一种“提示词工程”的实践。 3. **探索未知领域**当你需要进入一个不熟悉的领域比如用 Rust 写解析器可以先让 AI 为你概述这个领域的常见模式和最佳实践然后基于此快速构建一个初级 Skill在边学边用中不断完善它。 ## 6. 避坑指南编写与应用 Skill 的常见陷阱 在实际编写和使用 Skill 的过程中我踩过不少坑这里总结几个最常见的帮你省下试错时间。 ### 6.1 陷阱一指令过于宽泛或存在歧义 **反面教材**“写一个高效的函数。” **问题**“高效”指什么是时间复杂度低、内存占用少还是代码简洁AI 无从判断结果可能五花八门。 **修正方案**必须量化或具体化。改为“写一个函数使用哈希表在 O(n) 时间复杂度内找出数组中出现次数超过一半的元素。” ### 6.2 陷阱二忽略了上下文长度限制 Claude、GPT 等模型都有上下文窗口限制。如果你的 Skill 本身非常长再加上复杂的示例代码很容易挤占掉处理实际问题的空间。 **解决方案** - **精简示例**示例贵精不贵多一个最具代表性的、覆盖了各种约束的示例往往比三个平庸的示例更有效。 - **拆分 Skill**如果一个 Skill 试图做太多事情如“全栈项目生成器”就把它拆分成“前端组件生成”、“后端 API 生成”、“数据库模型生成”等多个小 Skill。 - **使用外部引用**对于非常长的规范如完整的公司编码规范文档不要在 Skill 里全文粘贴。可以写“请遵循项目根目录下 .eslintrc.cjs 和 tsconfig.json 中的规则。” 然后在对话中必要时再单独提供这些文件的关键部分。 ### 6.3 陷阱三在 Cursor 中错误地放置或调用规则 - **规则不生效**确保规则文件.md放在了正确的目录通常是项目根目录的 .cursor/rules 下。在 Cursor 的设置中检查规则目录的路径是否配置正确。 - **规则冲突**如果项目中有多个规则它们可能会相互干扰。特别是当规则包含矛盾的指令时比如一个要求用双引号一个要求用单引号。建议为不同层级的规则建立清晰的命名和目录结构或者使用 Cursor 的规则优先级机制。 - **忘记激活**在 Cursor Chat 中输入 / 后要手动选择你想应用的规则。有时我们写了规则但聊天时忘了用结果 AI 还是按默认模式回答。 ### 6.4 陷阱四过度依赖放弃思考 这是最危险的陷阱。Skill 是强大的杠杆但不能替代你的思考。AI 生成的代码尤其是复杂逻辑**必须经过你的仔细审查**。 - **逻辑正确性**AI 可能会生成看似合理但存在边界条件错误的代码。 - **安全性**AI 不一定了解最新的安全漏洞。对于涉及用户输入、数据库查询、命令执行、身份验证的代码必须人工进行安全审计。 - **架构合理性**AI 擅长完成具体指令但不擅长做高层架构决策。将大模块拆分成哪些小模块、如何设计数据流这些决策权必须掌握在你手里。 Skill 应该作为你的“超级助手”帮你处理重复、繁琐、模式化的编码工作从而让你能更专注于创造性的设计、复杂的算法和核心的业务逻辑。当你开始为一个任务编写 Skill 时你其实是在沉淀和固化这个任务的最佳实践这个过程本身就对提升你的工程能力大有裨益。
