1. 为什么你的 Claude Code 总是重复劳动Skill 编写入门与可复用能力沉淀用 Claude Code 写代码最让人抓狂的不是它不会写而是每次都要重新交代一遍背景。比如你让它做代码审查第一次得说清楚「检查命名规范、看有没有硬编码密钥、输出用表格」第二天换个项目又得从头讲一遍。这种重复沟通的成本在项目多起来之后会指数级上升。Claude Code 的 Skill 机制就是来解决这个问题的。简单说Skill 是一份写在项目里的 Markdown 文件它把「什么场景触发、按什么步骤执行、输出成什么格式」固化下来。你只要把文件放进.claude/skills/目录Claude Code 在对话时会自动匹配触发词并加载对应 Skill。适合谁适合已经用过 Claude Code 基础功能、手里有若干重复流程代码审查、API 文档生成、项目初始化、提交信息规范想沉淀成可调用能力的开发者。这一章不讲安装、不讲登录直接进入 Skill 怎么写。我会从最小可用 Skill 开始给出目录结构、SKILL.md 配置模板、触发词写法、带参数的进阶用法最后落到本地加载验证和调试动作。你跟着做半小时内就能把第一个可复用 Skill 跑起来。需要说明的是Skill 本质是「提示词工程 文件约定」它不依赖任何特殊网络环境就是本地文件加 Claude Code 的读取逻辑。所以下面的内容你直接照抄配置就能用。2. TaoToken 前置准备Claude Code 接入与 Skill 目录初始化在写 Skill 之前得先保证 Claude Code 能正常跑起来。如果你已经能正常对话可以跳过接入部分直接看目录初始化。这里我用 TaoToken 作为接入示例因为它对 Claude Code 的兼容做得比较直接配置项清晰。先说清楚 TaoToken 是什么它是一个大模型 API 聚合服务提供兼容 Anthropic 协议的接口Claude Code 可以通过配置 Base URL 和 API Key 直接调用。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。接入 Claude Code 的核心是三个东西Base URL、API Key、Model ID。这三个缺一不可后面讲 CC Switch 和 settings 配置时也会反复出现。第一步去控制台创建 API Key。打开 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 在 API Keys 页面新建一个 Key复制保存。这个 Key 只显示一次丢了就得重建。第二步确认你要用的 Model ID。Claude Code 场景下常用的是 Claude 系列模型具体可用的模型名在模型对话页面能看到 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。记下你要用的那个 ID比如claude-sonnet-4-5这类格式。第三步配置 Claude Code 的接入。Claude Code 读取的是环境变量或配置文件。最直接的方式是设置环境变量export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEY你的API Key export ANTHROPIC_MODEL你的Model ID如果你用的是 CC Switch 这类多配置切换工具那就要写全三件套。CC Switch 的配置文件通常是一个 JSON路径在~/.cc-switch/config.json或类似位置结构大致如下{ providers: [ { name: taotoken, baseUrl: https://taotoken.net/api, apiKey: 你的API Key, model: 你的Model ID } ] }注意 Base URL 后面不要多加/v1Claude Code 会自己拼接路径。这一点很多人踩坑加了/v1之后请求 404。第四步初始化 Skill 目录。在你的项目根目录下创建.claude/skills/文件夹mkdir -p .claude/skills这个目录就是 Claude Code 扫描 Skill 的地方。目录结构建议按功能分子目录比如.claude/ skills/ code-review/ SKILL.md api-doc/ SKILL.md project-init/ SKILL.md每个 Skill 一个文件夹文件夹里放SKILL.md。这样比把所有 Skill 平铺在一个目录里更好管理也方便后续加辅助文件比如模板、示例数据。验证接入是否成功跑一句claude 你好如果返回正常说明 Base URL、Key、Model 三件套都对了。如果报 401就是 Key 错了如果报连接失败检查 Base URL 是不是写成了https://taotoken.net/api/v1。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 遇到协议问题可以对照看。3. SKILL.md 配置模板与触发词写法从最小可用到带参数这一节是核心直接给可复制的配置。先说最小可用 Skill再说规范最后说带参数和 Skill 互相调用。3.1 最小可用 Skill创建.claude/skills/hello/SKILL.md内容如下# Hello Skill ## 描述 向用户问好并介绍当前项目。 ## 适用场景 - 用户说 你好 - 用户说 介绍项目 ## 执行步骤 1. 读取项目根目录的 README.md 2. 用一句话总结项目用途 3. 列出主要技术栈 4. 友好地向用户问好 ## 输出格式 用中文回复格式如下 你好这是 [项目名]。 项目简介[一句话总结] 技术栈[主要技术] 有什么可以帮你的保存后测试claude 你好Claude Code 会扫描.claude/skills/下的所有SKILL.md匹配到「你好」这个触发词加载 hello Skill 并按步骤执行。这就是最小闭环。3.2 Skill 编写规范文件名和目录名用「小写字母 连字符」比如code-review、api-doc。避免空格和特殊字符code review这种带空格的目录名在某些 shell 环境下会出问题。SKILL.md 的内容结构建议固定为这几段# Skill 名称 ## 描述 1-2 句话说明用途。 ## 适用场景 - 触发关键词 1 - 触发关键词 2 ## 参数 - 参数名: 说明默认值xxx ## 执行步骤 1. 具体动作 2. 具体动作 ## 输出格式 明确结果格式。 ## 示例 至少 1 个完整示例。 ## 注意事项 边界情况、常见错误。触发词写法是关键。触发词写在「适用场景」里Claude Code 会拿用户输入去匹配这些词。写法上有几个技巧第一触发词要具体不要用「帮助」「处理」这种泛词否则会误触发。比如代码审查 Skill 的触发词写「审查代码」「code review」「检查这个文件」而不是「看看」。第二一个 Skill 可以有多组触发词覆盖不同说法。比如「生成文档」「写 API 文档」「导出接口说明」都指向同一个 Skill。第三触发词和描述要一致。描述里说「用于代码审查」触发词里却没有「审查」匹配率会下降。3.3 带参数的 SkillSkill 可以接收参数用{{参数名}}表示。看这个 API 文档生成 Skill# API 文档生成 Skill ## 描述 根据代码生成 API 文档。 ## 适用场景 - 生成 API 文档 - 导出接口文档 ## 参数 - language: 编程语言默认python - style: 文档风格默认openapi ## 执行步骤 1. 扫描 {{language}} 源代码文件 2. 提取函数签名和 docstring 3. 按 {{style}} 格式生成文档 4. 保存到 docs/api.md ## 输出格式 OpenAPI 3.0 YAML 格式。 ## 示例 参数languagepython, styleopenapi 输入 python def get_user(user_id: int) - dict: 获取用户信息 ...输出/user/{user_id}: get: summary: 获取用户信息 parameters: - name: user_id in: path type: integer调用时这样写 bash claude 生成 API 文档languagepythonstyleopenapiClaude Code 会把{{language}}替换成python{{style}}替换成openapi。如果用户没传参数就用默认值。3.4 Skill 调用 Skill一个 Skill 可以调用另一个 Skill这在做复杂流程时很有用。比如项目初始化 Skill# 项目初始化 Skill ## 描述 初始化新项目依次执行环境检查、依赖安装、代码规范配置。 ## 适用场景 - 初始化项目 - 新建项目 ## 执行步骤 1. 检查项目类型Python/Node/Java 2. 调用对应的 环境检查 Skill 3. 调用 依赖安装 Skill 4. 调用 代码规范配置 Skill 5. 输出初始化报告注意Skill 之间的调用是逻辑上的Claude Code 会按步骤依次加载对应 Skill。所以被调用的 Skill 必须真实存在于.claude/skills/目录下且触发词能被匹配到。3.5 settings 配置片段如果你想把 Skill 目录配置固化到项目里可以在.claude/settings.json里写{ skills: { directory: .claude/skills, autoLoad: true } }这个配置告诉 Claude Code 从哪个目录加载 Skill以及是否自动加载。路径要和实际目录一致否则加载不到。4. 本地加载验证与调试确认 Skill 真的被触发写完 Skill 不代表就能用得验证它是否被正确加载和触发。这一节给几个实测有效的调试动作。4.1 查看加载了哪些 SkillClaude Code 有调试模式可以看当前对话匹配了哪些 Skillclaude /debug 帮我写代码输出里会显示匹配到的 Skill 列表。如果这里没出现你写的 Skill说明触发词没匹配上或者文件路径不对。4.2 强制使用某个 Skill有时候自动匹配不准可以强制指定claude 使用 code-review Skill 审查 src/main.py这样 Claude Code 会跳过自动匹配直接加载code-review这个 Skill。适合调试阶段确认 Skill 内容是否正确。4.3 查看 Skill 内容并让 Claude 分析把 Skill 文件内容直接喂给 Claude让它检查有没有问题claude file .claude/skills/my-skill/SKILL.md 这个 Skill 有什么问题Claude 会读文件内容指出触发词是否合理、步骤是否可执行、输出格式是否明确。这个动作在 Skill 写完后做一遍能提前发现很多逻辑漏洞。4.4 验证参数替换带参数的 Skill要确认参数真的被替换了。测试方法claude 生成 API 文档languagegostylemarkdown然后看输出里是不是按 Go 语言和 Markdown 风格生成的。如果还是默认的 python/openapi说明参数没被识别检查{{参数名}}的拼写和调用时的参数名是否一致。4.5 成功结果长什么样一个正常工作的 Skill执行后应该满足三点第一输出格式和 SKILL.md 里定义的「输出格式」一致第二执行步骤里的动作都做了比如读取了 README、扫描了源文件第三没有多余的解释性文字直接给结果。如果输出里出现「我将要…」「接下来我会…」这种话说明 Skill 的步骤写得不够具体Claude 在自由发挥。把步骤改成明确的动作比如「读取 package.json 的 dependencies 字段」而不是「检查依赖」。5. 常见报错排查401、local proxy failed、reading choices、OAuthSkill 本身是本地文件报错大多出在接入层或加载层。这一节对照真实报错给排查路径。5.1 401 Unauthorized报错原文Error: 401 Unauthorized原因API Key 错误或过期。排查检查ANTHROPIC_API_KEY环境变量是否设置正确Key 有没有多余空格。去 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 重新生成一个 Key 试试。如果用的是 CC Switch检查 JSON 里的apiKey字段。5.2 local proxy failed报错原文Error: local proxy failed to connect原因Base URL 配置错误或者本地网络无法访问该地址。排查确认ANTHROPIC_BASE_URL是https://taotoken.net/api不要加/v1。用 curl 测一下连通性curl -I https://taotoken.net/api如果返回 200 或 401说明地址通如果超时检查本地网络设置。5.3 reading choices 相关报错报错原文Error: reading choices of undefined原因返回的数据结构不符合预期通常是 Model ID 写错了或者请求发到了不兼容的端点。排查确认ANTHROPIC_MODEL是模型对话页面里列出的有效 ID。如果用的是 OpenAI 兼容格式的端点Claude Code 可能解析不了要确保走的是 Anthropic 协议。5.4 OAuth 相关报错报错原文Error: OAuth token expired原因Claude Code 默认可能走 OAuth 登录流程但用 API Key 接入时不需要 OAuth。排查确认没有同时配置 OAuth 和 API Key。如果之前登录过清掉~/.claude/下的凭证缓存重新用 API Key 配置。5.5 Skill 不触发报错表现写了 Skill但 Claude 不加载。排查三步第一确认文件路径是.claude/skills/技能名/SKILL.md文件名必须是大写SKILL.md第二确认触发词在「适用场景」里且和用户输入有重叠第三用/debug看匹配结果。如果还不行用强制调用方式测试 Skill 内容本身有没有问题。5.6 参数没替换报错表现{{language}}原样出现在输出里。排查确认参数名拼写一致调用时参数格式是参数名值。如果 Skill 里写的是{{language}}调用时写languagepython不要写成langpython。6. 把重复流程固化成 Skill从代码审查到项目初始化Skill 的价值在于沉淀。你每遇到一个重复三次以上的流程就该考虑写成 Skill。这一节给两个实战例子你可以直接改成自己项目用的。6.1 代码审查 Skill.claude/skills/code-review/SKILL.md# 代码审查 Skill ## 描述 审查指定文件的代码质量检查命名、硬编码、异常处理、注释。 ## 适用场景 - 审查代码 - code review - 检查这个文件 ## 参数 - file: 要审查的文件路径必填 ## 执行步骤 1. 读取 {{file}} 文件内容 2. 检查变量和函数命名是否符合语言惯例 3. 检查是否有硬编码的密钥、密码、URL 4. 检查异常处理是否完整 5. 检查关键函数是否有注释 6. 按严重程度排序输出问题 ## 输出格式 表格形式列严重程度 | 行号 | 问题 | 建议 ## 注意事项 - 只报告确定的问题不猜测 - 严重程度分高、中、低调用claude 审查代码 src/main.py6.2 项目初始化 Skill.claude/skills/project-init/SKILL.md# 项目初始化 Skill ## 描述 初始化新项目生成基础目录结构和配置文件。 ## 适用场景 - 初始化项目 - 新建项目 ## 参数 - type: 项目类型python/node/java默认python - name: 项目名称必填 ## 执行步骤 1. 创建 {{name}} 目录 2. 根据 {{type}} 生成对应的目录结构 3. 生成 README.md包含项目名和用途占位 4. 生成 .gitignore 5. 生成依赖管理文件requirements.txt / package.json / pom.xml 6. 输出初始化报告 ## 输出格式 列出创建的文件和目录树。 ## 注意事项 - 如果目录已存在先询问是否覆盖 - 不自动执行 git init由用户决定调用claude 初始化项目typenodenamemy-app6.3 沉淀节奏建议不要一上来就写十个 Skill。先从最高频的那个流程开始写一个用一周根据实际触发情况调整触发词和步骤。稳定之后再写第二个。Skill 的质量比数量重要一个触发精准、步骤清晰的 Skill比十个模糊的 Skill 有用得多。如果你要把 Skill 用在团队协作里把.claude/skills/提交到 Git 仓库团队成员拉下来就能用。注意 API Key 不要提交用环境变量或本地配置文件管理。长期做编码和 Agent 类任务的话可以考虑 Coding Plan把常用 Skill 和模型调用打包管理 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。需要看模型对话效果的直接去 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 试。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API Key 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后说个实测经验Skill 的触发词不要写太多三到五个精准的词比二十个泛词有效。我试过在一个 Skill 里塞了十几个触发词结果误触发率飙升后来砍到四个反而稳定了。