说实话Claude Code 刚推出的时候我更愿意把它当成一个能跑在终端里的聊天机器人直到有一天我用它写一个中等规模的前端项目反复在对话里粘贴了三遍同样的设计规范它依然给我生成完全不符合要求的排版我意识到单纯把话说清楚真不够。后来 Claude Code 的扩展机制里加入了 Skills我把项目里那些“做事方法”固化成了技能包同一套前端开发 skills 在几个仓库里测试下来AI 生成的质量稳定性提升得很明显。这篇文章不打算做成官方文档的翻译而是从一个实际使用者的角度聊聊 Claude Code 的 Skills 到底怎么工作怎么自己写一个可复用技能以及怎么用最新的 API 把 AI 项目做得更可靠。1. Claude Code 的 Skills 到底解决了什么问题1.1 一个让大多数团队头疼的痛点重复交代上下文我见过很多团队用 AI 写代码抱怨最多的不是“它写不出来”而是“它每次都要重新教”。产品经理给需求AI 开工前你得先说项目背景换一个需求又说一遍下次开新会话再说一遍。如果团队里有多个成员同时用每个人话术的差异都会导致产出风格不一致。在没有 Skills 之前大家常用的解决办法是把规范写进 CLAUDE.md。这个方法有效但存在一个很现实的问题CLAUDE.md 会越写越长。当文件涨到几万字模型每次处理主任务前都得把这些内容读一遍对长上下文模型来说影响可能不明显但放进 token 消耗里就是实打实的成本而且大量背景文字混进注意力里反而会干扰当前任务。Skills 的解决思路完全不同。它把“完成某一类任务的标准做法”拆成独立文件放进项目的 .claude/skills 目录。Claude Code 在执行任务时会根据技能描述做语义匹配只有匹配到当前任务才会把对应技能文件加载进上下文。换句话说技能不是常驻规则而是按需翻阅的工作手册。这套设计对真实项目的价值在于你可以把几十个不同领域的技能同时放在仓库里比如前端开发、数据库 Review、API 调试、数学建模、测试用例生成而单次任务只会激活其中的一两个。模型不需要为无关技能浪费时间也不需要在冗长的项目说明里大海捞针。1.2 Skills 和 CLAUDE.md、Subagent、普通提示词的真正分工这几个概念经常被混在一起实际上的分工非常清晰机制是否常驻生活化类比最适合放的场景CLAUDE.md常驻团队规章制度项目背景、通用代码风格、构建命令Skills按需触发菜谱/工作手册某类任务的完整做法、实现步骤、检查单Subagent运行时创建外包专家需要并行探索、独立思考的子任务普通提示词仅当前会话口头吩咐一次性需求、临时变更我猜你会问既然有 CLAUDE.md为什么还要 Skills因为两者解决的问题维度不同。CLAUDE.md 回答的是“这个项目是什么我们有什么约定”Skills 回答的是“遇到这类问题应该怎么一步步做”。做个类比厨房里贴着一张卫生规范厨师永远不会把鱼香肉丝的做法贴在墙上。需要做这道菜的时候他打开菜谱按步骤来做完之后菜谱也不会干扰下一道菜。Claude Code 的 Skills 就是这个菜谱平时存在目录里点菜时才翻出来。2. 拆解 Skills 的内部工作逻辑一份 SKILL.md 是如何被加载和调用的2.1 约定的目录结构与命名规则先看实际的目录结构。一个标准技能放在项目根目录或者用户级目录下.claude/ skills/ frontend-dev/ SKILL.md examples/ todo-list.tsx scripts/ check-design.js技能以目录为单位每个技能目录下至少要有一个 SKILL.md 文件。目录名建议用简短的小写连字符命名比如 frontend-dev、sql-review、api-fetch因为这个名字会出现在命令和匹配结果里。SKILL.md 里完整定义了技能名称、触发描述、使用步骤、代码规则等等。如果你希望某些技能对所有项目通用可以放到用户级目录大多数系统在用户主目录下的 .claude/skills项目级目录则放在仓库里随代码走。我的习惯是个人通用的偏好看用户级团队标准流程放项目级这样既能保证个人效率又能让团队规范随仓库分发。有一点要提前说明不同版本对技能加载路径的默认支持范围有差异配置前最好先看一下对应版本的文档或者用 /status 和环境变量确认当前的 skills 加载状态。我自己踩过配置了路径但始终不生效的坑最后发现是版本还不支持某一级目录。2.2 SKILL.md 的 frontmatter 字段逐项说明SKILL.md 的核心结构分两部分YAML frontmatter 和 Markdown 正文。frontmatter 是给 Claude Code 框架用的正文是给 Claude 模型用的。一个最简例子--- name: frontend-dev description: 当用户需要根据设计稿实现或修改前端页面时使用覆盖组件拆分、样式规范、响应式处理和浏览器兼容性检查。 allowed-tools: - Read - Edit - Bash --- # 前端开发技能 ## 任务目标 在收到前端开发需求时按照标准流程完成页面实现。 ## 具体步骤 1. 先读取项目根目录的 package.json确认框架与依赖版本。 2. 检查现有组件结构优先复用公共组件。 3. 按设计稿拆分组件遵循团队命名规范。 4. 使用 CSS Modules 或 Tailwind 实现样式。每个字段都有它的意义name技能的唯一标识尽量和目录名保持一致。description这是最关键的字段。Claude 不会把所有技能都加载进来而是根据 description 判断当前任务是否与此相关。description 写得太宽泛模型容易误触发写得太狭窄又可能漏触发。我的经验是描述里至少包含触发场景、适用对象、大致步骤范围不要用一句“处理前端开发”这种模糊话。allowed-tools限制技能执行时能用哪些工具能有效防止一些不稳定操作也能减少误用范围。model可选不少技能实现里还可以指定倾向的模型参数比如是否允许使用更贵的推理模型或强制使用快速模型。metadata可选放一些自定义字段比如版本号、维护人、更新时间方便团队排查。2.3 description 是触发机制的灵魂很多第一次接触 Skills 的人都会问Claude 怎么知道什么时候加载哪个技能答案藏在 description 里。Claude Code 会把技能列表中每个 description 暴露给模型模型结合当前用户请求做语义匹配类似“检索-增强”的逻辑。匹配到之后模型才会打开对应 SKILL.md读取内部操作步骤。所以 description 写得越像“实际任务描述”触发越准。举个例子错误写法description: 前端开发相关的技能。正确写法description: 当用户需要基于设计稿创建或修改 React 页面包括组件拆分、样式适配、响应式布局和访问性检查时使用。若只是问一句“这段代码为什么报错”不需要触发。最后一句尤其重要。它告诉模型“别动不动就打开这个技能”能显著降低误触发概率。我见过不少团队把 description 写成了功能清单结果模型经常在写 SQL 的时候打开前端技能非常尴尬。2.4 和 CLAUDE.md 配合时最容易犯的错为了把项目记忆和能力库分开我建议按照以下原则分配内容放 CLAUDE.md项目背景、技术栈、团队目录约定、通用命名规范、常用命令。放 Skills某类任务从开始到完成的完整方法、内置模板、质量检查单、错误处理流程。最常见的错误是写完一个技能后顺手把技能内容又复制一份进 CLAUDE.md。这样既不节省 token还会让匹配逻辑变混乱。技能该做的职责是“按需加载”你把它常驻之后不仅失去了按需加载的优势还会让模型在无关任务里也受到这份内容的暗示。3. 从零搭建一套可复用的 Skills 工作区3.1 安装 Claude Code 并完成最基础配置如果你还没装 Claude Code常规做法是通过 npm 全局安装npm 和 Node.js 环境是最常见的前提条件。安装完成以后第一次启动会要求完成认证这个环节可以设置对应的 API 密钥密钥会保存在本地配置里。npm install -g anthropic-ai/claude-code claude启动后可以用斜杠命令快速了解状态/status查看当前配置、模型、目录、认证信息/config打开配置文件设置默认模型、最大思考预算等/skills查看当前项目或用户目录下已加载的技能列表。我在新环境里拿到一个项目第一步永远是先跑一次 /status确认 API 密钥和 base URL 指向正确再往下走。很多人上来就写技能最后发现根本没调用到多半就是配置链路没通。如果你习惯在 IDE 里使用终端技能机制和 CLI 保持一致项目目录里的 .claude/skills 同样会被识别不需要额外做两套配置。3.2 创建一个前端开发 skills 的完整实操现在走一遍完整的创建流程。这里以团队里最常用的“前端开发技能”为例。第一步在项目根目录创建技能目录mkdir -p .claude/skills/frontend-dev第二步创建 SKILL.md 并填入内容。前端开发技能的正文我建议至少包含这几块项目读取、组件规划、代码风格、质量检查、完成标准。--- name: frontend-dev description: 当用户需要实现或修改前端页面时使用包括读取项目结构、拆分组件、编写样式、响应式适配和浏览器兼容检查。适合 React、Vue 等主流框架。 allowed-tools: - Read - Edit - Grep - Bash --- # 前端页面开发标准流程 ## 1. 开工前 - 读取 package.json确认依赖和框架版本。 - 搜索现有公共组件避免重复造轮子。 - 确认是否已存在相关样式变量和设计 token。 ## 2. 组件划分 - 按页面区块拆分子组件每个文件职责单一。 - 组件命名采用 PascalCase文件名与组件名一致。 ## 3. 样式规则 - 优先使用团队现有样式方案如 Tailwind / CSS Modules / Less。 - 颜色、间距、字号必须引用设计 token不要硬编码。 - 移动端优先验证 375/768/1280 三档宽度表现。 ## 4. 完成清单 - 无浏览器控制台报错。 - 无未使用的 import 和样式。 - 关键交互有状态反馈。 - 可通过项目内 lint 检查。内容不需要写得像论文。技能的目的不是“好看”而是让 Claude 在具体任务里能直接照着做写得越有操作性结果越稳定。第三步保存后在对话里验证。你可以给一个明确任务按照 frontend-dev 技能的标准帮我把首页的移动端适配问题修一下。如果技能被正常加载Claude 通常会先按技能里的步骤做前期检查然后在回答里体现“读取 package.json”“检查公共组件”这类动作。我在调试阶段常用 /skills 看技能是否被识别再通过对话判断触发是否生效。3.3 技能没被触发时的强制方案如果明明目录正确、文件也写了技能却从没弹出过先从这几个方向排查确认技能路径是否在支持范围里项目级、用户级路径别放错确认 description 是否和当前任务能对上语义确认是否有缓存或旧版本导致配置没生效必要时重启会话如果不着急自动触发也可以在任务描述里直接点技能名比如“使用 frontend-dev 技能”。我遇到过一种比较隐蔽的情况技能里用了 allowed-tools但实际运行时用到的工具不在允许列表里结果 Claude 反复尝试绕过或者直接报错。解决方法很简单把技能里肯定会用到的工具都列进去宁可多放 Read、Grep、Edit 这类安全和编辑工具也别图省事只放两个。4. 在 Skills 中封装 API 请求把数据能力和提示词解耦4.1 为什么“靠模型记忆写代码”的 AI 项目不靠谱聊完技能本身进入标题里另一个关键主题API。很多 AI 项目做不好的原因不是模型不够聪明而是上下文里的信息根本不可靠。模型记忆是静态的它不知道你当前的第三方 API 返回了什么结构、认证是否过期、某个字段是否已经改名最多只能根据训练数据里的印象给一段“看起来合理”的代码。正确做法是把 API 调用做成可执行的技能。技能里写好请求模板、鉴权方式、错误分类和结果解析Claude 面对任务时按步骤执行而不是凭空臆想。这样一来无论是写页面拉数据、调用大模型服务还是对接股票数据接口结果都来自真实请求而不是猜。4.2 设计一个带错误处理的 API 调用技能以“获取外部数据”这种通用任务为例在 .claude/skills/api-fetch 下创建 SKILL.md内容里把请求路径、headers、错误码和重试逻辑都写清楚。--- name: api-fetch description: 当用户需要从外部 REST API 获取数据、排查接口错误或根据接口文档生成请求代码时使用。包含请求模板、认证头、超时设置和错误状态码解析。 allowed-tools: - Bash - Read - Write --- # 外部 API 调用标准流程 ## 1. 确定请求参数 - 确认端点 URL。 - 确认请求方法。 - 确认是否需要认证头认证所需的密钥必须从环境变量读取不要写进文件。 ## 2. 构造请求 优先使用 curl 验证成功后再翻译成项目代码。 bash curl -sS -X GET https://example.com/api/v1/items \ -H Authorization: Bearer $API_TOKEN \ --max-time 103. 错误分类401认证失败检查密钥和权限范围。403有密钥但无权限检查授权角色。429限流等待重试或退避。5xx服务端错误重试两次后再放弃。这里有一个真实项目里很关键的做法密钥一律从环境变量读取绝对不要写死在 SKILL.md 里。因为技能文件很可能进版本库一旦写死密钥等于把凭证公开在所有协作者手里。 提示技能里凡是涉及身份验证的部分正文只写“从 $API_TOKEN 这类环境变量读取”不出现真实值。 ### 4.3 我踩过的坑401 unauthorized / incorrect api key provided 在把 Skills 和 API 结合起来的过程中我遇到最多的一类问题就是身份验证失败。报错很可能长这样 text unexpected status 401 unauthorized: incorrect api key provided遇到这种问题我的排错顺序是固定的先确认环境变量是否真的被加载。可以在终端执行 echo $API_TOKEN看看输出值和配置页里是否一致。不要只看前几位要核对完整内容。检查密钥前后是否存在多余空格、换行或引号。这个坑极其隐蔽尤其从网页复制密钥时末尾经常带个看不见的换行。确认用的是有效凭证而不是过期副本。很多服务商在后台重新生成密钥后旧密钥会立刻失效而项目配置里往往还留着旧值。看错误信息中返回的密钥前缀。如果类似 sk-abc**** 这种脱敏信息排查时特别容易误判你以为是对的其实可能是同一账号下的另一把密钥。可以拿报错信息里的前缀去后台核对。完成以上排查后再用一次临时调试命令验证curl -sS -o /dev/null -w %{http_code} \ -H Authorization: Bearer $API_TOKEN \ https://example.com/api/v1/ping返回 200 说明链路正常技能文件里大概率是请求写法问题还是 401 就继续查密钥本身。这个排查链路我写进了技能文档团队里其他人遇到 401 时不再需要反复问人直接照单执行。4.4 多 API 的统一管理思路如果一个技能里要用到多种 API我建议做三层隔离环境变量层不同 API 的密钥放在系统环境变量或本地环境管理文件里文件名加进 .gitignore技能文档层SKILL.md 里只写“从环境变量读取哪个密钥”不写具体值执行请求层优先用 curl 验证原始接口再生成项目内代码。这样即使技能文件被复制到别的项目里也不会泄露任何凭证。更重要的是当接口新增字段时你只需要改技能文档所有项目都能同步受益不用反复让 AI 猜接口格式。5. 把 Skills 接到模型服务和调试链路里真正提高可靠性5.1 连接本地模型或兼容服务时Base URL 的配置细节最近很多人在尝试让 Claude Code 调用本地模型服务比如 LM Studio 或 Ollama 这类工具提供的兼容接口。这个需求很实际有些场景不想把代码库传到云端或者想反复调试接口又不消耗外部配额。配置的核心思路是修改 API Base URL 和模型名让它指向兼容端点。在环境配置里设置类似这样的值具体变量名以当前产品文档为准export ANTHROPIC_BASE_URLhttp://127.0.0.1:11434/v1 export ANTHROPIC_MODELyour-local-model-name例如 Ollama 默认监听本地 11434 端口LM Studio 通常提供自己的本地服务端口。配置完以后再用 /status 检查实际生效的设置确保两个变量都被正确读取。这里有一个容易踩的坑本地模型的上下文窗口、函数调用能力和工具支持情况差异巨大SKILL.md 里如果写了很多依赖高级工具特性的操作普通模型执行时可能直接跳过或者报“工具不存在”。所以如果主要配合本地模型使用技能内容最好写得朴素一点减少对复杂工具链的依赖多给对方明确的文本步骤。5.2 上下文超长报错与 token 治理另一个让项目走向崩塌的问题是上下文无节制增长。我见过类似“this models maximum context length is 1048576 tokens”的报错这类信息的实质是你发给模型的累计 token 数超过了当前模型最大上下文长度。1048576 是个很大的数字也就是 1M token但真超限也没那么难。最常见的情况是长期会话没有清理、把大量日志全部丢给模型、或者技能文件本身写得极其冗余。每次请求都把这堆内容重新算一遍总有一天会撞墙。我的建议长期任务定期开新会话把必要背景写进 CLAUDE.md而不是靠聊天记录续命技能文件控制在“能说完步骤就行”的长度别把整个项目文档塞进去遇到 400 报错时先降低单次请求体量把日志分批处理在命令行工具里开启 verbose 或 debug 模式观察到底是谁吃掉了 token。5.3 团队协作把技能当代码一样管理当技能从个人工具变成团队资产管理方式也要跟着升级。我在团队里推广的流程是skills 目录纳入版本库和代码一起 review每个技能创建时写清楚 metadata包括维护人和适用版本修改技能后必须同步更新 description确保触发语义和实际行为一致禁止在技能文件里提交任何密钥、令牌、内部地址。团队里最常发生的问题不是没人写技能而是写了技能之后没人维护技能内容和实际项目规范脱节。解决办法是每隔一两个迭代把技能清单拉出来对一遍过时内容直接删比留着让模型误触发好得多。5.4 给技能写自测清单说一个我自己一直在用的方法每个技能文末加一节“自测清单”用于验证技能是否可用。前端技能的自测可能是“生成一个带响应式的卡片组件并跑 lint”API 技能的自测可能是“请求一个已知字段并检查解析结果”。这本质上是让技能自己也具备可测试性。有了自测清单哪怕技能是三个月前写的也能很快判断它是否还能正常工作。它跟单元测试的区别是不需要写代码但要写得足够具体让模型可以照着执行。6. 用了一阵子之后我想告诉你的几件事6.1 千万别把技能当“全部提示词仓库”Skills 最大的价值是按需加载很多人却把它当成又一个提示词收藏夹什么内容都往里塞。结果是技能文件越来越大匹配越来越不准最终退化成一份低效的 CLAUDE.md。我的原则很简单一个技能只解决一类任务超出范围的内容拆成新技能。6.2 从社区优秀技能包里能学到什么社区里已经有不少高质量的技能合集比如一些开发者公开维护的 superpower 风格技能包里面包含了几十个细粒度的小技能。有人专门整理数学建模相关的技能集有人做测试开发场景的技能包还有人把数据抓取和图表生成做成了完整工作流。我学习它们的重点不是直接照搬而是看它们怎么划分任务边界、怎么组织操作步骤、怎么写 description 避免误触发。尤其是一些做得好的技能会连“什么时候不要用”都写进描述里这种克制非常值得借鉴。如果你刚开始不知道从哪里下手可以先查一下当前目录下是否已经存在类似技能再决定是新建还是改造。一个项目里的技能数量不是越多越好覆盖到你的真实高频任务就够了。6.3 三个最容易踩的坑最后集中提醒三个高频问题description 模糊导致技能乱触发解决方法是把“不要用”的场景写进去allowed-tools 太严格导致执行失败解决方法是先做一次实跑再收紧把密钥写进技能文件这个没有悬念一定要用环境变量。我自己现在的工作流已经稳定下来项目根目录放 CLAUDE.md 约定通用规则.claude/skills 下面放着前端开发、API 调用、测试生成等七八个技能每次开新项目只需要把这一套目录复制过去再略作调整就能保持同样的质量基准。相比最初靠对话来回拉扯的生产方式这套方案的确定性高得多。如果你是刚接触 Claude Code不用一上来写几十个技能先把一个你最痛的真实任务固化成技能跑通一次你会发现后面所有事情都顺了。