1. 为什么每次开新对话都要重讲一遍规范如果你刚接触 Claude Code大概率经历过这种循环新开一个会话先把团队代码规范贴进去再补一句“用 TypeScript、函数加 JSDoc、变量 camelCase”然后才开始干正事。第二天换个会话同样的内容再贴一遍。贴到第三周你会开始怀疑自己到底是在写代码还是在做提示词搬运工。Claude Code Skills 就是冲着这个痛点来的。它是一套放在项目目录里的“知识包”由 Markdown 指令、脚本和参考资源组成Claude Code 会在需要的时候自动发现并加载。你不需要每次手动粘贴也不用把所有规范一次性塞进系统提示词。对刚上手 AI 编程工具的开发者来说判断要不要引入 Skills其实只需要回答一个问题你有没有反复输入同一类指令如果有Skills 就值得花两小时学。我试过把一套前端规范拆成 Skill 之后新会话里只说了句“按项目规范写个表单组件”Claude Code 就自动去读.claude/skills/下的规范文件产出的代码命名和注释风格跟团队要求基本一致。这篇文章会交付可复制的目录结构、SKILL.md 骨架以及在 Claude Code 里启用和验证 Skills 生效的完整步骤让你自己判断这套机制是否适合当前项目。2. Claude Code Skills 是什么和普通提示词差在哪先把概念说清楚。Skills 的本质是一个文件夹里面至少有一个SKILL.md。这个文件分两部分顶部是 YAML 元数据声明技能名称和“什么时候该用我”下面是正文指令写清楚具体怎么做。Claude Code 启动时会扫描所有技能的元数据每个只占很少的 token只有当它判断当前任务和某个技能描述匹配时才会把完整的 SKILL.md 读进来。这个机制叫渐进式披露是 Skills 省上下文的关键。和传统提示词的区别可以用一张表对照维度传统提示词Claude Code Skills持久化每次会话重新输入配置一次长期生效加载方式全量塞进上下文按需分级加载团队协作各自维护随 Git 仓库共享版本管理难以追踪纳入版本控制初始 token 占用高低仅元数据举个具体例子。假设你有一段 500 token 的写作规范每天开 5 次新会话一周就是 17500 token 的重复消耗。做成 Skill 之后初始只加载约 100 token 的描述真正写文章时才把正文读进来。技能越多这个差距越明显。需要强调的是Skills 不是替代斜杠命令或 MCP 的东西它们解决的是不同层面的问题。斜杠命令偏向“手动触发一个动作”MCP 偏向“连接外部工具和数据源”而 Skills 偏向“让 Claude 在合适的时候自动获得一套领域知识”。三者可以共存后面排障章节会讲怎么区分使用场景。3. 可复制的 Skills 目录结构与配置骨架这一节直接给能用的东西。Claude Code 默认从项目根目录的.claude/skills/下查找技能每个技能一个子目录目录名建议用 kebab-case。一个带参考资源和脚本的完整结构长这样your-project/ ├── .claude/ │ └── skills/ │ └── coding-standards/ │ ├── SKILL.md │ ├── references/ │ │ ├── naming-conventions.md │ │ └── error-handling.md │ └── scripts/ │ └── lint-check.py ├── src/ └── package.json最简版本只需要SKILL.md一个文件。下面是一个可以直接复制的骨架注意 YAML 元数据必须放在文件最顶部用三条短横线包起来--- name: coding-standards description: 当编写或修改 TypeScript 代码时使用此技能确保命名、注释和错误处理符合团队规范。 --- # TypeScript 代码规范 ## 命名约定 - 变量和函数使用 camelCase - 类型和接口使用 PascalCase - 常量使用 UPPER_SNAKE_CASE ## 函数要求 - 每个导出函数必须有 JSDoc 注释 - 单个函数不超过 50 行 - 必须处理可能的错误分支 ## 参考文件 命名细节见 [naming-conventions.md](references/naming-conventions.md) 错误处理模式见 [error-handling.md](references/error-handling.md)description这一行非常关键它决定了 Claude Code 什么时候会想起这个技能。写法上要包含“触发场景”比如“当编写 TypeScript 代码时”而不是只写“代码规范”。名称和描述都会进入初始扫描所以描述要精准但别太长。如果你用的是支持 MCP 的客户端配置或者需要把 Skills 相关服务接入统一网关可以在项目里放一份settings.json把模型和接入地址固定下来。下面这份配置里的 Base URL 和 Key 需要替换成你自己的{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的密钥, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }这里三件套要写全Base URL、API Key、Model ID。少任何一个请求都会失败。Key 可以在控制台的 API Keys 页面生成接入文档里有各客户端的详细字段说明。把配置放在项目级而不是全局团队其他人克隆仓库后改一下自己的 Key 就能用同一套 Skills。4. 在 Claude Code 中启用并验证 Skills 生效目录建好之后启用本身不需要额外命令Claude Code 会自动扫描.claude/skills/。真正要做的是验证它有没有被加载、有没有在正确时机触发。下面是我实测下来比较稳的验证流程。第一步确认文件位置和命名。技能目录必须在项目根目录的.claude/skills/下SKILL.md大小写要完全一致。放错层级是最常见的“技能不生效”原因。第二步启动 Claude Code 并观察初始加载。在项目根目录执行claude启动后可以先问一句和技能无关的普通问题比如“这个项目用什么包管理器”此时技能正文不应该被加载只有元数据在扫描范围内。第三步触发技能。输入一个明确匹配 description 的请求帮我写一个 TypeScript 函数把用户列表按注册时间排序。如果配置正确Claude Code 会识别到 coding-standards 的描述匹配读取完整 SKILL.md然后按里面的命名和注释规范产出代码。你可以检查输出里函数名是不是 camelCase、有没有 JSDoc、有没有错误处理分支。第四步用显式指令做对照测试。如果自动触发不稳定可以手动点名请使用 coding-standards 技能重写上面这个函数。手动点名能触发说明技能文件本身没问题只是 description 的匹配度需要调整。把 description 改得更贴近你的实际提问措辞通常就能解决。第五步检查参考文件是否被按需读取。在 SKILL.md 里引用了references/naming-conventions.md之后提一个涉及命名细节的问题观察 Claude 的回答是否引用了该文件里的具体规则。这一步能验证三级加载是否正常工作。验证通过后你可以把同样的结构复制到团队仓库让新成员克隆即获得全部规范。需要长期跑编码任务或 Agent 流程的话Coding Plan 这类按周期计费的方式会比反复开新会话更省心具体可以在官网的 coding-plan 页面看当前方案。5. 常见报错排查401、技能不触发、OAuth 失败这一节按真实遇到的报错来对照都是接入阶段高频问题。401 未授权。表现是请求直接被拒日志里出现401 Unauthorized。原因通常是 API Key 写错、过期或者 Base URL 和 Key 不属于同一套环境。排查顺序先确认ANTHROPIC_API_KEY没有多余空格再确认ANTHROPIC_BASE_URL填的是https://taotoken.net/api最后去控制台重新生成一个 Key 替换测试。三件套里 Key 和 Base URL 必须配套。技能完全不触发。表现是无论怎么提问Claude 都像没看到技能一样。先检查目录层级必须是项目根/.claude/skills/技能名/SKILL.md。再检查 YAML 元数据三条短横线必须在文件第一行name和description不能缺。最后检查 description 是否太泛比如只写“代码相关”改成“当编写 TypeScript 代码时使用”这种带场景的表述。local proxy failed。表现是连接本地代理失败。这类报错通常和客户端里配置了本地转发端口有关。检查你的客户端设置把代理相关字段清空直接使用 Base URL 直连。如果之前配过其他工具的转发规则也要一并确认没有残留。reading choices 相关报错。表现是解析响应时读不到choices字段。这多半是请求发到了不兼容的接口路径或者 Model ID 填错导致返回结构异常。确认ANTHROPIC_MODEL是有效模型名并且请求走的是 Anthropic 兼容格式而不是 OpenAI 格式。OAuth 相关失败。表现是登录或授权环节报错。如果你用的是 API Key 方式接入就不应该再走 OAuth 流程两者选其一。检查配置里是否同时存在 OAuth token 和 API Key冲突时优先保留 Key 方式把 OAuth 相关字段移除。CC Switch / Cline MCP / Codex auth.json 场景。如果你在这些工具里接入同样要写全三件套Base URL、Key、Model ID。以 Codex 的auth.json为例字段名要和工具要求一致缺一个都会导致鉴权失败。Cline 的 MCP 配置里Base URL 填https://taotoken.net/apiKey 填生成的密钥Model ID 填你实际要用的模型。CC Switch 切换配置时确认切换后的那套三件套是完整且匹配的。排查时有个通用思路先确认鉴权层401/OAuth再确认路径层local proxy/choices最后确认技能层目录/元数据/description。按这个顺序走大部分问题能在十分钟内定位。6. 什么时候该引入 Skills以及下一步怎么走判断标准其实很朴素。如果你或团队存在下面任意一种情况Skills 的投入产出比就很高同一段指令每周重复输入三次以上团队代码风格靠口头约定、review 时反复纠正新人入职要花大量时间问“我们规范是什么”某些复杂流程用几句话说不清楚、需要配参考文档。反过来如果只是偶尔用一次 AI 写个脚本那手动贴提示词完全够用不必为了用而用。落地路径建议这样走先挑一个最痛的场景比如代码规范按第 3 节的骨架建一个技能用第 4 节的流程验证生效。跑通一个之后再把文档模板、部署流程这类内容逐步拆成独立技能。每个技能的 description 都要写清楚触发场景这是自动加载能否命中的关键。需要生成新 Key 或查看接入字段去控制台的 API Keys 页面各客户端的完整配置示例在接入文档里想先验证模型对话效果可以直接用模型对话页面试几轮。如果打算把 Skills 用在长期编码或 Agent 工作流上Coding Plan 的按周期方式比反复开新会话更稳定。把第一个技能跑通你就知道这套机制值不值得继续投入了。