1. 为什么你的 Claude Code 越用越“笨”从上下文膨胀说起如果你用 Claude Code 超过两周大概率会遇到一个诡异现象刚开始它挺聪明改个 bug、写个组件都利索可随着你在项目里越用越久它开始答非所问明明问的是一个小问题它却扯出一堆无关规范甚至把三个月前定下的日志格式又背一遍。这不是模型退化了而是你的上下文被“常驻信息”撑爆了。我见过太多团队把 CLAUDE.md 当成万能收纳箱API 命名规范、错误码表、PR review 清单、上线检查步骤、SAP Commerce Cloud 的 storefront 构建流程、Angular 项目的 npm ci 规则、ABAP RAP 的行为定义注意事项全塞进去。结果就是 Claude 每一轮对话都背着这几千字走路哪怕你只是问“这个变量为什么是 undefined”。上下文窗口被无关信息占满token 成本上升还是小事真正的问题是模型注意力被稀释判断质量肉眼可见地下滑。Claude Code Skills 就是为解决这个问题设计的。它是什么一句话一套可以被 Claude Code 按需拿出来阅读和执行的工作手册。它既不是单纯的提示词模板也不是传统插件而是一个包含SKILL.md的文件夹里面可以放元数据、说明、脚本、参考资料和模板。适合谁适合所有在真实项目里反复处理“半结构化任务”的开发者——比如每次改 checkout 逻辑都要检查 OCC API 返回结构、B2B cart 权限、Spartacus facade 调用链每次写 RAP unmanaged 行为池都要检查锁、draft table、late numbering。这些任务靠临时 prompt 能做但质量会漂移沉淀成 SkillClaude Code 就多了一项稳定能力。核心机制叫progressive disclosure渐进披露会话开始时Claude 只看到所有 Skill 的名字和描述等当前任务匹配某个 Skill或者你手动输入/skill-name调用它时完整的SKILL.md才进入当前对话。平时只把“哪本手册讲什么”放在桌上真要排查问题时才把对应那本翻开。这就是它和 CLAUDE.md 最本质的区别——CLAUDE.md 是墙上永远贴着的制度Skills 是抽屉里的专项手册。下面我会从SKILL.md的文件结构、subagents 协作配置、到一次真实任务的验证步骤把“按需加载”这件事讲透让你能直接照着搭一套自己的 Skill 体系。2. SKILL.md 目录结构与 description 写法决定 Claude 会不会找对工具很多人第一次写 Skill主体说明写了两千字description却随手一句“处理数据”“帮助 review”。这是最致命的错误。Claude Code 的自动选择机制完全依赖 description 判断当前任务是否相关描述模糊或互相重叠它就会加载错 Skill或者干脆错过真正有用的那个。先看目录结构。一个标准的 Skill 就是一个文件夹核心是SKILL.md其余是可选资源.claude/ └── skills/ ├── commerce-cart-debug/ │ ├── SKILL.md # 主体工作流 元数据 │ ├── reference/ │ │ ├── b2b-cart.md # B2B 场景参考按需读取 │ │ └── asm-403.md # ASM 403 排查参考 │ └── scripts/ │ └── check-cart-guid.sh ├── rap-behavior-review/ │ ├── SKILL.md │ └── reference/ │ └── draft-table.md └── api-style-guide/ └── SKILL.mdSKILL.md顶部是 YAML frontmatter这是元数据区也是 Claude 决定“要不要用你”的唯一依据--- name: commerce-cart-debug description: 用于排查 SAP Commerce Cloud Composable Storefront 的购物车问题覆盖 anonymous cart、cart guid 丢失、登录后 cart merge 失败、checkout 前 validation 报错、ASM impersonation 下 cart 返回 403。当用户提到购物车丢失、cart 未合并、checkout 卡住时使用。 allowed-tools: Read, Grep, Bash ---注意description的写法它同时说明了做什么排查购物车问题和什么时候用提到购物车丢失、cart 未合并、checkout 卡住时并且塞进了具体触发关键词。Anthropic 的 Skill authoring best practices 明确建议这样做因为 Claude 可能从大量可用 Skills 中挑选description 必须提供足够信息帮它区分。对比一下错误示范和正确示范写法description 内容后果错误帮助 review 代码和 security-review、performance-review 抢任务Claude 乱选错误项目规范太泛几乎任何任务都可能误触发正确检查 REST API 命名、错误响应结构、分页参数、鉴权头、OData 过滤在新增或修改 API endpoint 时使用触发边界清晰只在 API 相关任务激活正确排查 SAP Commerce Cloud checkout、cart validation、payment step、B2B approval flow、Spartacus storefront 调用链当 checkout 报错或订单无法提交时使用场景具体关键词命中率高主体正文不要写成百科。Agent 不需要欣赏文章它需要知道下一步怎么做、何时查哪个文件、遇到分支怎么判断、输出长什么样。推荐的结构是“目录式概览 分支指引”## 工作流 1. 定位 storefront 中 cart service 和 OCC adapter 的调用位置 2. 检查当前用户状态anonymous 还是 logged-in 3. 读取 session storage 中的 cart guid确认是否为空 4. 检查 HTTP request 和 interceptor确认 cart guid 是否正确透传 5. 若涉及 B2B读取 reference/b2b-cart.md 6. 若返回 403 且涉及 ASM读取 reference/asm-403.md ## 输出格式 - 问题定位一句话说明根因 - 证据列出关键文件路径和行号 - 修复建议具体到改哪个文件、加什么判断当主体接近 500 行时就该拆分内容把大段参考资料移到单独文件让 Claude 需要时再读。这就是 progressive disclosure 的第二层不仅 Skill 本身按需加载Skill 内部的参考文件也按需读取。3. subagents 协作配置预加载 Skill 的正确姿势Skills 在主会话里是按需加载但到了 subagents规则变了。Claude Code 的 subagent frontmatter 里有一个skills字段可以把指定 Skill预加载到 subagent 的上下文启动阶段。官方说明很明确列在该字段里的 Skill 会注入完整内容不只是描述同时 subagent 仍可通过 Skill tool 发现并调用未列出的 project、user 和 plugin skills。先看一个 subagent 的配置文件。它放在.claude/agents/目录下--- name: api-developer description: 专门实现 REST API endpoint遵循项目 API 规范 skills: - api-style-guide - error-handling-patterns model: claude-sonnet-4-5 --- 你是一个 API 开发专员。实现 endpoint 时严格遵循已加载的 api-style-guide 和 error-handling-patterns。 输出必须包含路由定义、请求校验、错误响应、单元测试骨架。这里的关键差异主会话里的 Skill 像临时拿手册subagent 里的预加载 Skill 像给专员上岗前发一整套培训材料。api-developer每次启动都带着 API 规范和错误处理模式不需要运行中再决定是否加载。但这会带来上下文成本。subagent 一启动就加载完整 SkillSkill 太大就会压缩它自己的工作空间。官方文档说明subagent 的初始上下文包含自身 prompt、任务消息、CLAUDE.md 和 memory、git status以及skills字段指定的完整 Skill 内容。所以在 subagent 里预加载 Skill 要比主会话更谨慎——只有那些几乎每次都需要的领域知识才适合预加载。还有一个容易踩的坑设置了disable-model-invocation的 Skill 不能被预加载到 subagent。如果列出的 Skill 缺失或被禁用Claude Code 会跳过并在 debug log 记录警告。所以有副作用的 Skill 和作为领域知识预加载的 Skill应该分成两类设计。对于需要连接外部服务的场景比如让 subagent 调用模型能力可以在配置里指定 Base URL、Key 和 Model ID 三件套。以 TaoToken 为例它的 API 地址是https://taotoken.net/api你可以在 subagent 的环境变量或 MCP 配置里这样写{ mcpServers: { taotoken: { command: npx, args: [-y, taotoken/mcp-server], env: { TAOTOKEN_BASE_URL: https://taotoken.net/api, TAOTOKEN_API_KEY: sk-你的密钥, TAOTOKEN_MODEL_ID: claude-sonnet-4-5 } } } }配置好后subagent 就能在需要时调用模型对话能力而 Skill 负责告诉它“什么时候调、怎么调、输出什么格式”。两者配合才是完整的 Agent 工作流。4. 一次真实任务验证确认按需加载真的生效光看文档不够得用真实任务验证。我拿一个 SAP Commerce Cloud 购物车问题来演示检查 Skill 是否按预期触发。准备阶段在.claude/skills/commerce-cart-debug/SKILL.md里写好工作流description 包含“购物车丢失、cart 未合并、checkout 卡住”等关键词。然后开一个 fresh session先问一个无关问题帮我看看这个 Angular 组件的 change detection 为什么触发两次观察 Claude 的响应。如果它没有加载commerce-cart-debug说明按需加载生效了——无关任务不会把购物车手册拉进上下文。你可以在 Claude Code 里用/skills命令列出可用 Skills并按 token count 排序确认当前 session 加载了哪些。触发阶段接着问一个匹配任务用户登录后购物车里的商品消失了anonymous cart 没有 merge 到 user cart帮我排查这时 Claude 应该自动加载commerce-cart-debug并按照 SKILL.md 里的工作流执行定位 cart service、检查用户状态、读取 cart guid、检查 interceptor。如果它没触发先改 description把“anonymous cart 没有 merge”这个具体表述加进去。验证输出一个写得好的 Skill输出应该稳定且结构化。比如问题定位登录后 cart guid 未从 anonymous session 迁移到 user session 证据 - src/cart/cart.service.ts:47 未在 login 成功后调用 mergeCart - src/auth/login.facade.ts:23 缺少 cart guid 透传 修复建议在 login.facade.ts 的 onSuccess 回调中调用 cartService.mergeAnonymousCart()如果输出格式不稳定就在 SKILL.md 里加示例。如果 Claude 反复读取某个 reference 文件却没进展说明工作流分支写得不够清晰。检查加载行为官方文档提醒Skill 主体被调用后会作为一条消息进入对话并在本次 session 后续保留。对话发生 compaction 时Claude Code 会重新附加最近调用过的 Skill 内容但存在 token 预算旧的 Skill 可能在多次压缩后被挤掉。所以验证时要注意如果你在一个长 session 里连续调用多个 Skill早期的可能被挤掉。这不是 bug是设计上的成本控制。准备三到五个真实 prompt在 fresh session 里分别测试有 Skill 和无 Skill 的结果差异。比如对commerce-cart-debug可以测试“登录后购物车丢失”“anonymous cart 没有 merge”“checkout 前 cart guid 变了”“ASM impersonation 下 cart 返回 403”。该触发时没触发改 description触发了但路径混乱改正文流程输出不稳定加示例。这套迭代方法和软件测试一样别凭感觉说“应该有用”。5. 常见报错排查401、local proxy failed、reading choices、OAuthSkill 体系跑起来后最容易在“连接层”翻车。下面这几个报错我按真实遇到过的场景逐个拆。401 Unauthorized最常见。如果你在 Skill 里通过 MCP 或脚本调用模型 APIKey 没配或配错就会 401。检查三件套是否齐全Base URL 是否为https://taotoken.net/apiKey 是否以sk-开头且未过期Model ID 是否拼写正确。在 subagent 配置里确认env字段的变量名和脚本里读取的一致。一个典型错误是把 Key 写进了SKILL.md正文而不是环境变量导致 Claude 读取时拿到的是字面量字符串。local proxy failed这个报错通常出现在网络层配置。如果你在 MCP server 配置里指定了本地代理端口但代理服务没启动就会报这个。排查步骤先确认代理进程是否在运行再检查端口是否被占用最后确认 MCP 配置里的地址和端口与实际一致。注意Skill 本身不负责网络代理它只负责告诉 Claude“什么时候调用哪个工具”网络配置是 MCP server 或环境变量的事两者要分开排查。reading choices 报错这个通常出现在模型返回结构不符合预期时。比如你在 Skill 里要求 Claude 输出 JSON但模型返回了自然语言下游脚本解析choices字段就失败。解决办法是在 SKILL.md 里明确输出格式并给出示例## 输出格式 必须返回如下 JSON不要包裹在 markdown 代码块里 {root_cause: ..., evidence: [...], fix: ...}如果还是不稳定可以在脚本里加容错先尝试 JSON 解析失败则用正则提取关键字段再失败就原样返回让 Claude 重新生成。OAuth 相关报错当 Skill 涉及调用需要 OAuth 的外部服务时常见问题是 token 过期或 scope 不足。排查时先确认 token 是否有效再检查 scope 是否覆盖了 Skill 里声明的操作。如果 Skill 通过 MCP 连接外部服务确认 MCP server 的 OAuth 配置和 Skill 的allowed-tools不冲突。一个实用技巧把 OAuth 刷新逻辑放在脚本里Skill 正文只写“调用 refresh-token 脚本”这样 token 管理不占用 Claude 的上下文。Skill 没触发如果 Claude 该用 Skill 时没用先检查 description 是否包含当前任务的关键词。其次确认 Skill 文件路径是否正确——项目级 Skill 在.claude/skills/用户级在~/.claude/skills/。最后检查是否设置了disable-model-invocation设了的话只能手动/skill-name调用。Skill 触发了但行为不对先看 SKILL.md 的工作流是否有明确的分支判断。如果 Claude 跳过了某个检查步骤可能是那一步写得不够具体。把“检查 cart guid”改成“读取 sessionStorage 中的 cart_guid 字段若为空则记录到输出”行为会稳定很多。6. 把团队规范沉淀成可复用资产从今天开始搭你的第一个 Skill回到核心价值。Skills 真正解决的不是“怎么让 Claude 多知道一点”而是“怎么让 Claude 在正确时间知道正确内容并按稳定流程行动”。它让上下文从一锅粥变成按需加载的知识系统也让团队经验从口口相传变成可以版本化、review、测试和分发的工程资产。分工要清楚CLAUDE.md 写永远要记住的规则MCP 连接外部服务hooks 响应生命周期事件subagents 隔离探索和并行工作。Skills 卡在中间负责把“我们已经知道怎么做”变成 Claude Code 随时可取的能力包。如果你现在就想动手建议从最小的 Skill 开始。找一个你每周至少重复三次的任务比如“检查 PR 里的 API 命名是否符合规范”把它写成SKILL.md--- name: api-naming-check description: 检查 REST API endpoint 命名是否符合项目规范覆盖资源名复数、kebab-case 路径、版本前缀、HTTP 方法语义。当用户提交 API 相关代码或要求 review endpoint 时使用。 allowed-tools: Read, Grep --- ## 检查项 1. 资源名是否使用复数形式/users 而非 /user 2. 路径是否使用 kebab-case/user-profiles 而非 /userProfiles 3. 是否包含版本前缀/api/v1/... 4. HTTP 方法是否语义正确GET 查询、POST 创建、PUT 全量更新、PATCH 部分更新、DELETE 删除 ## 输出格式 逐条列出违规项格式文件路径:行号 - 违规内容 - 建议修改写完放进.claude/skills/api-naming-check/SKILL.md开一个 fresh session提交一段故意写错的 API 代码看 Claude 是否自动触发并逐条列出问题。如果触发了但漏检就在检查项里补具体规则如果没触发就在 description 里加“review endpoint”“API 命名”等关键词。跑通一个之后再按领域拆分。SAP Commerce Cloud 项目可以拆成commerce-cart-debug、commerce-asm-debug、commerce-solr-facet、commerce-checkout-reviewABAP RAP 项目可以拆成rap-behavior-review、rap-draft-debug、rap-locking-review。每个 Skill 短而准Claude 的自动选择质量会明显高于一个巨大的commerce-helper。最后提醒一句凡是会修改 Git、写文件、提交 PR、部署、发消息、改配置、调用生产系统的 Skill都默认设置disable-model-invocation只能人工/skill-name触发。Claude 可以读取说明、生成计划、提醒风险但不能因为一句泛泛的“帮我处理一下”就自动触发真实动作。权限分层、危险操作人工确认这套治理手段比 Skill 本身更重要。需要管理 API Key 或查看接入文档可以走 API Keys 和 接入文档想先验证模型效果用 模型对话长期跑编码和 Agent 任务直接上 Coding Plan。