Claude Code + Skills 使用教程：用 SKILL.md 把常用流程沉淀成可复用能力

1. 为什么要把重复流程沉淀成 Claude Code Skills如果你已经在用 Claude Code 写代码大概率遇到过这种场景每次让它做代码审查都要重新交代一遍「先看命名规范、再看边界条件、最后输出 diff 格式」每次让它生成接口文档都要把字段说明、示例格式、Markdown 模板重新贴一遍。这些流程本身是固定的但每次对话都要重新描述既费 token 又容易漏步骤。Claude Code Skills 解决的正是这个问题。它本质上是一份写给 AI 看的操作说明书用 Markdown 文件固定文件名SKILL.md把某类任务的执行流程、输出格式、参考资料固化下来。写一次之后无论是自动匹配触发还是用 slash 命令手动调用AI 都会按你设定的 SOP 执行。适合谁用适合所有在 Claude Code 里反复做同类任务的人——代码审查、文档生成、SQL 优化、组件重构只要流程能说清楚就能沉淀成 Skill。它和普通 Prompt 最大的区别在于加载机制。普通 Prompt 每次都要全量塞进上下文而 Skills 采用渐进式加载启动时 Claude Code 只读取每个 Skill 的name和description做识别只有当任务匹配到某个 Skill 的描述时才把完整的SKILL.md指令读进上下文需要模板或脚本时再按需加载对应文件。这意味着你可以维护几十个 Skill但日常对话的上下文占用几乎不受影响。再打个比方。把 Claude 想象成一个聪明但没经验的新人普通 Prompt 是你每次从头教他做事Rule 是贴在工位上的行为守则一直生效但只管格式和态度MCP 是给他电脑装了一堆软件和 API他能调用外部工具但不知道什么时候该用而 Skills 是直接给他一整套岗位培训大礼包——SOP、流程图、话术模板、常用脚本全在里面告诉他「遇到这类活就按这个文件夹里的方法来」。Skills 负责知识复用MCP 负责能力扩展两者配合才能把重复流程真正固化下来。这篇教程会从目录结构讲起给出可直接复制的SKILL.md模板再说明如何通过统一 Key/API 通道接入最后逐项验证触发是否生效。全程以 Claude Code 为例配置可以照抄。2. TaoToken 前置统一 Key 与 API 通道接入 Claude Code在写 Skill 之前先把 Claude Code 的模型通道配好。很多人卡在第一步不是不会写SKILL.md而是 Claude Code 的请求发不出去或者 Key 管理混乱。这里我用 TaoToken 作为统一通道一个 Key 覆盖模型对话和编码场景省去在多个平台之间切换的麻烦。TaoToken 的定位是统一的模型 API 接入层官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。它的作用是让你用一套 Base URL 和 Key就能在 Claude Code、Cline、Codex 等客户端里调用模型不用每个工具单独配一遍。先说清楚 Claude Code 的配置逻辑。Claude Code 读取环境变量来决定请求发往哪里核心是三个ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_MODEL。Base URL 指向 TaoToken 的 API 地址Auth Token 填你在控制台生成的 KeyModel 填你要用的模型 ID。这三件套配齐Claude Code 才能正常发起请求。第一步去控制台生成 Key。打开 https://taotoken.net/console 登录后在 API Keys 页面创建一个新 Key复制保存。注意 Key 只在创建时完整显示一次丢了就得重新生成。第二步配置环境变量。Windows 下可以在 PowerShell 里临时设置也可以写进系统环境变量长期生效。临时设置如下$env:ANTHROPIC_BASE_URL https://taotoken.net/api $env:ANTHROPIC_AUTH_TOKEN sk-你的Key $env:ANTHROPIC_MODEL claude-sonnet-4-20250514macOS 或 Linux 下写进~/.zshrc或~/.bashrcexport ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你的Key export ANTHROPIC_MODELclaude-sonnet-4-20250514改完记得source ~/.zshrc让配置生效。第三步如果你用的是 Claude Code 的 settings 文件方式可以在~/.claude/settings.json里写{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的Key, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }这个文件的好处是配置跟着 Claude Code 走不依赖 shell 环境换终端也不会丢。第四步验证通道是否通。在终端里跑一句最简单的请求curl https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的Key \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 64, messages: [{role: user, content: 回复 ok}] }如果返回里能看到content字段和正常的文本说明 Key 和通道都没问题。如果返回 401说明 Key 不对或没带上如果返回连接错误检查 Base URL 是不是写成了带路径的完整地址。这里有个容易踩的坑Base URL 到底填https://taotoken.net/api还是https://taotoken.net/api/v1Claude Code 内部会自己拼接/v1/messages所以环境变量里填到/api就够了多写/v1会变成/api/v1/v1/messages直接 404。这个细节我在配置 Cline 的时候也踩过两个客户端的拼接规则不一样Claude Code 认/api结尾。通道配好之后Claude Code 就能正常对话了。接下来才是重点怎么把重复流程写成 Skill让它自动触发。3. 可复制配置SKILL.md 目录结构与完整模板Skill 的核心结构非常简单一个文件夹加一个SKILL.md文件。文件夹名就是技能标识推荐用 kebab-case小写字母加连字符比如code-comment-expert、postgres-expert。SKILL.md是唯一必需的文件里面分两部分顶部的 YAML frontmatter 元数据和下面的 Markdown 正文指令。先看 Claude Code 查找 Skill 的优先级顺序越具体的位置优先级越高级别路径生效范围企业级管理控制台配置组织内所有用户个人级~/.claude/skills/skill-name/SKILL.md你所有项目项目级.claude/skills/skill-name/SKILL.md仅当前项目插件级plugin/skills/skill-name/SKILL.md启用该插件的环境个人级适合放通用技能比如代码注释、文档生成项目级适合放跟当前仓库强相关的技能比如「本项目的 API 响应格式规范」。我一般把通用技能放个人级项目特有的放项目级这样换项目时通用能力还在。最小可用的SKILL.md只需要两个字段--- name: skill-name description: 说明该 Skill 的功能以及适用场景 ---但要让自动触发稳定光有这两个字段不够。description是 Claude 判断是否加载这个 Skill 的关键写得越具体、越贴近真实触发场景命中率越高。我建议在 frontmatter 里额外加一个trigger_keywords字段把用户可能说的口语化表达都列进去。下面是一个完整的、可直接复制的SKILL.md模板以「代码注释专家」为例--- name: code-comment-expert description: - 为代码添加专业、清晰的中英双语注释。 适合缺少文档、可读性差、需要分享审查的代码。 常见触发场景加注释、注释一下、加文档、explain this、improve readability trigger_keywords: - 加注释 - 注释 - 加文档 - explain code - document - comment this - readability version: 1.0 author: yourname --- # 专业代码注释专家 你现在是「专业代码注释专家」。 ## 核心原则 - 只在缺少注释或可读性明显不足处添加 - 优先使用英文 JSDoc / TSDoc 风格 - 复杂逻辑 / 非明显意图处额外加一行中文解释 - 注释精炼每行不超过 80 字符 - 绝不修改原有逻辑 ## 输出格式严格遵守 1. 先输出完整修改后的代码块用 语言 包裹 2. 再用 diff 形式展示只改动注释的部分 3. 最后说明加了哪些注释、理由 现在直接开始处理用户提供的代码不要闲聊。这个模板的关键点在于description用了-折叠写法把功能、适用场景、触发场景分三行写清楚trigger_keywords覆盖了中英文口语表达正文里用「核心原则」和「输出格式」把执行规则固定下来最后一句「不要闲聊」是防止模型在输出前加一堆解释。当技能变复杂超过 500 到 800 行或者需要模板、脚本、参考资料时推荐用扩展目录结构~/.claude/skills/react-component-review/ ├── SKILL.md # 核心指令 元数据建议控制在 400 行内 ├── templates/ # 常用模板Claude 按需读取 │ ├── functional.tsx.md │ └── class-component.md ├── examples/ # 优秀/反例给 Claude 看标准 │ ├── good.md │ └── anti-pattern.md ├── references/ # 规范、规则、禁用词表 │ ├── hooks-rules.md │ └── naming-convention.md └── scripts/ # 可执行脚本需开启 code execution ├── validate-props.py └── check-cycle-deps.sh在SKILL.md正文里引用这些文件时直接写相对路径需要给出标准函数组件时参考 templates/functional.tsx.md 的结构。 如果违反 Hooks 规则对照 references/hooks-rules.md 第 3–5 条说明。 如需校验 propTypes可执行 scripts/validate-props.py {代码片段}。Claude 看到路径引用后会按需加载对应文件而不是一次性全部塞进上下文。这就是渐进式加载的价值——主指令保持精简重资料放在旁边用到才读。如果你用的是 Cline 或 Codex配置逻辑类似但文件位置不同。Cline 的 MCP 配置在cline_mcp_settings.jsonCodex 的认证信息在auth.json。无论哪个客户端三件套都是 Base URL、Key、Model ID缺一不可。TaoToken 的好处是这三个值在所有客户端里通用换工具不用重新申请。4. 验证请求创建第一个 Skill 并确认触发生效配置写完了得实际跑一遍才知道有没有生效。这一节我带你从零创建一个 PostgreSQL 专家 Skill然后验证它能不能被正确触发。第一步创建目录。在项目根目录下建.claude/skills/postgres-expert/mkdir -p .claude/skills/postgres-expert cd .claude/skills/postgres-expert第二步写SKILL.md。内容如下可以直接复制--- name: postgres-expert description: - 精通 PostgreSQL SQL 语法、查询优化、数据库设计与管理的专家。 适合编写复杂查询、设计索引、排查慢 SQL、处理事务并发问题。 常见触发场景pg 优化、postgres 慢查询、索引建议、执行计划分析 trigger_keywords: - postgresql - pgsql - pg - 慢查询 - 执行计划 - 索引优化 version: 1.0 author: xwf --- # PostgreSQL 数据库专家技能 ## 简介 你是一个专注于 PostgreSQL 数据库的专家熟悉从 SQL 语法到性能调优、从事务管理到高可用架构的方方面面。 ## 核心职责 - SQL 语法支持编写符合 PostgreSQL 标准的 SQL包括 DDL、DML、窗口函数、CTE - 查询优化分析执行计划推荐索引、重写查询或调整参数 - 数据库设计表结构设计、规范化、分区表、数据类型选择 - 事务与并发解释隔离级别、锁机制、MVCC解决死锁 - 故障排查诊断连接问题、性能瓶颈、磁盘 I/O 异常 ## 行为准则 1. 精准回答基于 PostgreSQL 官方文档和最佳实践 2. 示例优先尽可能附带可执行的 SQL 示例 3. 引导式沟通问题不完整时主动索要表结构、查询语句、EXPLAIN 输出 4. 安全提醒涉及 DELETE、UPDATE、DROP 时提醒先备份 5. 版本意识不同版本功能有差异建议用户说明版本号 ## 输出格式 1. 先给出问题分析 2. 再给出可执行的 SQL 或配置 3. 最后说明优化理由和注意事项第三步启动 Claude Code 并验证。在项目根目录运行claude进入交互界面后先确认 Skill 被识别。输入/skills或查看启动日志应该能看到postgres-expert出现在已加载列表里。如果没看到检查目录层级是不是.claude/skills/postgres-expert/SKILL.md少一层或多一层都不会被扫描到。第四步触发测试。输入一个贴近真实场景的问题pg 数据库请帮我统计一下每个部门前三的薪资 sql如果 Skill 生效Claude 会按SKILL.md里定义的输出格式回应先分析需求再给出带ROW_NUMBER()窗口函数的 SQL最后说明为什么用窗口函数而不是LIMIT。如果它只是泛泛回答、没有按格式走说明 Skill 没被加载回到上一步检查路径和 frontmatter 格式。第五步验证渐进式加载。故意问一个跟 PostgreSQL 无关的问题比如「帮我写个 Python 快速排序」。如果 Skill 机制正常Claude 不会加载postgres-expert的完整指令回答里也不会出现 SQL 相关的格式约束。这说明按需加载在工作——只有匹配到描述时才读完整内容。第六步验证 slash 命令触发。Claude Code 会把 Skill 的name注册成 slash 命令输入/postgres-expert应该能手动调用。手动调用适合那些描述匹配不到、但你想强制走某个流程的场景。实测下来触发成功率主要取决于description和trigger_keywords的质量。如果发现某个 Skill 老是不触发把用户可能说的原话直接加进trigger_keywords命中率会明显提升。比如用户说「这条 SQL 跑得慢」你就把「跑得慢」加进去而不是只写「性能优化」。5. 本篇常见错排查401、local proxy failed 与 OAuth 报错配置和触发过程中最容易卡在几个固定报错上。这一节把真实遇到的错误和排查路径列出来对照着查能省不少时间。报错一401 UnauthorizedAPI Error: 401 {error:{type:authentication_error,message:invalid x-api-key}}这个报错说明 Key 没带上、带错了或者环境变量没生效。排查顺序先确认ANTHROPIC_AUTH_TOKEN的值是不是完整的sk-开头字符串有没有多余空格再确认这个 Key 在 TaoToken 控制台里是启用状态最后确认环境变量真的被 Claude Code 读到了——在终端里echo $ANTHROPIC_AUTH_TOKEN看有没有输出。如果是 Windows 用echo $env:ANTHROPIC_AUTH_TOKEN。如果环境变量在 shell 里有、但 Claude Code 里没有可能是启动方式不对试试写进~/.claude/settings.json的env字段。报错二local proxy failed / connection refusedError: local proxy failed: dial tcp 127.0.0.1:7890: connect: connection refused这个报错通常是系统里配了本地代理但代理服务没启动或者 Claude Code 继承了代理环境变量。检查HTTP_PROXY、HTTPS_PROXY、ALL_PROXY这几个变量如果指向一个没运行的本地端口就会报这个错。解决方式是清掉这些变量或者确保代理服务在运行。注意 TaoToken 的 API 地址是直连的不需要额外代理配置。报错三reading choices / 响应解析失败Error: reading choices: unexpected end of JSON input这个报错一般出现在流式响应被中断或者返回内容不是预期的 JSON 结构。常见原因是 Base URL 写错了请求打到了一个不返回标准格式的地址。确认ANTHROPIC_BASE_URL填的是https://taotoken.net/api不要带/v1也不要带尾部斜杠。另外检查 Model ID 是不是有效填了一个不存在的模型名服务端可能返回空响应。报错四OAuth / 登录态冲突Error: OAuth token expired, please re-authenticate如果你之前用官方账号登录过 Claude Code本地可能存了 OAuth 凭证跟环境变量里的 Key 冲突。Claude Code 优先用 OAuth 还是环境变量取决于版本和配置。解决方式是清理本地登录态或者显式在settings.json里指定用 API Key 模式。具体做法是删掉~/.claude/下的凭证缓存文件重新用环境变量启动。报错五Skill 不触发这个不算报错但最常见。表现是明明写了SKILL.mdClaude 却完全不按里面的格式走。排查三点一是路径对不对个人级是~/.claude/skills/项目级是.claude/skills/别搞混二是 frontmatter 格式对不对---必须是文件第一行name和description不能少三是description够不够具体太笼统的描述匹配不到具体任务。把trigger_keywords加上用用户的原话做关键词。三件套检查清单无论哪个客户端配置出问题时先核对这三项配置项Claude CodeClineCodexBase URLANTHROPIC_BASE_URLcline_mcp_settings.json里的 baseUrlauth.json里的 base_urlKeyANTHROPIC_AUTH_TOKEN同上 apiKey 字段同上 api_key 字段Model IDANTHROPIC_MODEL同上 model 字段同上 model 字段三项里任何一项缺失或写错都会导致请求失败。Base URL 统一填https://taotoken.net/apiKey 用控制台生成的Model ID 用有效的模型名。这三件套在 TaoToken 的所有客户端里通用配一次就能复用。排障时如果拿不准先去 https://taotoken.net/api-keys 确认 Key 状态再看 https://taotoken.net/doc 里的接入文档核对参数格式。文档里有各客户端的完整配置示例比对着改最快。6. 把 Skill 用起来从单点能力到可复用工作流Skill 写出来只是第一步真正省时间的是把它嵌进日常工作流。我自己的做法是凡是同一类任务做过三次以上就停下来把它写成 Skill。代码审查、接口文档生成、SQL 优化、组件重构这几个是我用得最多的。代码审查 Skill 的写法跟注释专家类似但重点在检查项清单。把团队规范拆成一条条可执行的检查项比如「函数参数超过 4 个要提醒」「异步调用必须有错误处理」「公共方法必须有 JSDoc」写进SKILL.md的正文。这样每次审查Claude 会按清单逐条过不会漏。文档生成 Skill 适合配合模板目录。把接口文档的 Markdown 模板放在templates/下SKILL.md里写清楚「读取 templates/api-doc.md 的结构按字段说明、请求示例、响应示例、错误码四段填充」。Claude 生成时会自动套模板输出格式统一。MCP 和 Skill 的配合是另一个提效点。MCP 负责让 Claude 能调用外部工具比如查数据库、读文件、调 APISkill 负责告诉它什么时候用、怎么组合用。举个例子你有一个查数据库的 MCP 工具再写一个「慢查询分析」Skill里面规定「先用 MCP 执行 EXPLAIN再根据输出判断是否缺索引最后给出 CREATE INDEX 建议」。这样一句话就能触发整套流程不用每次手动指挥。长期做编码和 Agent 任务的话可以考虑用 Coding Plan 把模型调用额度固定下来避免按次计费的不确定性。入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 适合高频使用 Claude Code 的场景。最后说一个实用技巧Skill 的description要定期维护。用了一段时间后回顾一下哪些问法触发了、哪些没触发把没触发的原话补进trigger_keywords。这个动作花不了几分钟但能让 Skill 的命中率持续提升。我一般每个月过一遍把新出现的口语表达加进去。如果你还没开始写第一个 Skill就从最简单的代码注释专家开始。复制第 3 节的模板改一下name和description放到~/.claude/skills/下启动 Claude Code 试一句「帮我给这段代码加注释」。跑通了再往复杂流程扩展。