1. 为什么你的 Claude Code 总是“重新学一遍”用 Claude Code 写代码的人大概率都经历过这种循环每次开新会话都要把同一套项目规范、同一套代码风格、同一套发布流程重新讲一遍。讲完这次下次换个窗口又得从头来。提示词越写越长最后变成一份几百行的“项目说明书”塞进对话里既占上下文又容易被模型忽略。问题的根源在于提示词是会话级的而工作流是项目级的。你在一次对话里教会 Claude 的东西会话结束就没了。Claude Skills 要解决的就是这件事——它把“怎么做一个特定任务”从一次性提示词变成文件系统里可复用、可版本管理、可团队共享的技能包。Claude Skills 是 Anthropic 推出的一套机制用一个SKILL.md文件注意大小写Claude Code 里通常写作SKILL.md加上可选的脚本和资源文件把某类任务的执行方法固化下来。Claude Code 会在合适的时机自动发现并加载它你不需要手动“召唤”。它适合谁适合所有把 Claude Code 当日常开发工具、并且发现自己反复写同类提示词的人——尤其是做数据清洗、文档生成、代码审查、发布流程自动化的开发者。我试过把一套“生成周报”的提示词从对话里搬进 Skill之后每周只需要说一句“生成本周周报”Claude 就按固定格式、固定数据源、固定输出路径跑完。这篇文章就按这个思路从文件结构讲到触发机制再给一份可直接复制的模板最后演示怎么验证它真的生效。2. Claude Skills 的前置准备目录、模型与接入配置在动手写SKILL.md之前先把运行环境理清楚。Claude Code 的 Skills 走的是文件系统发现路线和网页版 claude.ai 上传 ZIP 的方式完全不同。网页版是“上传—开关—自动激活”Claude Code 是“放进目录—自动扫描—按描述激活”。理解这个差异后面排障会省很多事。Skills 有三个存放位置优先级和用途不一样位置路径作用范围典型用途个人 Skills~/.claude/skills/skill-name/当前用户所有项目个人通用工作流项目 Skills项目根/.claude/skills/skill-name/仅当前项目团队共享、随 git 同步插件 Skills随插件安装自动提供取决于插件第三方能力扩展个人 Skills 适合放“我自己到哪都用”的东西比如统一的提交信息格式。项目 Skills 适合放“这个仓库专属”的东西比如本项目的 API 命名规范、数据库迁移流程。团队协作优先用项目 Skills因为它能进 git别人git pull之后自动就有了。接下来是模型接入。Claude Code 需要能访问 Claude 模型这里我用 TaoToken 做统一接入它的 API 地址是https://taotoken.net/api兼容 Anthropic 的接口格式。配置方式是在环境变量里指定 Base URL 和 KeyClaude Code 会读取这些变量。# 写入 shell 配置以 zsh 为例bash 换成 ~/.bashrc export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的TaoToken密钥如果你用的是 Claude Code 的 settings 文件方式可以在~/.claude/settings.json里写{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥 } }Key 在 TaoToken 控制台的 API Keys 页面创建地址是https://taotoken.net/console/api-keys。创建后复制一次之后不再显示。模型 ID 用 Claude 系列即可比如claude-sonnet-4-5这类标识具体以控制台模型列表为准。这里有个容易踩的坑Base URL 结尾不要多加/v1。TaoToken 的接入地址就是https://taotoken.net/apiClaude Code 会自己拼接路径。多写一层会导致 404而不是 401报错信息看起来像“模型不存在”实际是路径错了。配置完先别急着写 Skill用一条最小请求确认链路通curl https://taotoken.net/api/v1/messages \ -H x-api-key: $ANTHROPIC_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-5, max_tokens: 64, messages: [{role: user, content: 回复 OK 两个字母}] }返回里有content字段且文本是 OK说明接入没问题。这一步过了再进 Skills 才不会把“接入错误”误判成“Skill 没生效”。3. 可复制的 SKILL.md 模板与目录结构现在进入正题。一个 Skill 的最小单元是一个目录里面必须有SKILL.md。文件名在 Claude Code 里是大小写敏感的写成skill.md在部分版本上不会被识别统一用SKILL.md最稳。先看目录结构。下面这个模板是我实际在用的“周报生成”Skill你可以直接复制改名.claude/skills/weekly-report/ ├── SKILL.md # 核心文件必需 ├── reference.md # 参考文档可选 ├── scripts/ │ └── collect_git.py # 可执行脚本可选 └── resources/ └── template.md # 模板资源可选SKILL.md必须以 YAML frontmatter 开头两个字段是必需的name和description。description是触发决策的核心写得好不好直接决定 Claude 会不会用它。--- name: weekly-report description: 根据 git 提交记录生成结构化周报。当用户提到周报本周总结weekly report汇总本周提交时使用。输出 Markdown 格式包含完成事项、进行中事项、风险点三部分。 allowed-tools: - Read - Bash - Write --- # 周报生成技能 ## 何时使用 用户要求生成周报、本周工作总结、或汇总一段时间内的代码提交时。 ## 执行步骤 1. 运行 scripts/collect_git.py 收集最近 7 天的提交记录 2. 按提交类型feat/fix/docs/refactor归类 3. 读取 resources/template.md 作为输出模板 4. 将归类结果填入模板输出到 reports/weekly-YYYY-MM-DD.md ## 输出要求 - 完成事项每条一行格式为 - [类型] 描述 - 进行中事项标注当前进度百分比 - 风险点没有则写无 ## 注意事项 - 不要编造未在提交记录中出现的内容 - 提交信息为英文时保留原文不翻译allowed-tools是可选的但强烈建议写。它的作用是当这个 Skill 激活时Claude 只能使用你列出的工具不需要每次请求权限。上面这个 Skill 只允许读文件、跑 Bash、写文件不会去动网络或删库安全性可控。description的写法有个诀窍同时写“做什么”和“什么时候用”并塞进用户可能说的关键词。对比一下# 差的写法太泛Claude 不知道何时触发 description: 帮助处理报告 # 好的写法功能 触发词 输出形态 description: 根据 git 提交记录生成结构化周报。当用户提到周报本周总结weekly report汇总本周提交时使用。输出 Markdown 格式包含完成事项、进行中事项、风险点三部分。差的写法里没有“周报”这个词用户说“帮我写周报”时Claude 匹配不上。好的写法把用户可能用的词都列进去了命中率高很多。再给一个更贴近编码场景的模板做“代码审查”--- name: code-review description: 对指定文件或 diff 做代码审查检查命名、错误处理、边界条件、性能隐患。当用户说审查代码review 一下看看这段有没有问题code review时使用。 allowed-tools: - Read - Grep - Bash --- # 代码审查技能 ## 审查维度 1. 命名变量/函数名是否表意清晰 2. 错误处理异常是否被吞掉是否有兜底 3. 边界条件空值、越界、并发是否考虑 4. 性能是否有明显的 N1、重复计算 ## 输出格式 按严重程度分级BLOCKER / MAJOR / MINOR每条给出文件行号和修改建议。 ## 禁止 - 不要重写整个文件只给针对性建议 - 不要对未改动的代码提意见这两个模板覆盖了“生成类”和“审查类”两种典型 Skill。你可以把它们放进.claude/skills/下对应目录重启 Claude Code 会话即可被发现。4. 验证 Skill 是否生效从发现到调用的完整请求写完文件不等于生效。Claude Code 的 Skills 是按需加载的它不会把所有 Skill 内容都塞进上下文而是先加载元数据name description判断相关后再读完整内容。所以验证要分两步先确认被发现再确认被调用。第一步确认发现。在 Claude Code 会话里直接问有哪些 Skills 可用正常情况下Claude 会列出它扫描到的 Skill 名称和描述。如果没看到你的 Skill先检查路径# 个人 Skills ls ~/.claude/skills/*/SKILL.md # 项目 Skills ls .claude/skills/*/SKILL.md两个命令都要能列出你刚建的文件。列不出来就是路径错了常见的是把.claude写成了claude或者目录层级多套了一层。第二步确认调用。构造一个和description匹配的请求比如对周报 Skill帮我生成本周周报如果 Skill 生效Claude 会按SKILL.md里的步骤执行先跑脚本收集提交再读模板最后写文件。你可以在输出里看到它调用了scripts/collect_git.py并且生成了reports/weekly-2025-xx-xx.md。如果 Claude 没有调用 Skill而是自己随手写了一段说明description没匹配上。这时候不要改代码先改描述。把用户实际会说的那句话原封不动加进description的触发词里再试一次。验证脚本类 Skill 时注意脚本的执行权限chmod x .claude/skills/weekly-report/scripts/collect_git.py没有执行权限时Claude 调用会失败报错类似Permission denied。这个错误不会自动提示你“是权限问题”只会显示脚本没输出容易误判成 Skill 逻辑错。还有一个验证技巧让 Claude 复述它加载了什么。在请求后追加一句执行前先告诉我你加载了哪个 Skill以及它的执行步骤。这样你能看到它的“思考路径”确认它读的是你的SKILL.md而不是凭记忆瞎编。这一步对调试description特别有用——如果它说“我没有加载任何 Skill”那就是发现阶段就失败了。5. 常见报错排查401、local proxy failed 与 Skill 不触发Skills 本身不复杂但和接入层、文件系统叠在一起报错信息往往指向错误的方向。下面按真实遇到的错误逐条拆。401 Unauthorized。这个几乎都是 Key 的问题。先确认环境变量真的被读到了echo $ANTHROPIC_API_KEY echo $ANTHROPIC_BASE_URL如果输出为空说明 shell 配置没生效重新source ~/.zshrc或开新终端。如果 Key 有值但仍 401检查是不是复制时带了空格或换行。TaoToken 的 Key 在控制台创建后只显示一次如果丢了就重新建一个。local proxy failed / connection refused。这个报错通常出现在你本地起了代理层但代理没起来或端口不对。Claude Code 直连https://taotoken.net/api时不应该出现这个错。如果出现了检查是不是在 settings 里额外配了HTTP_PROXY之类的变量把它清掉unset HTTP_PROXY HTTPS_PROXY ALL_PROXY然后重开会话。注意这里说的是清掉本地代理配置不是让你去配代理方向别搞反。reading choices / 响应解析失败。这个多半是 Base URL 多写了路径。正确写法是https://taotoken.net/api不要写成https://taotoken.net/api/v1。多一层/v1后Claude Code 拼出来的完整路径会变成/api/v1/v1/messages服务端返回的不是标准结构客户端解析choices字段时就报错。改回正确地址即可。OAuth 相关报错。如果你之前用官方账号登录过 Claude Code本地可能残留 OAuth 凭据和 API Key 模式冲突。清理方式rm -rf ~/.claude/credentials.json然后重新用环境变量方式启动。这一步会清掉登录态之后走的就是纯 API Key 鉴权。Skill 不触发。这个不是报错但最常被当成 bug。排查顺序先看description是否包含用户实际会说的词。用户说“总结一下这周干了啥”你的描述里只有“周报”那就匹配不上。把口语化说法也加进去。再看 YAML 是否合法。frontmatter 必须以---开头和结尾中间不能有 tab只能用空格。快速检查head -n 15 .claude/skills/weekly-report/SKILL.md如果第一行不是---或者字段缩进用了 tabYAML 解析会静默失败Skill 等于不存在。最后看是否有多个 Skill 描述重叠。两个 Skill 都写“处理文档”Claude 会犹豫。解决办法是让描述更具体把各自的触发词区分开。脚本报 ModuleNotFoundError。Claude Code 在加载 Skill 时可以按需安装依赖但前提是脚本里声明了。稳妥做法是在SKILL.md里写明依赖或者用标准库写脚本。比如collect_git.py只用subprocess和datetime就不需要额外安装。6. 把重复提示词沉淀成技能从单文件到 Agent Skills 组合单个 Skill 解决单个任务但真实工作流往往是多个任务的组合。比如“发布一个新版本”可能包含跑测试、生成 changelog、打 tag、发通知。这时候不需要写一个巨大的 Skill而是拆成几个小 Skill让 Claude 自己组合。Claude Skills 的一个关键设计是Skill 之间不能显式互相引用但 Claude 可以自动同时使用多个。这意味着你只要把每个 Skill 的description写清楚Claude 在“发布版本”这个请求下会依次激活测试 Skill、changelog Skill、git tag Skill。这种组合能力就是 Agent Skills 的核心价值——把通用 Agent 变成懂你项目规矩的专用 Agent。组合时的组织建议按“动词 对象”拆分而不是按“大流程”拆分。run-tests、gen-changelog、tag-release三个小 Skill 比一个release-everything更好维护也更容易复用——run-tests在本地开发时也能单独用。共享资源放在项目根的资源目录而不是每个 Skill 各存一份。比如 changelog 模板被两个 Skill 用到就放在.claude/skills/shared/templates/在各自的SKILL.md里用相对路径引用。用allowed-tools做权限隔离。生成 changelog 的 Skill 只需要Read和Write就不要给它Bash。这样即使描述被误触发也不会执行危险命令。版本管理上项目 Skills 直接进 git。团队成员git pull后Claude Code 下次启动就会扫描到新 Skill不需要额外安装步骤。个人 Skills 则适合放那些“只对我自己有意义”的东西比如我自己的提交信息风格。最后说一个实际体会Skill 的价值不在于写得多而在于写得准。我一开始建了七八个 Skill结果描述互相重叠Claude 经常选错。后来砍到三个每个的description都精确到“用户会说的原话”触发准确率反而上去了。先从一个最痛的点开始把它跑通、跑稳再考虑扩展。当你能用一句“生成本周周报”替代过去三百字的提示词时这套机制就算真正落地了。 
长河君 · 2026/10/3 16:29:29 · 阅读 1.2k Claude Skills 介绍：用 skill.md 把 Claude Code 变成可复用工作流
1. 为什么你的 Claude Code 总是“重新学一遍”用 Claude Code 写代码的人大概率都经历过这种循环每次开新会话都要把同一套项目规范、同一套代码风格、同一套发布流程重新讲一遍。讲完这次下次换个窗口又得从头来。提示词越写越长最后变成一份几百行的“项目说明书”塞进对话里既占上下文又容易被模型忽略。问题的根源在于提示词是会话级的而工作流是项目级的。你在一次对话里教会 Claude 的东西会话结束就没了。Claude Skills 要解决的就是这件事——它把“怎么做一个特定任务”从一次性提示词变成文件系统里可复用、可版本管理、可团队共享的技能包。Claude Skills 是 Anthropic 推出的一套机制用一个SKILL.md文件注意大小写Claude Code 里通常写作SKILL.md加上可选的脚本和资源文件把某类任务的执行方法固化下来。Claude Code 会在合适的时机自动发现并加载它你不需要手动“召唤”。它适合谁适合所有把 Claude Code 当日常开发工具、并且发现自己反复写同类提示词的人——尤其是做数据清洗、文档生成、代码审查、发布流程自动化的开发者。我试过把一套“生成周报”的提示词从对话里搬进 Skill之后每周只需要说一句“生成本周周报”Claude 就按固定格式、固定数据源、固定输出路径跑完。这篇文章就按这个思路从文件结构讲到触发机制再给一份可直接复制的模板最后演示怎么验证它真的生效。2. Claude Skills 的前置准备目录、模型与接入配置在动手写SKILL.md之前先把运行环境理清楚。Claude Code 的 Skills 走的是文件系统发现路线和网页版 claude.ai 上传 ZIP 的方式完全不同。网页版是“上传—开关—自动激活”Claude Code 是“放进目录—自动扫描—按描述激活”。理解这个差异后面排障会省很多事。Skills 有三个存放位置优先级和用途不一样位置路径作用范围典型用途个人 Skills~/.claude/skills/skill-name/当前用户所有项目个人通用工作流项目 Skills项目根/.claude/skills/skill-name/仅当前项目团队共享、随 git 同步插件 Skills随插件安装自动提供取决于插件第三方能力扩展个人 Skills 适合放“我自己到哪都用”的东西比如统一的提交信息格式。项目 Skills 适合放“这个仓库专属”的东西比如本项目的 API 命名规范、数据库迁移流程。团队协作优先用项目 Skills因为它能进 git别人git pull之后自动就有了。接下来是模型接入。Claude Code 需要能访问 Claude 模型这里我用 TaoToken 做统一接入它的 API 地址是https://taotoken.net/api兼容 Anthropic 的接口格式。配置方式是在环境变量里指定 Base URL 和 KeyClaude Code 会读取这些变量。# 写入 shell 配置以 zsh 为例bash 换成 ~/.bashrc export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的TaoToken密钥如果你用的是 Claude Code 的 settings 文件方式可以在~/.claude/settings.json里写{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥 } }Key 在 TaoToken 控制台的 API Keys 页面创建地址是https://taotoken.net/console/api-keys。创建后复制一次之后不再显示。模型 ID 用 Claude 系列即可比如claude-sonnet-4-5这类标识具体以控制台模型列表为准。这里有个容易踩的坑Base URL 结尾不要多加/v1。TaoToken 的接入地址就是https://taotoken.net/apiClaude Code 会自己拼接路径。多写一层会导致 404而不是 401报错信息看起来像“模型不存在”实际是路径错了。配置完先别急着写 Skill用一条最小请求确认链路通curl https://taotoken.net/api/v1/messages \ -H x-api-key: $ANTHROPIC_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-5, max_tokens: 64, messages: [{role: user, content: 回复 OK 两个字母}] }返回里有content字段且文本是 OK说明接入没问题。这一步过了再进 Skills 才不会把“接入错误”误判成“Skill 没生效”。3. 可复制的 SKILL.md 模板与目录结构现在进入正题。一个 Skill 的最小单元是一个目录里面必须有SKILL.md。文件名在 Claude Code 里是大小写敏感的写成skill.md在部分版本上不会被识别统一用SKILL.md最稳。先看目录结构。下面这个模板是我实际在用的“周报生成”Skill你可以直接复制改名.claude/skills/weekly-report/ ├── SKILL.md # 核心文件必需 ├── reference.md # 参考文档可选 ├── scripts/ │ └── collect_git.py # 可执行脚本可选 └── resources/ └── template.md # 模板资源可选SKILL.md必须以 YAML frontmatter 开头两个字段是必需的name和description。description是触发决策的核心写得好不好直接决定 Claude 会不会用它。--- name: weekly-report description: 根据 git 提交记录生成结构化周报。当用户提到周报本周总结weekly report汇总本周提交时使用。输出 Markdown 格式包含完成事项、进行中事项、风险点三部分。 allowed-tools: - Read - Bash - Write --- # 周报生成技能 ## 何时使用 用户要求生成周报、本周工作总结、或汇总一段时间内的代码提交时。 ## 执行步骤 1. 运行 scripts/collect_git.py 收集最近 7 天的提交记录 2. 按提交类型feat/fix/docs/refactor归类 3. 读取 resources/template.md 作为输出模板 4. 将归类结果填入模板输出到 reports/weekly-YYYY-MM-DD.md ## 输出要求 - 完成事项每条一行格式为 - [类型] 描述 - 进行中事项标注当前进度百分比 - 风险点没有则写无 ## 注意事项 - 不要编造未在提交记录中出现的内容 - 提交信息为英文时保留原文不翻译allowed-tools是可选的但强烈建议写。它的作用是当这个 Skill 激活时Claude 只能使用你列出的工具不需要每次请求权限。上面这个 Skill 只允许读文件、跑 Bash、写文件不会去动网络或删库安全性可控。description的写法有个诀窍同时写“做什么”和“什么时候用”并塞进用户可能说的关键词。对比一下# 差的写法太泛Claude 不知道何时触发 description: 帮助处理报告 # 好的写法功能 触发词 输出形态 description: 根据 git 提交记录生成结构化周报。当用户提到周报本周总结weekly report汇总本周提交时使用。输出 Markdown 格式包含完成事项、进行中事项、风险点三部分。差的写法里没有“周报”这个词用户说“帮我写周报”时Claude 匹配不上。好的写法把用户可能用的词都列进去了命中率高很多。再给一个更贴近编码场景的模板做“代码审查”--- name: code-review description: 对指定文件或 diff 做代码审查检查命名、错误处理、边界条件、性能隐患。当用户说审查代码review 一下看看这段有没有问题code review时使用。 allowed-tools: - Read - Grep - Bash --- # 代码审查技能 ## 审查维度 1. 命名变量/函数名是否表意清晰 2. 错误处理异常是否被吞掉是否有兜底 3. 边界条件空值、越界、并发是否考虑 4. 性能是否有明显的 N1、重复计算 ## 输出格式 按严重程度分级BLOCKER / MAJOR / MINOR每条给出文件行号和修改建议。 ## 禁止 - 不要重写整个文件只给针对性建议 - 不要对未改动的代码提意见这两个模板覆盖了“生成类”和“审查类”两种典型 Skill。你可以把它们放进.claude/skills/下对应目录重启 Claude Code 会话即可被发现。4. 验证 Skill 是否生效从发现到调用的完整请求写完文件不等于生效。Claude Code 的 Skills 是按需加载的它不会把所有 Skill 内容都塞进上下文而是先加载元数据name description判断相关后再读完整内容。所以验证要分两步先确认被发现再确认被调用。第一步确认发现。在 Claude Code 会话里直接问有哪些 Skills 可用正常情况下Claude 会列出它扫描到的 Skill 名称和描述。如果没看到你的 Skill先检查路径# 个人 Skills ls ~/.claude/skills/*/SKILL.md # 项目 Skills ls .claude/skills/*/SKILL.md两个命令都要能列出你刚建的文件。列不出来就是路径错了常见的是把.claude写成了claude或者目录层级多套了一层。第二步确认调用。构造一个和description匹配的请求比如对周报 Skill帮我生成本周周报如果 Skill 生效Claude 会按SKILL.md里的步骤执行先跑脚本收集提交再读模板最后写文件。你可以在输出里看到它调用了scripts/collect_git.py并且生成了reports/weekly-2025-xx-xx.md。如果 Claude 没有调用 Skill而是自己随手写了一段说明description没匹配上。这时候不要改代码先改描述。把用户实际会说的那句话原封不动加进description的触发词里再试一次。验证脚本类 Skill 时注意脚本的执行权限chmod x .claude/skills/weekly-report/scripts/collect_git.py没有执行权限时Claude 调用会失败报错类似Permission denied。这个错误不会自动提示你“是权限问题”只会显示脚本没输出容易误判成 Skill 逻辑错。还有一个验证技巧让 Claude 复述它加载了什么。在请求后追加一句执行前先告诉我你加载了哪个 Skill以及它的执行步骤。这样你能看到它的“思考路径”确认它读的是你的SKILL.md而不是凭记忆瞎编。这一步对调试description特别有用——如果它说“我没有加载任何 Skill”那就是发现阶段就失败了。5. 常见报错排查401、local proxy failed 与 Skill 不触发Skills 本身不复杂但和接入层、文件系统叠在一起报错信息往往指向错误的方向。下面按真实遇到的错误逐条拆。401 Unauthorized。这个几乎都是 Key 的问题。先确认环境变量真的被读到了echo $ANTHROPIC_API_KEY echo $ANTHROPIC_BASE_URL如果输出为空说明 shell 配置没生效重新source ~/.zshrc或开新终端。如果 Key 有值但仍 401检查是不是复制时带了空格或换行。TaoToken 的 Key 在控制台创建后只显示一次如果丢了就重新建一个。local proxy failed / connection refused。这个报错通常出现在你本地起了代理层但代理没起来或端口不对。Claude Code 直连https://taotoken.net/api时不应该出现这个错。如果出现了检查是不是在 settings 里额外配了HTTP_PROXY之类的变量把它清掉unset HTTP_PROXY HTTPS_PROXY ALL_PROXY然后重开会话。注意这里说的是清掉本地代理配置不是让你去配代理方向别搞反。reading choices / 响应解析失败。这个多半是 Base URL 多写了路径。正确写法是https://taotoken.net/api不要写成https://taotoken.net/api/v1。多一层/v1后Claude Code 拼出来的完整路径会变成/api/v1/v1/messages服务端返回的不是标准结构客户端解析choices字段时就报错。改回正确地址即可。OAuth 相关报错。如果你之前用官方账号登录过 Claude Code本地可能残留 OAuth 凭据和 API Key 模式冲突。清理方式rm -rf ~/.claude/credentials.json然后重新用环境变量方式启动。这一步会清掉登录态之后走的就是纯 API Key 鉴权。Skill 不触发。这个不是报错但最常被当成 bug。排查顺序先看description是否包含用户实际会说的词。用户说“总结一下这周干了啥”你的描述里只有“周报”那就匹配不上。把口语化说法也加进去。再看 YAML 是否合法。frontmatter 必须以---开头和结尾中间不能有 tab只能用空格。快速检查head -n 15 .claude/skills/weekly-report/SKILL.md如果第一行不是---或者字段缩进用了 tabYAML 解析会静默失败Skill 等于不存在。最后看是否有多个 Skill 描述重叠。两个 Skill 都写“处理文档”Claude 会犹豫。解决办法是让描述更具体把各自的触发词区分开。脚本报 ModuleNotFoundError。Claude Code 在加载 Skill 时可以按需安装依赖但前提是脚本里声明了。稳妥做法是在SKILL.md里写明依赖或者用标准库写脚本。比如collect_git.py只用subprocess和datetime就不需要额外安装。6. 把重复提示词沉淀成技能从单文件到 Agent Skills 组合单个 Skill 解决单个任务但真实工作流往往是多个任务的组合。比如“发布一个新版本”可能包含跑测试、生成 changelog、打 tag、发通知。这时候不需要写一个巨大的 Skill而是拆成几个小 Skill让 Claude 自己组合。Claude Skills 的一个关键设计是Skill 之间不能显式互相引用但 Claude 可以自动同时使用多个。这意味着你只要把每个 Skill 的description写清楚Claude 在“发布版本”这个请求下会依次激活测试 Skill、changelog Skill、git tag Skill。这种组合能力就是 Agent Skills 的核心价值——把通用 Agent 变成懂你项目规矩的专用 Agent。组合时的组织建议按“动词 对象”拆分而不是按“大流程”拆分。run-tests、gen-changelog、tag-release三个小 Skill 比一个release-everything更好维护也更容易复用——run-tests在本地开发时也能单独用。共享资源放在项目根的资源目录而不是每个 Skill 各存一份。比如 changelog 模板被两个 Skill 用到就放在.claude/skills/shared/templates/在各自的SKILL.md里用相对路径引用。用allowed-tools做权限隔离。生成 changelog 的 Skill 只需要Read和Write就不要给它Bash。这样即使描述被误触发也不会执行危险命令。版本管理上项目 Skills 直接进 git。团队成员git pull后Claude Code 下次启动就会扫描到新 Skill不需要额外安装步骤。个人 Skills 则适合放那些“只对我自己有意义”的东西比如我自己的提交信息风格。最后说一个实际体会Skill 的价值不在于写得多而在于写得准。我一开始建了七八个 Skill结果描述互相重叠Claude 经常选错。后来砍到三个每个的description都精确到“用户会说的原话”触发准确率反而上去了。先从一个最痛的点开始把它跑通、跑稳再考虑扩展。当你能用一句“生成本周周报”替代过去三百字的提示词时这套机制就算真正落地了。