1. 为什么你的 Claude Code 需要一套技能集
如果你已经在用 Claude Code 写代码，大概率遇到过这种场景：每次开新会话，都要把同一套要求重新说一遍——「注释用中文」「提交前检查有没有硬编码密钥」「前端别用那种一眼 AI 的紫色渐变」。说一次两次还行，说上几十次就纯属浪费生命。更麻烦的是，这些零散提示词散落在各个会话里，既没法版本管理，也没法分享给同事。
Claude Skills 就是来解决这个问题的。简单说，它是一套基于 Markdown 文件的技能扩展机制：你把某类任务的指令、检查清单、参考文档写进一个SKILL.md，放进指定目录，Claude Code 在遇到匹配任务时会自动加载并执行。它和普通提示词最大的区别在于按需加载——技能没被触发前，只有文件头部的一小段描述进入上下文；真正触发后，正文才被读取。这意味着你可以维护几十个技能，而日常会话的 token 开销几乎不增加。
这套机制适合谁？三类人最受益：一是长期用 Claude Code 做项目的独立开发者，想把个人习惯沉淀成资产；二是需要统一团队编码规范的 Tech Lead，把技能文件夹提交进仓库，新人克隆下来就自带同一套标准；三是经常处理重复任务（代码审查、上下文清理、文档生成）的人，把流程固化成技能后，一句话就能调用。
我试过把过去半年攒的提示词整理成技能集，最直观的感受是：以前靠记忆和复制粘贴维持的「工作流」，现在变成了可维护、可迭代、可共享的文件。下面从目录结构讲起，一步步带你搭出自己的技能集。
2. SKILL.md 目录结构与元信息：技能是怎么被识别和加载的
理解 Skills 的关键，是先搞清它的物理形态。一个技能就是一个独立文件夹，文件夹名通常用短横线命名（比如code-review），内部至少包含一个SKILL.md。复杂一点的技能还会带references/子目录，存放补充参考文档，比如设计规范、检查清单、示例代码。
~/.claude/skills/ ├── code-review/ │ ├── SKILL.md │ └── references/ │ └── security-checklist.md ├── frontend-design/ │ └── SKILL.md └── token-discipline/ └── SKILL.mdSKILL.md的结构分两部分：顶部的 YAML frontmatter 和下面的正文。frontmatter 目前最核心的两个字段是name和description。
--- name: code-review description: 对未提交的代码改动进行安全与质量审查，检查硬编码凭证、SQL 注入、XSS、命令注入、调试残留等问题。当用户要求审查代码、检查改动或提交前自查时使用。 --- # 代码审查技能 ## 审查流程 1. 先运行 git diff 获取未提交改动 2. 逐文件检查以下风险点...这里有个设计精髓值得展开：description 是 Claude Code 判断是否调用该技能的唯一依据。技能没触发时，只有这段描述进入上下文，正文完全不加载。所以 description 的写法直接决定技能能不能被正确命中。我的经验是，description 要同时包含「做什么」和「什么时候用」，把触发场景的关键词写进去，比如「当用户要求审查代码时」「处理前端界面时」「上下文接近上限时」。
正文部分则是技能被触发后才读取的指令集。它可以很长，可以包含步骤、检查清单、代码模板、甚至引用references/里的文档。因为只在触发时加载，你可以写得足够详细，不用担心日常开销。
加载时机上，Claude Code 会在两种情况下触发技能：一是它根据你的对话内容判断匹配某个 description，自动加载；二是你显式调用。自动触发依赖 description 的准确度，这也是为什么我建议每个技能的 description 都反复打磨——写得太窄会漏触发，写得太宽会误触发。
还有一个容易忽略的点：技能的作用域。放在~/.claude/skills/下是用户级，对你所有项目生效；放在<项目>/.claude/skills/下是项目级，只在该项目生效，而且可以提交到版本控制。团队协作场景下，项目级技能是统一规范的最佳载体——把code-review放进仓库，所有人克隆后自动获得同一套审查标准。
3. 可复制的技能集配置：从零搭一套自己的 Skills
这一节给你可以直接抄的配置。先规划一套最小可用的技能集，我建议从三个技能起步：一个管代码质量，一个管前端风格，一个管上下文纪律。这三个覆盖了日常最高频的重复需求。
先建目录。用户级技能放在家目录下：
mkdir -p ~/.claude/skills/code-review/references mkdir -p ~/.claude/skills/frontend-design mkdir -p ~/.claude/skills/token-discipline然后写第一个技能code-review/SKILL.md：
--- name: code-review description: 审查未提交的代码改动，检查安全漏洞与质量问题，包括硬编码凭证、SQL 注入、XSS、命令注入、IDOR、调试残留。当用户要求审查代码、检查改动、提交前自查或提到 code review 时使用。 --- # 代码审查 ## 执行步骤 1. 运行 `git diff --staged` 和 `git diff` 获取全部未提交改动 2. 对每个改动文件逐项检查： - 硬编码密钥、token、密码 - 拼接式 SQL 查询（应使用参数化） - 未转义的用户输入进入 HTML - 直接拼接的 shell 命令 - 越权访问风险（IDOR） - console.log / print 等调试残留 3. 按严重程度分级输出：严重 / 警告 / 建议 4. 每条问题给出文件、行号和修复建议 ## 参考 详细检查清单见 references/security-checklist.md第二个技能frontend-design/SKILL.md，重点解决「AI 味界面」问题：
--- name: frontend-design description: 生成或修改前端界面代码时使用，识别项目现有技术栈与设计 token，遵循已有配色、间距、字体规范，避免生成通用 AI 风格界面。 --- # 前端设计 ## 前置检查 1. 先读取项目中的 tailwind.config、theme 文件或 CSS 变量 2. 识别现有配色、圆角、间距、字体 3. 新组件必须复用已有设计 token，不引入新色值 ## 禁止项 - 不使用紫色到蓝色的渐变作为主视觉 - 不使用 emoji 作为图标 - 不生成居中的大标题加副标题的落地页结构 - 不引入项目未使用的 UI 库 ## 输出要求 组件代码需与项目现有风格一致，必要时先说明你识别到的设计 token。第三个token-discipline/SKILL.md，长会话必备：
--- name: token-discipline description: 长会话或上下文接近上限时使用，通过偏移读取、子代理、TodoWrite 等习惯减少 token 消耗，清理过期输出。 --- # Token 纪律 ## 习惯 1. 读取大文件时用偏移读取，不整文件加载 2. 探索性任务交给子代理，只把结论带回主会话 3. 用 TodoWrite 维护任务清单，避免重复描述上下文 4. 定期清理已完成的中间输出 ## 触发时机 当会话轮次超过 20 轮，或用户提到上下文、token、变慢时启用。如果你用 Claude Code 的配置文件管理模型接入，settings.json里可以这样写（把 Base URL、Key、Model ID 三件套配齐）：
{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_AUTH_TOKEN": "你的API Key", "ANTHROPIC_MODEL": "claude-sonnet-4-20250514" } }注意ANTHROPIC_BASE_URL填的是 API 地址，不带任何多余路径。Key 从控制台的 API Keys 页面生成，模型 ID 按你实际订阅的填。这三项配好，Claude Code 才能正常发起请求，Skills 机制也才有运行的基础。
技能集组织上，我的建议是：用户级放通用技能（审查、上下文纪律），项目级放业务相关技能（特定框架规范、内部 API 约定）。项目级技能随仓库走，团队共享；用户级技能跟人走，跨项目复用。两者不冲突，Claude Code 会同时扫描。
4. 验证技能生效：用 /skills 和对话触发确认加载
配置写完不代表生效，必须验证。Claude Code 提供了几种确认方式，我按从快到慢的顺序讲。
最直接的是斜杠命令。在会话里输入/skills，它会列出当前可用的技能。如果列表里没有你刚建的技能，说明目录位置或文件名有问题——先检查SKILL.md是否拼写正确（大小写敏感），再确认文件夹是否在~/.claude/skills/或项目级.claude/skills/下。改完文件后需要重启会话，因为技能列表在会话启动时扫描。
第二步是显式触发。直接说「用 code-review 技能审查一下当前改动」，如果技能被正确加载，Claude 会按SKILL.md里的步骤执行，先跑git diff，再逐项检查。你能从它的输出结构判断技能是否真的生效——如果它只是泛泛而谈而没有按你写的分级输出，说明正文没被加载。
第三步是验证自动触发。这是最关键的一环，因为它检验 description 的质量。开一个新会话，不提技能名字，直接说「帮我看看这次改动有没有安全问题」。如果 description 写得准，Claude 应该自动加载code-review并执行。如果没触发，回去改 description，把「安全问题」「审查改动」这类用户真实会说的词补进去。
验证请求是否真正打到模型，可以看返回。正常响应会包含choices字段（OpenAI 兼容格式）或对应的内容块。如果返回 401，说明 Key 无效或没带上；如果报local proxy failed，通常是 Base URL 配错或网络层拦截；如果报reading choices相关错误，多半是响应格式和预期不符，检查模型 ID 是否写对。
一个实测有效的技巧：故意在代码里埋一个硬编码的假密钥，然后触发审查技能。如果技能生效，它应该能准确指出这一行。这比看它泛泛输出「代码看起来不错」可靠得多。技能生效的标志不是它回复了，而是它按你定义的流程和标准回复了。
5. 常见报错排查：401、local proxy failed、reading choices 怎么解
技能不生效，问题往往不在技能本身，而在接入层。下面按真实报错逐个拆。
401 Unauthorized。这是最常见的。原因通常是 Key 没配、配错或过期。检查settings.json里的ANTHROPIC_AUTH_TOKEN是否和 API Keys 页面生成的一致，注意不要有多余空格或换行。如果你用的是环境变量方式，确认变量名拼写正确。还有一种情况是 Key 有权限范围限制，换一个全权限的 Key 测试。
local proxy failed。这个报错指向 Base URL 配置问题。ANTHROPIC_BASE_URL应该填https://taotoken.net/api，不要在后面加/v1或其他路径，也不要带尾部斜杠。如果你本地有网络层工具在拦截请求，也会出现类似报错，先确认请求能正常发出。配置改完记得重启 Claude Code，环境变量不会热加载。
reading choices 相关错误。这通常出现在响应解析阶段，说明返回的数据结构和客户端预期不一致。排查顺序：先确认模型 ID 是否有效，填一个不存在的模型名会导致返回异常结构；再确认 Base URL 指向的是兼容接口；最后检查是否有中间层改写了响应。把模型 ID 换成官方文档里明确列出的版本号再试。
OAuth 相关报错。如果你之前用账号登录方式配置过，又切换到 Key 方式，可能残留 OAuth 凭证导致冲突。清理旧的凭证缓存，重新用 Key 配置。Claude Code 的认证方式不要混用，选一种配到底。
技能列表为空。/skills什么都不显示，先确认目录层级：必须是skills/技能名/SKILL.md，不能是skills/SKILL.md。frontmatter 的---必须顶格写，前后不能有空格。YAML 格式错误会导致整个技能被跳过，用在线 YAML 校验工具过一遍。
技能触发了但没按流程走。说明 description 命中了但正文没加载，或者正文写得太模糊。检查SKILL.md正文是否有明确的步骤编号，指令越具体执行越稳定。把「检查代码质量」改成「运行 git diff 后逐文件检查以下 6 项」，效果差别很大。
排查时有个通用思路：先确认接入层通不通（能不能正常对话），再确认技能层加载没加载（/skills列表），最后确认触发层命中没命中（自动触发测试）。三层分开定位，比一股脑改配置高效得多。
6. 把技能集用起来：从单机到团队的落地路径
技能集搭好之后，怎么让它真正产生价值，而不是躺在目录里吃灰？分享几条我踩过坑之后的经验。
第一，技能要小步迭代，不要一次写十个。先写一个最痛的场景，用一周，发现 description 漏触发就改 description，发现流程有遗漏就补正文。技能文件是活的，不是一次写完就冻结的文档。我最初的code-review只有三行，现在长到带独立检查清单，全靠实际使用中不断补。
第二，项目级技能优先于用户级。团队协作时，把审查规范、框架约定放进<项目>/.claude/skills/并提交，比在群里发文档有效得多。新人克隆仓库，Claude Code 自动带上同一套标准，不需要额外培训。这是技能机制相比传统文档最大的优势——规范从「需要人记住」变成「工具自动执行」。
第三，description 是技能的门面，值得反复打磨。判断标准很简单：让一个不了解你技能集的同事，用他自己的话描述需求，看能不能触发。如果触发不了，说明 description 用的是你的内部术语，而不是用户的自然语言。把用户真实会说的词写进去。
第四，技能之间可以组合。比如token-discipline和code-review可以同时生效，一个管上下文，一个管质量。设计技能时保持职责单一，不要写一个「什么都能干」的巨型技能，那样 description 会失焦，触发率反而下降。
如果你还在用零散提示词，建议从今天开始，把最常用的那条提示词抽出来，写成第一个SKILL.md。目录建好，frontmatter 写清楚，正文列步骤，重启会话，/skills确认，然后故意触发一次验证。走完这一圈，你就有了第一块可维护的技能资产。后面每遇到一个重复场景，就沉淀一个，半年下来这套技能集就是你个人工作流的完整映射。
需要生成 API Key 或查看接入文档，可以从 API Keys 页面和控制台的接入文档入手；想先验证模型对话是否正常，用模型对话页面测一轮；如果打算长期做编码和 Agent 任务，Coding Plan 更适合持续使用。技能集是长期资产，接入稳定了，它才能持续发挥价值。
