1. 为什么零散提示词需要沉淀成 Claude Skills很多人用 Claude 的路径都差不多一开始在对话框里手敲提示词调顺了以后存进备忘录下次用的时候再复制粘贴。单个任务这样没问题但当你手上有十几个常用场景——代码评审、周报生成、竞品分析、论文润色——每次都要翻备忘录找对应那段话还要手动补上背景资料效率很快就见顶了。Claude Skills 解决的正是这个断层。你可以把它理解成给 Claude 装的一个「技能包」一个文件夹里面放一份说明文件告诉 Claude 这个技能是干什么的、什么时候该用再放上这个技能专属的知识库文件。加载之后Claude 会在合适的时机自动调用它不需要你每次重新交代背景。它和单纯的长提示词有几个实质区别。第一技能包可以挂载文件提示词只能靠你粘贴文本几十页的规范文档塞进对话既费 token 又容易丢上下文。第二技能是按需触发的你装了十个技能Claude 只在当前任务匹配某个技能时才读取它的内容不会把所有技能全文都塞进上下文。第三技能包是文件系统里的实体可以版本管理、可以分享给同事、可以随项目走。适合谁如果你已经有几个调得比较顺的提示词并且发现自己反复在补同样的背景资料那就是该做技能包的时候了。如果你还在摸索提示词本身怎么写建议先把单个场景的提示词打磨稳定再考虑封装。这篇会走完一条完整路径先讲清楚 Skills 的目录结构长什么样再给出可复制的配置示例然后演示怎么在 Claude 客户端里加载、触发、验证技能真的生效了最后把几个高频报错逐个拆开。全程以能跟着操作为准不堆概念。需要说明的是Skills 的加载和调用依赖 Claude 客户端本身的能力而如果你想把技能包里的自定义工具接到外部 API或者想在编码场景里让 Claude Code 调用这些技能就需要一个稳定的 API 接入点。后面会讲到用 TaoToken 作为接入层来打通这部分它的 Base URL 和 Key 管理方式对多技能、多模型的场景比较友好。2. Claude Skills 目录结构与 skill.md 配置示例先看结构。一个技能包本质上就是一个文件夹Claude 客户端在扫描技能目录时会读取每个子文件夹里的入口文件。目前主流的结构是这样~/.claude/skills/ ├── code-reviewer/ │ ├── SKILL.md │ ├── references/ │ │ ├── style-guide.md │ │ └── common-pitfalls.md │ └── assets/ │ └── review-template.md ├── weekly-report/ │ ├── SKILL.md │ └── references/ │ └── report-format.md └── paper-polish/ ├── SKILL.md └── references/ └── terminology.csv每个技能文件夹里必须有一个SKILL.md这是入口。references/放知识库文档assets/放模板类文件这两个目录名字不是强制的但用统一命名方便你自己维护。Claude 读取SKILL.md时会根据里面的描述判断这个技能是否和当前任务相关相关才会进一步读取引用的文件。SKILL.md的写法有固定套路。它由两部分组成开头的 YAML frontmatter 和正文。frontmatter 里最关键的是name和descriptiondescription 写得好不好直接决定 Claude 能不能在正确时机触发这个技能。--- name: code-reviewer description: 当用户要求评审代码、检查代码质量、寻找潜在 bug 或提出重构建议时使用。适用于 Python、TypeScript、Go 项目。不适用于从零生成新代码。 --- # 代码评审技能 你是一名资深代码评审员遵循以下规则工作。 ## 评审流程 1. 先通读用户提供的代码识别语言和框架 2. 对照 references/style-guide.md 中的规范逐条检查 3. 对照 references/common-pitfalls.md 排查高频问题 4. 按 assets/review-template.md 的格式输出评审结果 ## 输出要求 - 每个问题标注严重程度阻塞 / 建议 / 提示 - 阻塞级问题必须给出修改后的代码片段 - 不要泛泛而谈「建议优化」要指出具体行号和原因 ## 知识边界 只基于用户提供的代码和 references 目录下的文档作答。 如果代码依赖的外部库行为不确定明确说明「需要确认该库版本行为」不要猜测。这里有几个细节值得展开。description 里我特意写了「不适用于从零生成新代码」这是负向边界。Claude 在判断是否触发技能时负向描述能有效减少误触发——否则你让它写个新函数它也可能把评审技能拉出来。正文里的「知识边界」段落也很重要。技能包挂载了文档但 Claude 默认还是可能用训练数据里的知识来补充。如果你希望它严格基于你给的资料回答就要在 SKILL.md 里明确写死这条规则否则它会在资料不足时自己编。再看一个带 CSV 知识库的例子论文润色技能--- name: paper-polish description: 当用户要求润色学术论文、修改英文表达、统一术语或检查学术写作规范时使用。适用于计算机、生物、物理领域的英文论文。 --- # 学术论文润色技能 你是一名学术论文润色专家。 ## 术语一致性 读取 references/terminology.csv该文件包含本领域标准术语对照表。 润色时如果原文术语与表中不一致以表中为准并在输出末尾列出所有改动。 ## 润色原则 - 保持作者原意不改变论证结构 - 被动语态改为主动语态除非学术惯例要求被动 - 长句拆分单句不超过 35 词 - 不添加原文没有的引用或数据 ## 输出格式 先给出润色后的全文再给出改动清单表格原句 / 改后 / 改动原因。terminology.csv的内容大概长这样wrong,correct,note neural net,neural network,正式论文用全称 deep learning model,deep learning model,保持 data set,dataset,已合并为单词这种 CSV 挂载的方式比把术语表写进提示词要清晰得多而且改术语表不用动 SKILL.md。目录结构定下来之后下一步是让 Claude 真正加载它。这里分两条路一条是在 Claude 客户端里配置技能目录另一条是通过 API 接入时把技能作为上下文注入。两条路的配置方式不同下面分别给。3. 可复制配置settings.json 与 API 接入参数Claude 客户端读取技能目录靠的是配置文件里的路径声明。不同客户端的配置文件名不一样Claude Code 用的是settings.json位置通常在~/.claude/settings.json。如果你用的是桌面客户端配置入口在设置里的 Skills 面板但底层还是写同一个文件。先给 Claude Code 的配置。打开~/.claude/settings.json加入 skills 相关字段{ skills: { enabled: true, directories: [ /Users/yourname/.claude/skills ], autoTrigger: true, maxActiveSkills: 3 }, api: { baseUrl: https://taotoken.net/api, apiKey: sk-your-taotoken-key, model: claude-sonnet-4-20250514 } }几个字段说明一下。directories是技能目录列表可以配多个Claude 会全部扫描。autoTrigger设为 true 时Claude 根据 SKILL.md 的 description 自动判断是否触发设为 false 则只在你手动点名技能时才加载。maxActiveSkills限制同时激活的技能数量设成 3 是为了避免上下文被多个技能的知识库撑爆——每个技能挂载的文档都会占用 token。api段是接入层配置。Base URL 填https://taotoken.net/apiKey 在 TaoToken 控制台的 API Keys 页面生成。模型 ID 要写全Claude 的模型 ID 格式是claude-系列-版本-日期写错了会直接报模型不存在。如果你用的是 Cline 或者带 MCP 的编辑器插件配置方式换成 MCP 的 JSON 格式。以 Cline 的 MCP 配置为例在cline_mcp_settings.json里加{ mcpServers: { claude-skills: { command: npx, args: [-y, anthropic-ai/claude-skills-mcp], env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-your-taotoken-key, SKILLS_DIR: /Users/yourname/.claude/skills } } } }这里三件套要写全Base URL 是https://taotoken.net/apiKey 是 TaoToken 生成的sk-开头字符串Model ID 在调用时通过参数传入或在客户端设置里指定。少任何一个都会在启动时报错。如果你用的是 Codex 系的工具认证信息写在~/.codex/auth.json{ base_url: https://taotoken.net/api, api_key: sk-your-taotoken-key, model: claude-sonnet-4-20250514 }注意 Codex 的字段名是下划线风格和 Claude Code 的驼峰不一样别混用。配置写完重启客户端。重启后在对话里输入/skills或者查看技能面板应该能看到你放在目录里的技能列表。如果列表是空的先检查directories路径有没有写错路径要用绝对路径~在某些客户端里不会被展开。技能加载成功但没触发是另一个常见情况。这时候先确认autoTrigger是 true再检查 SKILL.md 的 description 是不是写得太窄。比如你写「当用户要求评审 Python 代码时使用」那用户说「帮我看看这段 TypeScript」就不会触发。description 要覆盖你实际会用的说法。配置这块踩过的坑基本集中在路径和字段名上。路径写相对路径、字段名大小写写错、Key 里混入空格这三类占了报错的大头。配好之后建议先用一个最简单的技能测试确认链路通了再往上加复杂技能。4. 验证技能生效从触发到结果确认配置写完不代表技能真的在工作。你需要一套验证动作确认 Claude 确实读取了技能内容而不是靠自己的训练数据在回答。第一步确认技能被加载。在 Claude Code 里输入/skills list正常输出会列出所有扫描到的技能名和它们的 description。如果某个技能没出现回到上一节检查目录和 SKILL.md 的 frontmatter 格式——frontmatter 必须以---开头和结尾中间不能有空行错位YAML 缩进用空格不用 Tab。第二步触发技能。用一句明确匹配 description 的话比如对 code-reviewer 技能帮我评审这段代码看看有没有潜在问题 def process(items): result [] for i in range(len(items)): if items[i] ! None: result.append(items[i] * 2) return result如果技能触发成功Claude 的回答会带上技能里定义的输出格式——比如按「阻塞 / 建议 / 提示」分级并且引用 style-guide.md 里的具体条款。如果它只是泛泛地说「这段代码可以用列表推导式优化」没有分级、没有引用文档那说明技能没触发Claude 在用默认能力回答。第三步验证知识库真的被读取。这是最关键的一步。在 code-reviewer 的references/style-guide.md里写一条不常见的规则比如## 命名规范 禁止使用单字母变量名循环索引除外i, j, k 允许。 禁止使用 data、info、temp 作为变量名必须用具体语义命名。然后触发技能看 Claude 有没有指出items这个参数名不够具体。如果它指出了说明 style-guide.md 被读进去了。如果没指出说明技能虽然触发了但引用文件没加载成功——检查 SKILL.md 里引用文件的路径是不是相对于技能文件夹的写绝对路径会失败。第四步验证 API 链路。如果你是通过 TaoToken 接入的可以在终端直接发一个请求确认链路通curl https://taotoken.net/api/v1/messages \ -H x-api-key: sk-your-taotoken-key \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 256, messages: [ {role: user, content: 回复 OK 两个字母即可} ] }正常返回是一段 JSONcontent数组里第一个元素的text字段是OK。如果返回 401是 Key 的问题如果返回 404是模型 ID 写错了如果连接超时检查 Base URL 有没有多写或少写路径段。第五步做一次「技能隔离」测试。同时装两个技能一个 code-reviewer 一个 paper-polish然后发一句只该触发其中一个的话确认另一个没被误触发。如果两个都触发了说明 description 的边界没划清楚回去改 description加上负向描述。走完这五步你对技能是否生效就有把握了。日常使用中我习惯在技能刚写完时跑一遍这套验证之后每次改 SKILL.md 或知识库文件也至少跑第三步和第五步防止改动引入回归。5. 常见报错排查401、local proxy failed 与 reading choices技能配置过程中会撞上几类固定报错这里逐个拆。401 Unauthorized。这个最直接Key 无效或没带上。先确认请求头里带的是x-api-key而不是Authorization: Bearer——Anthropic 的 API 用前者。再确认 Key 没有多余空格从 TaoToken 控制台复制时容易带上首尾空白。如果 Key 确认没问题还是 401检查是不是把 Key 写进了错误的配置文件——Claude Code 读settings.json的api.apiKeyCline 读 MCP 配置的env.ANTHROPIC_API_KEY写错地方等于没配。local proxy failed。这个报错通常出现在客户端启动阶段意思是客户端尝试连接配置的 Base URL 失败了。排查顺序先在终端用 curl 直接请求 Base URL确认网络层通如果 curl 通但客户端报错检查客户端配置里的 URL 有没有拼写错误比如把https://taotoken.net/api写成了https://taotoken.net/api/v1——路径多一段会 404少一段也可能失败。还有一种情况是客户端缓存了旧的配置改完配置要完全退出客户端再重启不是关窗口。reading choices 相关报错。这个报错一般出现在响应解析阶段提示读取choices字段失败。原因是请求发到了 OpenAI 格式的端点但返回的是 Anthropic 格式或者反过来。Anthropic 的响应结构是content数组OpenAI 是choices数组。如果你用的客户端默认按 OpenAI 格式解析就要在客户端设置里把 API 格式切成 Anthropic或者确认 Base URL 指向的是 Anthropic 兼容端点。TaoToken 的/api路径同时支持两种格式但客户端要选对解析模式。OAuth 相关报错。如果你在配置里同时开了 OAuth 登录和 API Key客户端可能优先走 OAuth 流程导致 Key 配置被忽略。解决办法是在设置里明确关闭 OAuth或者把认证方式强制设为 API Key。Claude Code 里对应的字段是authMethod: apiKey。技能触发了但回答没引用知识库。这不是报错但结果不对。原因通常是 SKILL.md 里引用文件的路径写错了或者文件编码不是 UTF-8。Claude 读取非 UTF-8 文件时可能静默失败。用file -I references/style-guide.md确认编码不是utf-8就转一下。技能列表为空。前面提过路径问题占大头。另外注意directories里配的路径Claude 扫描的是这个路径下的直接子文件夹每个子文件夹算一个技能。如果你把 SKILL.md 直接放在skills/根目录下不会被识别必须放在skills/技能名/SKILL.md。把这几类报错对照着排查大部分配置问题都能定位到具体字段。建议在改配置时一次只改一个地方改完立刻验证这样出问题时能快速锁定是哪个改动引入的。6. 把技能包接进日常编码流技能包配好之后真正产生价值的地方是把它接进日常流程。我自己的做法是分三层项目级技能、个人级技能、临时技能。项目级技能放在项目仓库的.claude/skills/下跟着代码走。比如一个后端项目会有api-reviewer技能挂载这个项目的接口规范文档和错误码表。团队里每个人拉下代码就自带这套技能评审标准统一。这类技能适合用版本管理改动走 PR。个人级技能放在~/.claude/skills/跨项目复用。比如commit-message技能挂载你自己的提交信息风格样本不管在哪个项目里写提交信息都触发它。这类技能不需要分享自己维护就行。临时技能用于一次性任务比如要处理一批特定格式的数据临时写个技能挂载数据字典任务结束就删掉。这类技能的生命周期短不用太讲究结构。如果你要把技能包接到 Claude Code 做长期编码Coding Plan 的额度模式比按量计费更适合高频调用——技能触发会额外读取知识库文件token 消耗比普通对话高包月模式能控制成本。接入方式还是那三件套Base URL 填https://taotoken.net/apiKey 用 TaoToken 生成的Model ID 按你实际用的 Claude 版本填全。技能包写多了之后维护成本会上升。我的经验是给每个技能在 SKILL.md 顶部加一行版本注释改了什么记一笔。知识库文件超过 50MB 就考虑拆分单个技能挂载太多文档会拖慢触发判断。定期清理不再用的技能别让技能目录变成垃圾场。最后一步验证随便挑一个你日常最高频的场景把它现有的提示词改写成 SKILL.md挂上对应的参考资料跑一遍第 4 节的五步验证。跑通了你就有了第一个真正可复用的技能包。后面再往上加就是复制这套结构的事。