1. 项目概述从“助手”到“队友”的进化最近在折腾AI编程工具的朋友估计都绕不开Claude Code。它确实是个好用的“助手”能帮你补全代码、解释逻辑甚至修复一些简单的bug。但不知道你有没有这种感觉很多时候你得像哄孩子一样一遍遍地给它描述你想要的功能或者纠正它跑偏的思路。它更像一个需要你精确指令的“实习生”而不是一个能主动思考、理解你项目上下文的“搭档”。这正是“Agent Skills”这个概念要解决的问题。我们不再满足于让AI被动响应而是希望它能主动“理解”我们的项目掌握我们团队的“黑话”和“套路”从而真正融入开发流程。而实现这一转变的关键就是一份名为SKILL.md的文档。这听起来可能有点抽象但简单来说SKILL.md就是一份写给Claude Code的“岗位说明书”和“工作手册”。通过它你可以将你个人的编码习惯、项目的技术栈规范、甚至是那些只有老员工才知道的“祖传代码”逻辑系统地“传授”给Claude Code。当Claude Code消化了这份文档后它的行为模式会发生质变。比如你不再需要每次都说“用TypeScript写一个React函数组件要包含useState”因为你已经在SKILL.md里定义了团队组件规范它自然会按规范生成。当你提到“处理那个用户上传的钩子”时它能立刻联想到项目中具体的useFileUpload自定义Hook而不是生成一段通用代码。这种从“一问一答”到“心领神会”的转变就是我们将Claude Code从“助手”升级为“队友”的核心目标。接下来我会详细拆解如何通过一份精心设计的SKILL.md一步步实现这个目标。2. 核心理念SKILL.md 如何重塑 AI 工作流2.1 从“指令驱动”到“上下文驱动”的范式转变传统的AI编码助手工作模式我称之为“指令驱动”。你输入一个具体的、原子化的任务比如“写一个Python函数计算斐波那契数列”AI返回一段代码。这种模式的问题在于它极度依赖你输入的即时信息质量。如果你没说清楚边界条件、性能要求或者代码风格结果往往需要反复调整。更重要的是AI对项目的整体架构、历史决策、业务逻辑一无所知就像一个空降的外援每次都要从头了解情况。SKILL.md引入的是“上下文驱动”范式。它的核心思想是将那些重复的、隐性的、项目特有的知识从你的大脑和零散的聊天记录中沉淀为一份结构化的、机器可读的文档。这份文档会在每次与Claude Code交互时作为背景知识Context自动提供给AI。这意味着AI在开始思考你的具体问题之前已经“预习”了项目的“教材”。这种转变带来的最直接好处是沟通成本的断崖式下降。你不再需要为每个任务撰写冗长的“需求文档式”提示词。例如在一个使用Redux Toolkit和RTK Query的项目中你只需要说“给用户列表页加个搜索功能”Claude Code结合SKILL.md中关于状态管理、API层和UI组件的约定就能自动生成符合规范的动作action、切片slice、查询query以及组件代码而不是生成一套过时的、手写Redux的方案。2.2 SKILL.md 的核心构成一份给AI的“项目生存指南”一份有效的SKILL.md不是随意堆砌的文本它需要有清晰的结构以便AI高效地提取和利用信息。根据我的实战经验它通常包含以下几个核心模块项目身份与目标Project Identity Goals这是AI理解项目“为什么存在”的基石。需要清晰说明项目的核心业务价值、目标用户、以及希望达成的关键成果。这能帮助AI在提出方案时优先考虑业务目标而不仅仅是技术实现。例如“本项目是一个面向中小企业的内部知识库系统核心目标是降低信息检索成本提升团队协作效率。因此所有功能设计应优先考虑易用性和检索速度而非极致的视觉特效。”技术栈与架构规范Tech Stack Architecture这是约束AI代码生成的“法律条文”。必须明确列出前端/后端/移动端技术栈精确到主要库和框架的版本如React 18, Next.js 14, Python 3.11 FastAPI。代码风格与格式化规则指定是ESLint Prettier还是Ruff并给出配置文件名称或关键规则如“使用双引号”、“函数最大行数80”。目录结构约定说明src/components/,src/hooks/,src/services/等目录的职责。状态管理、路由、API交互方案明确使用Zustand还是Redux Toolkit使用TanStack Router还是React Router使用axios还是fetch的封装。领域特定语言与模式Domain-Specific Language Patterns这是提升AI理解深度的“行业黑话”。每个项目都有自己独特的业务概念和对应的代码模式。业务实体定义明确“用户”、“订单”、“工作流”等在代码中对应的类名、接口名。通用设计模式例如“所有数据获取操作必须使用useQuery自定义Hook进行封装错误处理在Hook内部完成”。命名约定例如“API请求函数以fetch或get开头事件处理函数以handle开头”。“避坑”指南与最佳实践Anti-Patterns Best Practices这部分是经验的结晶价值最高。直接告诉AI“不要做什么”和“应该怎么做”。已知陷阱“在useEffect中直接修改状态可能导致无限循环应使用函数式更新。”性能禁忌“禁止在渲染函数中进行重型计算或数据转换应使用useMemo。”安全红线“所有用户输入在插入DOM前必须使用DOMPurify进行消毒。”项目特定技巧“与后端/api/v2/交互时需要在请求头中附加X-Client-Version: 2.0。”工作流程与协作指令Workflow Collaboration Commands定义AI如何参与团队协作。例如代码审查视角“在生成或修改代码后请以代码审查者的角度列出可能存在的潜在问题如可访问性、边界条件处理、类型安全。”测试驱动开发“在实现功能前请先根据描述为我生成相应的Jest/Vitest测试用例框架。”文档生成“在创建新的React组件后请自动生成对应的Props类型说明和基础用法示例格式参考项目中的Component.stories.mdx。”注意SKILL.md是一个动态文档。在项目初期它可以很简单只包含技术栈和基本规范。随着项目推进和与AI协作经验的积累你需要不断将遇到的新模式、解决的典型问题补充进去。它应该被纳入版本控制系统如Git成为项目文档不可或缺的一部分。3. 实战构建手把手创建你的第一份 SKILL.md理论讲得再多不如动手写一行。下面我将以一个假设的“任务管理Web应用”项目为例带你从零开始创建一份具有实战价值的SKILL.md。我们将使用Visual Studio Code和Claude Code扩展进行演示。3.1 环境准备与基础配置首先确保你的开发环境已经就绪。安装VS Code从官网下载并安装最新稳定版。安装Claude Code扩展在VS Code的扩展市场CtrlShiftX中搜索“Claude Code”。点击安装。请注意该扩展的可用性可能因地区而异请根据官方指引完成账户绑定和配置。创建项目与SKILL.md文件# 创建一个新的Next.js项目示例 npx create-next-applatest task-manager-app --typescript --tailwind --app cd task-manager-app # 在项目根目录创建SKILL.md文件 touch SKILL.md现在用VS Code打开SKILL.md文件我们开始填充内容。3.2 逐模块详解与编写示例一份好的SKILL.md应该开门见山让AI快速抓住重点。我们从最核心的项目定义开始。模块一项目身份与目标# SKILL.md - 任务管理应用 (TaskMaster) ## 项目概述 本项目代号TaskMaster是一个轻量级、团队协作式的任务管理Web应用。核心目标是帮助小型敏捷团队5-10人可视化工作流、跟踪任务进度并减少沟通开销。**用户体验和响应速度是最高优先级**功能上遵循“少即是多”原则优先保证核心流程的极致流畅。 **核心用户价值** 1. 快速创建、分配和流转任务。 2. 清晰可视化的看板Kanban视图了解整体项目状态。 3. 最小化的界面干扰让用户专注于任务本身。编写心得这部分要像电梯演讲一样简洁有力。明确“为谁解决什么问题”这能引导AI在后续所有代码生成中都带着“提升用户体验和性能”的视角去思考。模块二技术栈与硬性规范## 技术栈与开发规范 ### 强制技术栈 - **框架**: Next.js 14 (App Router) - **语言**: TypeScript (严格模式 strict: true) - **样式**: Tailwind CSS v3.4 - **UI组件库**: 无。所有组件必须自主开发以保持极简设计和包体积最小化。 - **状态管理**: Zustand (用于全局状态如用户信息、主题)。组件级状态优先使用 useState/useReducer。 - **数据获取**: TanStack Query (React Query) v5。**禁止**在组件中直接使用 fetch 或 axios所有API调用必须通过自定义的 useQuery 或 useMutation hooks封装。 - **表单处理**: React Hook Form Zod (用于表单验证和类型安全)。 - **图标**: Lucide React。 ### 代码风格与质量 - **格式化**: 使用项目根目录的 .prettierrc 配置。提交前必须运行 npm run format。 - **代码检查**: 使用项目根目录的 .eslintrc.json 配置。禁止出现任何ESLint错误。 - **命名约定**: - 组件文件: PascalCase如 TaskCard.tsx。 - 工具函数/Hooks文件: camelCase如 useTaskOperations.ts。 - 常量: UPPER_SNAKE_CASE如 API_ENDPOINTS。 - 接口/类型: PascalCase 并以 I 前缀开头团队约定如 ITask, IUser。 - **目录结构**: - /app: Next.js App Router 页面和布局。 - /components: 可复用UI组件。按领域分文件夹如 /components/task/, /components/ui/。 - /hooks: 自定义React Hooks。 - /lib: 工具函数、API客户端配置、常量。 - /stores: Zustand store 定义。 - /types: 全局TypeScript类型定义。编写心得这部分要“不留歧义”。版本号、配置文件名、目录结构都要写清楚。“禁止”和“必须”这类词要大胆使用这是给AI的强制指令。明确“用什么”和“不用什么”同样重要。模块三领域模式与业务逻辑## 领域模型与业务逻辑 ### 核心数据模型 typescript // 位于 /types/task.ts interface ITask { id: string; // UUID v4 title: string; description?: string; status: backlog | todo | in-progress | review | done; // 看板列状态 priority: low | medium | high; assigneeId?: string; // 关联用户ID createdAt: Date; updatedAt: Date; // ... 其他业务字段 }API交互模式所有API请求必须通过/lib/api-client.ts中导出的apiClient实例发起。Query Keys: 为TanStack Query定义统一的Key工厂函数位于/lib/queryKeys.ts。错误处理: API客户端会拦截错误并统一转换为ApiError类型。在Hook中使用try...catch或onError回调处理并向用户展示友好的Toast消息使用sonner库。组件设计模式容器组件与展示组件分离: 页面/app/*或容器组件负责数据获取和状态管理将数据作为Props传递给纯展示组件/components/*。任务卡片组件 (TaskCard)必须接收完整的ITask对象作为prop。交互逻辑如点击编辑、拖拽开始通过回调函数向上传递。* **编写心得**直接贴出关键的类型定义和代码片段是最有效的方式。AI能直接“看到”你的数据结构。描述业务规则时使用“必须”、“通过…发起”、“定义为…”等确定性语言。 **模块四避坑指南与性能守则精华部分**关键注意事项与最佳实践 (请严格遵守)性能禁区⚠️ 禁止在渲染函数或组件主体内进行任何形式的数据过滤、排序或映射操作。此类逻辑必须封装在useMemo钩子中依赖项必须明确列出。⚠️ 禁止创建内联函数作为事件处理器如onClick{() doSomething()}除非该函数极其简单。应使用useCallback或将其定义在组件外部。✅ 正确做法: 对于列表渲染必须为每个列表项提供稳定且唯一的key属性优先使用数据ID而非索引。状态管理陷阱Zustand Store的定义应尽量细粒度。不要创建一个包含所有应用状态的“上帝Store”。例如将useTaskStore和useUserStore分开。避免 Zustand 的深度嵌套状态更新。更新状态时始终使用Immer风格的更新set(state { state.tasks.push(newTask) })或展开运算符返回新对象。安全与健壮性所有用户输入在显示或发送到后端前必须进行验证和清理。表单使用Zod Schema验证动态内容使用DOMPurify。网络请求必须考虑加载、成功、失败状态。UI上要有明确的加载指示器和错误反馈。项目特定“祖传”逻辑任务状态流转是单向的backlog - todo - in-progress - review - done。不允许逆向流转。相关验证逻辑在/lib/task-validator.ts中。优先级颜色编码:high对应红色(bg-red-100)medium对应黄色low对应绿色。已在/components/ui/PriorityBadge.tsx中实现请直接使用该组件。* **编写心得**这部分是SKILL.md的灵魂直接决定了AI能否帮你避开雷区。用“⚠️ 禁止”和“✅ 正确做法”的对比形式效果极佳。把项目中那些“血的教训”总结成条文AI下次就不会再犯。 **模块五协作指令**与Claude Code的协作约定当你Claude Code协助我进行开发时请遵循以下模式代码生成在生成任何代码片段前请先简要说明你的实现思路并确认是否符合上述技术栈和模式。代码审查在你生成或我提供一段代码后请自动以代码审查者的身份列出潜在的性能问题如缺少useMemo/useCallback。可能违反项目约定的模式如直接使用fetch。类型安全风险如使用any。可访问性a11y问题如图片缺少alt文本。测试建议对于核心业务逻辑如task-validator.ts请建议需要覆盖的测试用例。提问如果我的需求描述不够清晰或与现有项目模式有冲突请主动提问澄清而不是猜测我的意图。* **编写心得**这部分是“调教”AI行为模式的关键。你是在定义你们之间的“合作流程”。告诉它你期望它如何工作它能反馈什么这样协作才会高效。 ## 4. 集成与调优让 SKILL.md 在 Claude Code 中生效 写完SKILL.md只是第一步如何让Claude Code“学会”它才是关键。目前Claude Code主要通过与它对话的“上下文”来学习。我们需要巧妙地将这份文档融入对话中。 ### 4.1 初始“培训”与上下文加载 最直接有效的方法就是在开启一个新的、重要的对话线程时将SKILL.md的内容作为第一条消息或系统提示词发送给Claude Code。 **操作步骤** 1. 在VS Code中打开你的SKILL.md文件全选并复制所有内容。 2. 在Claude Code的聊天面板中开始一个新对话。 3. 首先发送一条明确的指令作为“开场白” 你好Claude。接下来我们将一起在“TaskMaster”项目上进行开发。这是该项目的完整技能与规范文档SKILL.md请你仔细阅读并理解。在后续所有关于本项目的对话中请严格依据此文档中的技术栈、模式、禁忌和协作约定来提供帮助。 4. 紧接着将复制的SKILL.md全文粘贴发送。 **原理与技巧** * **开场白的重要性**明确的指令“严格依据此文档”能强化AI对后续内容重要性的认知。 * **上下文长度管理**SKILL.md可能会很长超出AI单次上下文窗口。一个技巧是将其拆分为几个核心部分如“技术栈”、“避坑指南”分次发送并在每次发送时强调其作用。或者只发送最关键、最通用的部分如技术栈和避坑指南将更具体的业务逻辑在需要时再作为补充上下文提供。 * **创建对话模板**你可以将这条“开场白核心SKILL.md”保存为一个文本片段或笔记每次开始新项目会话时快速导入避免重复劳动。 ### 4.2 动态引用与精准提示 在漫长的开发会话中AI可能会“忘记”早期提供的上下文或者在某些具体场景下需要特别提醒。 **场景一当AI的提议偏离技术栈时** * **你的需求**“帮我实现一个任务详情页的侧边栏显示任务历史记录。” * **AI的可能回复未充分结合上下文**“我们可以使用Chakra UI的VStack和Box组件来快速搭建...” * **你的纠正与提示**“请记住我们的项目技术栈规定不使用任何外部UI组件库见SKILL.md‘强制技术栈’部分。请使用纯Tailwind CSS工具类来构建这个侧边栏。另外历史记录的数据应该通过哪个Hook获取参考‘API交互模式’部分” **场景二当需要AI进行深度代码审查时** * **你的提示**“以下是我刚写的TaskList.tsx组件代码请根据SKILL.md中的‘性能禁区’和‘代码审查’约定对其进行严格审查指出所有问题并提供修改建议。” * **效果**AI会主动对照SKILL.md中的条款检查内联函数、不必要的计算、缺失的key等并提供符合项目规范的修改方案。 **场景三补充特定场景的细节** * 有时SKILL.md里可能没有涵盖某个非常具体的业务规则。你可以在对话中即时补充并声明这是对SKILL.md的更新。 * **你的提示**“关于任务分配补充一条业务规则到我们的SKILL.md上下文中当一个任务被标记为‘high’优先级时系统必须自动发送一条Slack通知到项目频道。相关的通知函数封装在/lib/notifications/slack.ts中的sendHighPriorityAlert函数里。请记住这条规则。” ### 4.3 效果评估与迭代更新 如何判断你的SKILL.md是否有效看以下几个信号 * **减少纠正次数**AI生成的代码第一次就符合项目规范的比例显著提高。 * **主动符合模式**当你提出一个需求时AI会主动说“根据项目规范我将使用Zustand来管理这个状态并用一个自定义Hook来封装API调用。” * **主动规避陷阱**AI在生成代码时会附带提醒“注意这里我使用了useMemo来避免在每次渲染时重新计算这个过滤列表。” * **提出有深度的问题**AI会基于对项目背景的理解提出更深入的问题如“这个新功能是否需要考虑任务状态单向流转的校验如果需要我们可以复用task-validator.ts中的逻辑。” 如果效果不理想就需要迭代SKILL.md 1. **定位问题**是AI完全忽略了某个规范还是对某个模式理解有偏差 2. **分析原因**是SKILL.md中描述得太模糊还是该规则与其他规则有潜在冲突 3. **更新文档**用更清晰、更强制性的语言重写相关部分。增加正反例子对比。 4. **重新“培训”**在后续对话中重点强调更新后的部分。 ## 5. 高级技巧与边界探索 当你熟练掌握了基础用法后可以尝试以下进阶技巧进一步释放“AI队友”的潜力。 ### 5.1 技能分层与模块化 对于大型复杂项目一个庞大的SKILL.md文件可能难以维护和高效利用。可以考虑将其模块化 * **SKILL_CORE.md**包含永远需要的基础信息如技术栈、代码风格、目录结构、核心设计模式。每次对话必带。 * **SKILL_FRONTEND.md / SKILL_BACKEND.md**根据你当前的工作重点前端或后端动态加载。 * **SKILL_FEATURE_X.md**针对某个复杂功能模块如“支付系统”、“实时协作”的详细规范在开发该功能时附加提供。 在对话中你可以这样引导“Claude我们先基于SKILL_CORE.md内容如下...。现在我们开始开发支付功能这是支付模块的特定技能SKILL_PAYMENT.md内容如下...请结合两者来协助我。” ### 5.2 结合项目源码的“增强学习” SKILL.md是书面规范而项目现有的源代码是最真实的“范例”。你可以通过让Claude Code分析现有代码来加深它对项目模式的理解。 **操作示例** 1. 选中一段体现项目良好模式的代码例如一个封装精美的自定义Hook useTasks.ts。 2. 在Claude Code聊天框中发送这段代码并提问“请分析这段 useTasks Hook总结它在数据获取、错误处理和缓存策略上是如何遵循项目最佳实践的” 3. AI的分析结果可以反过来提炼、补充到你的SKILL.md中形成“理论SKILL.md←→实践代码”的闭环。 ### 5.3 处理模糊需求与创造性任务 SKILL.md主要约束“如何做”但对于“做什么”的创造性任务它也能提供边界。 * **场景**“我们需要在任务卡片上添加一个视觉元素让用户能一眼看出任务是否已逾期。” * **AI的思考过程在SKILL.md约束下** 1. 约束检查不能引入新的UI库只能用Tailwind CSS和现有组件。 2. 模式检查任务卡片是TaskCard组件修改它。 3. 业务逻辑逾期判断需要基于ITask接口中的dueDate和当前时间。 4. 最佳实践颜色编码应保持一致性如逾期用红色参考“项目特定逻辑”。 5. 输出生成一个修改方案在TaskCard组件中添加一个根据dueDate计算是否逾期的函数并利用现有的PriorityBadge组件逻辑添加一个红色的“逾期”角标使用类似的样式工具类。 通过这种方式AI的“创意”被引导在项目既定的技术边界和设计语言内发挥产出物与项目整体风格高度一致。 ## 6. 常见问题与排错指南 在实际使用中你可能会遇到一些典型问题。以下是我踩过坑后总结的排查思路。 ### 6.1 AI似乎“忘记”或忽略了SKILL.md中的规则 * **症状**AI生成的代码使用了明确禁止的技术如直接用了fetch或违反了命名约定。 * **可能原因与解决** 1. **上下文丢失**对话过长早期的SKILL.md内容被挤出了AI的上下文窗口。**解决方案**开启一个新的对话线程重新加载SKILL.md核心部分。对于长周期任务定期在对话中简短重申关键规则如“提醒一下我们用的是Zustand和TanStack Query”。 2. **规则冲突或模糊**SKILL.md中的某条规则可能与其他通用编程知识或AI的内部训练数据冲突。**解决方案**用更绝对、更具体的语言重写规则。例如将“建议使用自定义Hook”改为“**禁止**在组件中直接使用fetch**所有**API调用**必须**通过/lib/api-client.ts中导出的自定义Hook发起”。 3. **提示词优先级不足**你的即时请求提示词没有明确要求AI参考规范。**解决方案**在提出具体编码需求前加上引导语“请严格遵循SKILL.md中的技术栈和规范实现以下功能...”。 ### 6.2 生成的代码质量不稳定时好时坏 * **症状**有时生成的代码完美有时却显得草率或包含低级错误。 * **可能原因与解决** 1. **需求描述不清**你的提示词过于简略或存在歧义。**解决方案**采用“角色-任务-上下文-输出”格式结构化你的提示词。例如“【角色】你是一位精通Next.js和TypeScript的资深前端工程师。【任务】请为TaskCard组件添加一个拖拽开始处理的回调。【上下文】该组件位于/components/task/TaskCard.tsx接收ITask类型的task prop和onDragStart: (taskId: string) void回调。项目使用HTML5 Drag API。【输出】请只给出修改后的组件代码关键部分并说明修改处。” 2. **SKILL.md信息过载或矛盾**文档内容太多、太杂或不同部分之间存在不一致。**解决方案**精简SKILL.md只保留最核心、最确定的规则。定期回顾和重构文档确保其内部一致性。 ### 6.3 如何衡量和提升SKILL.md的投资回报率ROI 投入时间写SKILL.md是否值得可以从以下几个维度评估 * **效率提升**对比使用SKILL.md前后完成一个典型功能如“创建带表单验证的任务创建模态框”所需的平均对话轮次和纠正次数。 * **代码一致性**随机抽查AI生成的代码检查其符合项目规范如目录结构、Hook使用、类型定义的比例。 * **心智负担减轻**你是否减少了在每次对话中重复解释基础技术栈和项目惯例的时间 要提升ROI关键在于**让SKILL.md保持活力和精准**。它不是一份写完后就被遗忘的文档。每当你发现一个需要反复向AI解释的模式或AI犯了一个重复性错误就立刻将其转化为一条清晰的规则补充到SKILL.md中。久而久之这份文档会成为你项目知识和团队经验的“数字大脑”而Claude Code就是这个大脑最得力的执行者。