1. 为什么你的 Claude Code 总是“记不住”项目规范很多人第一次用 Claude Code 写业务代码都会遇到同一个尴尬明明上一轮对话里刚说过“我们项目用 pnpm不要用 npm”“接口统一走 src/api/request.ts 封装”下一轮它又给你npm install加裸fetch。这不是模型变笨了而是对话本身是短暂的——每次新会话都从零开始团队的业务逻辑、目录约定、代码风格散落在 Wiki、README、老员工脑子里AI 根本调不到。Claude Skills 就是冲着这个痛点来的。你可以把它理解成给 Claude 准备的“岗位技能包”一个包含SKILL.md、脚本和参考文档的文件夹里面封装了某个具体任务的工作流程和领域知识。当你的需求命中这个技能时Claude 才会把对应的详细指令加载进上下文不需要的时候就不占窗口。这个机制叫渐进式披露Progressive Disclosure也是 Skills 相比“把一大段提示词塞进 system prompt”最本质的区别。它适合谁三类人最该上手一是天天在 Claude Code 里写业务、想让 AI 稳定遵守团队规范的后端/前端二是想把重复操作比如 PDF 转 PPT、周报生成、竞品调研固化成可复用能力的效率玩家三是正在搭 Agent、需要把“工具调用”和“流程知识”分开管理的开发者。这篇就按最小可复现的路径从SKILL.md目录结构讲到 Claude Code 加载配置再用 MCP 工具把 Agent 串起来跑通一次验证。先明确一个容易混的点Skills 和 MCP 不是二选一。MCP 是协议层负责让模型“够得着”外部工具和数据像手和脚Skills 是知识层负责告诉模型“这件事该按什么流程做”像操作手册。一个调研类 Skill 可以规定先搜什么、再拉什么数据、最后按什么框架输出而真正去 Google Drive 搜文件、去 GitHub 拉仓库的动作交给 MCP 工具执行。两者配合Agent 才能既知道怎么做又真的做得到。2. TaoToken 前置准备给 Claude Code 配一个稳定的模型入口在写SKILL.md之前得先让 Claude Code 能正常跑起来。Claude Code 是 Anthropic 官方的命令行编码工具安装本身不复杂难的是模型接入这一环——官方直连价格不低很多人会找一个兼容 Anthropic 接口的入口来跑。这里我用 TaoToken 做演示它的接口兼容 Anthropic 的 Messages 格式Claude Code 这类工具可以直接对接。先装 Claude Code。官方推荐 native 安装方式比 npm 方式更稳、更新也更及时终端里执行curl -fsSL https://claude.ai/install.sh | bash装完之后随便进一个项目目录输入claude就能启动。但第一次启动它会要求你配置 API否则没法对话。这时候需要准备三样东西Base URL、API Key、Model ID。TaoToken 的 API 地址是https://taotoken.net/apiKey 需要你去控制台自己生成。生成 Key 的入口在控制台里打开 TaoToken 控制台 登录后创建 API Key复制出来保存好后面配置要用。如果你还没注册可以先从 官网 进。配置 Claude Code 有两种常见做法。一种是直接改环境变量在~/.zshrc或~/.bashrc里加export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你的Key export ANTHROPIC_MODELclaude-sonnet-4-5-20250929改完source ~/.zshrc生效。另一种是用 CC Switch 这类配置管理工具它能在多个 API 配置之间快速切换适合同时用官方和第三方入口的人。CC Switch 的配置本质也是写这几个字段只是帮你做了可视化管理和备份。这里有个细节要注意Claude Code 读取的是ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN不是 OpenAI 那套OPENAI_API_KEY。如果你之前配过别的工具环境变量别串了。Model ID 要填真实存在的模型名写错了会在请求时报模型不存在的错。配好之后在终端里跑一句最简单的验证claude -p 用一句话说明什么是 Claude Skills如果能看到正常返回说明模型入口通了。这一步是整个教程的地基地基不稳后面加载 Skill 会一直报错所以别跳过。Key 的额度、模型列表这些信息可以在 API Keys 页面 查看和管理。3. 可复制配置SKILL.md 目录结构与 Claude Code 加载现在进入正题。一个标准的 Skill 就是一个文件夹放在 Claude Code 能识别的位置。目录结构大致长这样my-skill/ ├── SKILL.md # 核心指令必须有 ├── scripts/ # 可执行脚本按需调用 │ └── convert.py └── references/ # 按需加载的详细文档 ├── schema.md └── api-spec.mdSKILL.md是入口Claude 先读它的 frontmatter 和正文判断这个技能是否匹配当前任务。scripts/放真正干活的脚本references/放那些“用到才加载”的长文档比如数据库表结构、API 规范。这种分层就是渐进式披露的落地先看摘要命中再展开细节。SKILL.md的 frontmatter 至少要写name和description。description是触发质量的关键它不是关键词匹配而是 Claude 对“这个技能能干什么、什么时候用”的语义理解。写得太窄该触发时不触发写得太泛不该触发时乱触发。一个可复制的模板--- name: pdf-to-ppt description: 将 PDF 文档转换为结构化的 PPT 演示文稿。当用户要求把 PDF、报告或文档转成幻灯片、PPT、演示文稿时使用。适用于技术分享、周报汇报、课程讲义等场景。 --- # PDF 转 PPT 技能 ## 触发条件 用户提到“PDF 转 PPT”“把这份报告做成幻灯片”“生成演示文稿”等意图时启用。 ## 执行步骤 1. 读取用户指定的 PDF 文件提取章节标题和要点。 2. 按每页 3-5 个要点的粒度拆分内容。 3. 调用 scripts/convert.py 生成 pptx 文件。 4. 输出文件路径并提示用户检查。 ## 约束 - 单页要点不超过 5 条避免文字堆砌。 - 保留原文的层级结构一级标题作为章节页。 - 代码片段单独成页保留等宽字体。把这个文件夹放到项目的.claude/skills/目录下Claude Code 启动时会扫描这个路径。如果你想全局可用放到用户级的~/.claude/skills/。放好之后重启 Claude Code让它重新扫描技能目录。除了手动放文件夹Claude Code 还支持插件市场方式安装。在 Claude Code 里运行/plugin marketplace add anthropics/skills这会把 Anthropic 官方的技能仓库注册为插件市场之后可以用/plugin install document-skillsanthropic-agent-skills安装官方文档类技能。通过插件装的技能会落在.claude/plugins/marketplaces/下和手动放的.claude/skills/是两套路径排查问题时别找错地方。还有一种最省事的方式直接用自然语言让 Claude Code 帮你装。比如你说“帮我安装这个 skill地址是 https://github.com/anthropics/skills/tree/main/skills/skill-creator克隆到我的 ~/.claude/skills 目录”它会自己执行 git clone 并放到正确位置。这种方式适合快速试玩但生产环境建议还是手动管理目录方便版本控制。配置层面还有一个容易忽略的点如果你用 CC Switch 管理多套 API切换配置后要确认 Claude Code 重启了否则它可能还挂着旧的 Base URL。CC Switch 里每套配置都要写全 Base URL、Key、Model ID 三件套缺一个都会导致请求失败。4. 验证请求用 MCP 工具串联 Agent 跑通最小实践Skill 装好了怎么确认它真的被加载、真的能干活最直接的办法是给一个明确命中description的请求观察 Claude 是否调用了技能里的步骤和脚本。但光有 Skill 还不够很多任务需要外部工具配合这就轮到 MCP 上场。MCPModel Context Protocol是一个标准协议让 Claude 能连接外部工具和数据源。你可以把 MCP Server 理解成给 Claude 装的手和脚文件系统 MCP 让它读写本地文件GitHub MCP 让它拉仓库数据库 MCP 让它查表。而 Skill 负责告诉它“拿到数据后按什么流程分析”。两者组合才是一个完整的 Agent 落地。先配一个最小 MCP Server。以文件系统为例在 Claude Code 的配置里加{ mcpServers: { filesystem: { command: npx, args: [ -y, modelcontextprotocol/server-filesystem, /Users/yourname/projects ] } } }这段配置通常写在项目根目录的.mcp.json或者 Claude Code 的用户级配置里。路径换成你自己的项目目录。配好后重启 Claude Code它会在启动时连接这个 MCP Server。现在做一个端到端验证。假设我们有一个“竞品调研”SkillSKILL.md里规定流程是先用文件系统 MCP 读取本地竞品资料再按 SWOT 框架输出分析。给 Claude 的请求用竞品调研 skill 分析 projects/competitor 目录下的资料输出 SWOT 分析正常情况下你会看到 Claude 先调用 filesystem MCP 的list_directory和read_file工具读取文件然后按照 Skill 里定义的 SWOT 框架组织输出。如果它没读文件就直接编说明 MCP 没连上如果它读了文件但没按 SWOT 结构输出说明 Skill 没被触发。这两个现象要分开排查。再验证一个带脚本的 Skill。前面那个pdf-to-ppt技能scripts/convert.py里可以放一个调用 python-pptx 的转换脚本。给 Claude 的请求帮我把 report.pdf 转成 PPT观察它是否执行了python scripts/convert.py report.pdf以及最终是否生成了.pptx文件。实测下来只要SKILL.md的description写得准Claude 命中技能的概率很高脚本调用也会按步骤走。如果你想把模型对话能力也接进来做对比测试可以打开 模型对话 页面用同一个 prompt 试试不带 Skill 时的输出差异对比一下就能直观感受到 Skill 带来的稳定性提升。对于需要长期跑编码任务或 Agent 的场景可以考虑 Coding Plan额度更划算。5. 本篇常见错排查401、local proxy failed 与技能不触发配置过程中最容易卡住的就那几个报错这里按真实遇到的顺序列一下。401 Unauthorized。这个基本是 Key 的问题。先确认ANTHROPIC_AUTH_TOKEN填的是 TaoToken 控制台生成的 Key不是官方 Key也不是 OpenAI 的 Key。然后确认 Base URL 是https://taotoken.net/api结尾没有多余的斜杠或路径。如果用了 CC Switch检查当前激活的配置是不是你改的那套。还有一种情况是 Key 复制时带了空格或换行肉眼看不出来重新复制一遍。local proxy failed / connection refused。这个通常出现在你本地挂了某个代理工具但代理没启动或者端口不对。Claude Code 会读取系统代理环境变量如果HTTP_PROXY指向一个不存在的端口就会报这个。解决办法是检查env | grep -i proxy把不该有的代理变量清掉或者确认代理工具正常运行。注意这里说的是本地网络配置问题不涉及任何跨境访问手段。reading choices of undefined。这个报错说明返回的数据结构不是预期的 OpenAI 格式。Claude Code 走的是 Anthropic Messages 格式返回体里是content数组不是choices。如果你在某个中间层做了格式转换或者 Base URL 指向了一个只支持 OpenAI 格式的入口就会出这个错。确认 Base URL 指向的是兼容 Anthropic 的接口。OAuth 相关报错。Claude Code 某些版本会尝试 OAuth 登录流程如果你用的是 API Key 模式可能会冲突。检查配置里是否同时存在 OAuth token 和 API Key保留一种即可。清理~/.claude下的缓存配置后重启通常能解决。Skill 不触发。这个最隐蔽。先确认SKILL.md的 frontmatter 格式正确name和description都在---之间。然后确认目录位置对项目级是.claude/skills/你的技能名/SKILL.md注意是技能名再套一层不是直接把SKILL.md扔在skills/下。最后看description的措辞如果用户请求里的意图和 description 差太远语义匹配不上就不会触发。把 description 改得更贴近真实说法比如加上“把 PDF 做成幻灯片”这种口语化表达。MCP Server 连不上。检查.mcp.json的 JSON 格式逗号、引号最容易错。command用npx时要确认本机 Node 版本够新。路径参数要用绝对路径相对路径在不同工作目录下会失效。改完配置一定要重启 Claude Code它不会热加载 MCP 配置。排查顺序建议从下往上先确认模型入口通401 类再确认 MCP 通连接类最后确认 Skill 触发语义类。三层都通了Agent 才能稳定跑。6. 把 Skill 变成可复用资产从单次提示到团队知识库跑通最小实践之后真正有价值的是把团队里那些“老员工才知道”的流程固化下来。比如你们的接口规范、数据库表结构、发布检查清单、代码 review 要点这些以前靠口口相传或者散落在文档里的东西都可以写成一个 Skill。写 Skill 有个实用技巧先让 Claude 帮你生成初稿。Anthropic 官方有个skill-creator技能专门用来写 Skill。安装方式/plugin install skill-creatoranthropic-agent-skills装好后直接说“创建一个 skill能自动把 PDF 转成 PPT”它会引导你补全SKILL.md的各个字段生成目录结构。你只需要在它生成的草稿上改description和约束条件。实测下来一个简单 Skill 从描述需求到生成可用文件几分钟就能搞定。对于更复杂的场景比如需要串联多个 MCP 工具的调研 Agent建议把 Skill 拆细一个 Skill 只负责一个明确任务description写清楚触发边界。多个 Skill 之间通过 Claude 的调度组合而不是塞进一个大而全的 Skill 里。这样维护起来清晰触发也更准。如果你在团队里推广可以把.claude/skills/目录纳入 Git 管理新人 clone 下来就能用同一套技能包。配合 接入文档 里的接口说明把 Base URL、Key、Model ID 三件套写进 onboarding 文档新人半小时就能把环境跑起来。最后说个我踩过的坑SKILL.md里的步骤别写太死。早期我把某个 Skill 的每一步都写成固定命令结果换个项目路径就失效。后来改成“先读取用户指定的文件再按以下规则处理”把具体路径和参数留给运行时决定复用性好了很多。Skill 是给模型看的操作手册不是写死的脚本留出判断空间反而更稳。