1. 为什么你的 Claude Code 总在重复解释同一件事用 Claude Code 写代码最烦的不是它不会写而是每次开新会话都要重新交代一遍背景。比如你们团队规定所有 API 返回必须包一层{ code, data, message }数据库查询禁止SELECT *提交前必须跑eslint --fix。这些规则你第一次说得很清楚Claude 也照做了但关掉终端再打开它又变回那个什么都不知道的新人。我试过把规则塞进CLAUDE.md确实能解决一部分问题。但CLAUDE.md是全局注入的项目一大这个文件会膨胀到几千字每次对话都占着上下文窗口真正干活的空间被挤掉。更麻烦的是CLAUDE.md里的内容是无差别加载的——你写代码审查规则它在你问今天天气的时候也照样加载。Claude Code Skills 就是来解决这个矛盾的。你可以把它理解成给 Claude 配了一本按需翻阅的工作手册平时放在书架上不占地方当你说的话跟某本手册的主题对上了它才把那一本抽出来看。这个对上的过程就是触发机制而手册本身就是一个叫SKILL.md的 Markdown 文件。Skills 适合谁三类人最该用一是团队里有明确编码规范、想让 Claude 自动遵守的二是经常重复某类工作流比如写单元测试、做代码审查、生成 API 文档的三是维护多个项目、每个项目规则不同、不想每次都手动切换提示词的。如果你只是偶尔用 Claude Code 问几个零散问题那CLAUDE.md够用了Skills 的收益不明显。这篇手册会从SKILL.md的目录结构讲起拆解元信息怎么写、触发机制怎么运作、插件加载顺序是什么最后给你一份可以直接复制的模板和本地验证步骤。全程用命令行操作跟着敲就行。2. TaoToken 前置准备让 Claude Code 稳定跑起来在折腾 Skills 之前得先保证 Claude Code 本身能正常调用模型。Claude Code 默认走 Anthropic 官方接口国内直连经常超时或者报local proxy failed。我的做法是把它指向 TaoToken 的兼容端点这样请求走一个稳定的入口Skills 的调试过程不会被网络问题打断。TaoToken 是一个模型调用聚合服务提供 Anthropic 兼容的 API 端点Claude Code、Cline、Codex 这些工具都能接。官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 注意这个地址后面不加任何参数。第一步去控制台拿 Key。打开 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 登录后在 API Keys 页面创建一个新 Key复制出来。这个 Key 只显示一次丢了就得重建。第二步配置 Claude Code 的环境变量。Claude Code 读取ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY两个变量。在~/.zshrc或~/.bashrc里加上export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的Key然后source ~/.zshrc让它生效。如果你用的是 Windows在 PowerShell 里用$env:ANTHROPIC_BASE_URLhttps://taotoken.net/api这种写法或者直接写进系统环境变量。第三步验证连通性。跑一个最简单的请求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-20250514, max_tokens: 100, messages: [{role: user, content: 回复 OK 两个字}] }如果返回里能看到text: OK之类的字段说明链路通了。这一步很重要因为后面调试 Skills 触发的时候如果模型根本没响应你分不清是 Skill 没触发还是网络挂了。关于模型 IDClaude Code 里常用的有claude-sonnet-4-20250514、claude-opus-4-20250514这些。具体支持哪些可以在模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 里试一下那边有可视化的模型选择器能直接看到当前可用的模型列表。如果你打算长期用 Claude Code 做编码和 Agent 任务可以考虑 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 按套餐走比按量计费省心一些。不过这是后话先把 Skills 跑通再说。3. SKILL.md 目录结构与元信息写法附可复制模板Skills 的物理形态就是一个目录目录名就是 Skill 的名字里面必须有一个SKILL.md。这个文件分两部分顶部的 YAML frontmatter 是元信息下面的 Markdown 正文是给 Claude 看的指令。先看目录结构。一个完整的 Skill 长这样my-plugin/ └── skills/ └── code-review-guide/ ├── SKILL.md ├── references/ │ └── security-checklist.md ├── examples/ │ └── sample-review.md └── scripts/ └── scan.shSKILL.md是唯一必需的文件references/、examples/、scripts/都是可选的。这三个目录的作用后面会讲先记住它们的存在。现在看SKILL.md的元信息。frontmatter 用---包起来里面至少要有name和description两个字段--- name: code-review-guide description: This skill should be used when the user asks to review code, check code quality, review this function, analyze code, or requests code review feedback. Provides comprehensive code review standards, security checks, and best practices. version: 1.0.0 ---name是 Skill 的标识符用小写字母加连字符别用空格和大写。description是触发机制的核心Claude 就是靠读这段文字来判断当前对话要不要加载这个 Skill。写description有个关键原则用第三人称以 This skill should be used when... 开头然后把用户可能说的原话用引号列出来。对比一下好坏两种写法# 好的写法具体、包含用户原话、第三人称 description: This skill should be used when the user asks to create a hook, add a PreToolUse hook, validate tool use, or mentions hook events (PreToolUse, PostToolUse, Stop). # 差的写法太笼统Claude 判断不了什么时候该加载 description: Use this skill when working with hooks. # 差的写法第一人称不符合规范 description: I will help you with code review.version字段是可选的但建议加上方便团队协作时追踪变更。还可以加license、maintainers这些不影响触发纯粹是给人看的。frontmatter 下面是正文。正文的写法有讲究用命令式语气直接说做什么不要用你应该这种第二人称。比如# Code Review Guide This skill provides standardized code review guidance focusing on security, performance, and maintainability. ## Core Review Principles When reviewing code, evaluate these aspects: ### 1. Security - Check for injection vulnerabilities (SQL, command, XSS) - Verify input validation and sanitization - Ensure sensitive data is handled properly - Review authentication and authorization logic ### 2. Performance - Identify unnecessary computations - Check for N1 query problems - Review algorithm complexity - Verify proper resource cleanup ### 3. Maintainability - Evaluate code clarity and readability - Check for appropriate abstraction - Verify error handling completeness - Review test coverage ## Review Process 1. **Understand Intent** - Read code and comments, identify purpose and requirements 2. **Identify Issues** - Use static analysis patterns, look for anti-patterns 3. **Provide Feedback** - Explain why its an issue, suggest specific improvements 4. **Prioritize Findings** - Mark critical vs optional, group related issues ## Additional Resources ### Reference Files - **references/security-checklist.md** - Detailed security review checklist - **references/performance-patterns.md** - Performance optimization patterns ### Example Reviews - **examples/sample-review.md** - Example of a thorough code review正文控制在 1500 到 2000 字之间比较合适。太短了信息不够太长了每次加载都占上下文。如果内容确实多就把细节挪到references/目录里正文只留一个引用链接。references/放详细文档Claude 需要的时候才会去读。examples/放可以直接复制的工作示例。scripts/放可执行脚本比如自动化检查工具。这三个目录的内容不会在 Skill 触发时全部加载只有 Claude 主动去读某个文件时才会加载这就是渐进式披露——先加载核心需要细节再加载细节。4. 触发机制与插件加载顺序Skill 什么时候被唤醒理解触发机制才能写出该触发时触发、不该触发时不触发的 Skill。Claude Code 启动时会扫描所有已安装插件里的skills/目录把每个SKILL.md的 frontmatter 读进来但正文不读。这些元信息构成一个技能索引常驻在上下文里。当你发一条消息Claude 先拿这条消息去跟索引里的description做匹配匹配上了才把对应的SKILL.md正文加载进来。这个设计的好处是省上下文。假设你装了 20 个 Skill每个正文 2000 字全加载就是 4 万字上下文窗口直接爆掉。但只加载元信息的话20 个description加起来可能才 1000 字完全无压力。匹配的粒度是关键词和短语。所以description里列的用户原话越具体匹配越准。比如你写review code、check code quality用户说 can you review this code 就能命中但如果你只写code那用户说 write some code 也会误触发。插件加载顺序方面Claude Code 按这个优先级扫描项目级.claude/skills/目录当前项目专用用户级~/.claude/skills/目录全局所有项目共享通过--plugin-dir参数指定的插件目录已安装的插件包同名 Skill 的情况下项目级覆盖用户级。这个机制让你可以给不同项目配不同的 Skill互不干扰。验证加载顺序有个简单办法在两个位置放同名 Skill内容里写不同的标记然后触发它看 Claude 用的是哪个。比如项目级写 PROJECT VERSION用户级写 USER VERSION触发后看输出里出现哪个。触发测试清单创建 Skill 后挨个试直接请求Please use code-review-guide to check this间接提及I need a code review for this function模糊表达Can you look at this code and tell me if its good边界情况Whats the weather today不应该触发如果直接请求能触发但间接提及不行说明description里的关键词覆盖不够。如果边界情况也触发了说明description写得太宽泛需要加限定词。还有一个容易踩的坑description里如果用了某个词但这个词在你的日常对话里高频出现会导致频繁误触发。比如你写description: ...when the user mentions function...那你每次说 write a function 都会触发代码审查 Skill很烦。解决办法是把触发词写得更完整比如review this function而不是单独的function。5. 常见报错排查401、local proxy failed、reading choices调试 Skills 的过程中报错基本集中在几个地方。下面按我实际遇到的顺序列出来。401 Unauthorized这个最直接Key 不对或者没传。检查三件事ANTHROPIC_API_KEY环境变量有没有生效echo $ANTHROPIC_API_KEY看一下、Key 有没有多余空格、Key 是不是在控制台被删了。如果用的是 TaoToken 的 Key确认地址是https://taotoken.net/api不要加/v1后缀Claude Code 会自己拼路径。local proxy failed / connection refused这个报错通常出现在 Claude Code 启动阶段说明它连不上ANTHROPIC_BASE_URL。先curl一下那个地址看通不通。如果 curl 通但 Claude Code 报错检查是不是有别的环境变量在干扰比如HTTP_PROXY、HTTPS_PROXY这些。把它们 unset 掉再试unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxyError reading choices / unexpected response format这个报错说明请求发出去了但返回的 JSON 结构跟 Claude Code 预期的不一样。常见原因是模型 ID 写错了或者端点返回了错误信息但被当成正常响应解析。检查ANTHROPIC_MODEL环境变量确认模型 ID 是有效的。可以在模型对话页面手动发一条消息看返回结构对不对。Skill 不触发如果模型正常响应但 Skill 就是不加载按这个顺序查先确认文件位置对。ls -la .claude/skills/code-review-guide/SKILL.md文件得真实存在。然后确认 frontmatter 格式对---必须是文件第一行不能有空行在前面。再确认description里有具体的触发短语。最后看 Claude Code 的日志输出通常会有 Loading skill: xxx 这样的记录。Skill 误触发反过来如果不想触发的时候触发了把description收窄。加限定词比如review this function而不是function。或者用括号排除比如...when working with Git hooks (not webhooks)...。资源文件找不到SKILL.md里引用references/security-checklist.md但 Claude 说找不到。检查路径是相对于SKILL.md所在目录的不要写成skills/code-review-guide/references/...这种全路径。另外注意大小写Linux 下References和references是两个不同的目录。脚本无法执行scripts/scan.sh报权限错误chmod x scripts/scan.sh加上执行权限。脚本第一行要有 shebang比如#!/bin/bash或#!/usr/bin/env python3。如果脚本依赖某个命令在SKILL.md里写清楚比如 This skill requiresjqcommand-line tool。排查的时候有个通用思路先确认模型调用本身没问题用 curl 测再确认 Skill 文件被扫描到了看日志最后确认触发词匹配上了换更直接的说法试。这三层逐层排除基本能定位到问题。6. 把重复工作流沉淀成可复用技能Skills 真正的价值不在于写一个两个而在于把团队里那些每次都要说一遍的规则固化下来。我现在的做法是每当发现自己在对话里第三次解释同一件事就停下来把它写成一个 Skill。写 Skill 的时候description花的时间应该比正文还多。正文写一次就不用动了但description决定了它能不能在正确的时机被唤醒。我的习惯是先把用户可能说的原话列出来挑最典型的五到八个塞进description然后用 This skill should be used when the user asks to... 串起来。团队协作的话把 Skill 目录放进 Git 仓库用 submodule 挂到各个项目的.claude/skills/下。这样规则更新一次所有项目同步。每个 Skill 配一个CHANGELOG.md记录版本变更方便回溯。最后给一个可以直接复制的模板拿去改改就能用--- name: your-skill-name description: This skill should be used when the user asks to 触发短语1, 触发短语2, 触发短语3, or mentions 相关主题. version: 1.0.0 --- # Your Skill Title 一句话说明这个 Skill 提供什么。 ## Core Principles ### 1. 原则一 - 具体规则 - 具体规则 ### 2. 原则二 - 具体规则 - 具体规则 ## Process 1. **步骤一** - 说明 2. **步骤二** - 说明 3. **步骤三** - 说明 ## Additional Resources ### Reference Files - **references/detail.md** - 详细说明 ### Examples - **examples/sample.md** - 示例创建目录、写文件、测试触发三步走完。如果触发不理想回头改description别改正文。正文是给触发之后的 Claude 看的description才是决定触发与否的关键。