Claude Code 实践：用 Skill 让 Agent 行为稳定可靠，从 CLAUDE.md 到 MCP 的落地配置

1. 为什么你的 Claude Code Agent 总是“这次行、下次不行”如果你已经在用 Claude Code 写代码、跑脚本、做自动化大概率遇到过这种场景同一个任务今天让它改一个 Python 脚本的日志格式它老老实实按你的规范来明天换个会话再让它做类似的事它突然开始用另一种命名风格甚至自作主张重构了半个文件。你不得不把之前解释过的规则再讲一遍讲完它才“想起来”。这不是模型变笨了而是 Agent 的行为没有被约束住。Claude Code 里的 Agent 本质上是“大模型 工具调用 上下文”的组合它能读文件、写文件、执行 Bash、调外部服务能力很强但强能力如果没有稳定的行为边界就会变成不可预期。你每次开新会话它都是从零开始理解你的项目之前踩过的坑、定过的规范、约定好的流程全都不在它的记忆里。解决这个问题的核心机制就是 Skill。你可以把 Skill 理解成给 Agent 准备的一份“岗位操作手册”当任务触发到某个领域时Agent 自动加载对应的手册按照里面写好的流程、约束、工具调用来干活。它不会每次即兴发挥而是以同样的专家状态执行。配合 CLAUDE.md 定义始终生效的项目规范再用 MCP 把外部系统接进来三者组合起来才能让 Agent 的行为真正稳定可预期。这篇内容我会从实际配置出发给你可复制的 Skill 模板、CLAUDE.md 写法、MCP 接入方式以及一套验证 Agent 行为是否稳定的操作步骤。目标很明确让你下次开新会话时不用再重复解释同一件事。2. Skill、CLAUDE.md、MCP 三者到底怎么分工很多人搭 Claude Code 环境时最容易犯的错就是把所有东西都往一个地方塞。规则写进 CLAUDE.md流程也写进 CLAUDE.md外部工具调用还想塞进去最后 CLAUDE.md 变成几百行的大杂烩每次对话都加载上下文又重又乱。要理清分工先看三者的触发时机。CLAUDE.md 的特点是“只要在作用范围内每次对话都自动加载”。它可以放在用户根目录对所有项目生效也可以放在具体项目目录下只对该项目生效。所以它适合放始终生效的标准、约束、偏好比如“不要修改数据库 Schema”“代码风格用 Black 格式化”“提交信息用中文”。这些内容每次都需要放这里合理。Skill 的特点是“话题匹配时才按需加载”。它适合放特定任务的专项知识和操作流程比如“如何生成周报”“如何查询订单系统”“如何操作某个内部工具”。这些知识大多数对话用不到只有触发相关任务时才需要放 CLAUDE.md 会让每次对话都变重放 Skill 才合理。MCP 则是“工具调用时接入外部系统”。它解决的是 Agent 能不能访问数据库、API、第三方平台的问题。MCP Server 提供工具接口Agent 在需要时调用。它不负责行为约束只负责能力扩展。一个判断方法很实用如果某段知识放进 CLAUDE.md 会让所有对话上下文变重但大多数对话根本用不到那它就应该是 Skill。如果某个能力需要访问外部系统那就走 MCP。如果某条规则每次都必须遵守那才放 CLAUDE.md。我试过把三者混在一起结果就是每次对话加载一堆用不上的内容Agent 反而更容易忽略真正重要的约束。分开之后行为稳定性明显提升。3. 可复制的 Skill 配置模板与 CLAUDE.md 写法先看 Skill 的文件结构。一个规范的 Skill 应该是一个目录主文件是 SKILL.md脚本和模板独立存放skill-name/ ├── SKILL.md # 精简主文件说明、调用命令、Key Lessons ├── tool.py # 独立可执行工具 └── scripts/ ├── template_a.py # 模板脚本带占位符 └── template_b.shSKILL.md 的开头是 YAML frontmatter这是决定 Skill 何时触发、用什么模型、能用哪些工具的关键。下面是一个可直接复制的模板--- name: weekly-report description: Use this skill for ANY weekly report tasks, including collecting data, generating summaries, and formatting output. Always trigger when user mentions weekly report, 周报, or report generation. model: sonnet allowed-tools: Read, Write, Bash --- ## 操作说明 1. 读取 data/ 目录下的本周数据文件 2. 调用 scripts/generate_summary.py 生成摘要 3. 按 templates/report.md 格式输出到 output/ 目录 ## 脚本索引 | 文件名 | 用途 | |--------|------| | scripts/generate_summary.py | 生成数据摘要 | | scripts/format_report.py | 格式化输出 | ## 调用命令 bash python scripts/generate_summary.py --input data/ --output tmp/summary.json python scripts/format_report.py --input tmp/summary.json --output output/report.mdKey Lessons数据文件可能为空需要先检查行数日期格式统一用 YYYY-MM-DD输出前必须校验模板占位符是否全部替换Hard Rules不要修改 data/ 目录下的原始文件不要跳过格式校验步骤description 是最重要的属性它决定 Agent 在什么情况下自动调用这个 Skill。写法上要覆盖触发关键词说清楚能力边界用 “Always trigger when…” 明确条件。上面模板里的 description 覆盖了 weekly report、周报、report generation 三个触发点基本不会漏。 model 属性按复杂度选复杂分析用 opus常规操作用 sonnet高频简单任务用 haiku。allowed-tools 限制工具范围只读型 Skill 只给 Read 和 Bash文件操作型再加 Write 和 Edit避免 Agent 越界操作。 再看 CLAUDE.md。它放在项目根目录内容要精简只放每次都必须遵守的规则 markdown # 项目规范 ## 代码风格 - Python 使用 Black 格式化行宽 100 - 提交信息用中文格式类型: 描述 ## 硬性约束 - 不要修改 database/schema.sql - 不要直接操作生产环境配置 - 所有新增文件必须放在 src/ 或 tests/ 下 ## 常用命令 - 测试pytest tests/ -v - 格式化black src/ --line-length 100CLAUDE.md 不要写具体任务的流程那些放 Skill。它只负责“始终生效”的部分。MCP 的配置放在 Claude Code 的设置文件里通常是~/.claude/settings.json或项目级的.claude/settings.json。下面是一个接入外部服务的配置片段{ mcpServers: { order-system: { command: npx, args: [-y, your-org/order-mcp-server], env: { ORDER_API_BASE: https://taotoken.net/api, ORDER_API_KEY: your-api-key-here } } } }这里要注意MCP Server 的 Base URL 和 Key 要和你实际使用的服务一致。如果你通过 TaoToken 接入模型能力API 地址是https://taotoken.net/apiKey 在控制台生成。MCP 配置里的环境变量按你实际的服务填写不要照抄。三件套配齐后Agent 的行为边界就清晰了CLAUDE.md 管始终生效的规则Skill 管特定任务的流程MCP 管外部系统的访问。4. 验证 Agent 行为是否稳定的操作步骤配置写完不代表就稳了必须验证。验证的核心思路是用同一类任务多次触发看 Agent 是否每次都走同样的路径、遵守同样的约束。第一步先验证 Skill 能否被正确触发。开一个新会话输入一个应该触发 Skill 的任务描述比如“帮我生成本周周报”。观察 Agent 是否加载了 weekly-report 这个 Skill。如果没触发检查 description 里的关键词是否覆盖了你输入的说法。第二步验证 CLAUDE.md 的约束是否生效。输入一个会触碰硬性约束的任务比如“帮我改一下 database/schema.sql 里的字段”。正确的行为是 Agent 拒绝直接修改并提示这条约束。如果它直接改了说明 CLAUDE.md 没被加载或路径不对。第三步验证 MCP 工具是否可用。输入一个需要调用外部系统的任务比如“查一下订单系统里本周的订单数量”。Agent 应该调用 MCP Server 提供的工具而不是编造数据。如果报错检查 MCP 配置里的 command、args、env 是否正确。第四步做重复性验证。把同一个任务在不同会话里跑三次对比三次的执行路径和输出格式。稳定的表现是三次都加载了同一个 Skill都遵守了同样的约束输出格式一致。如果某次走了不同路径说明 Skill 的流程描述还不够明确需要补充判断逻辑。第五步记录失败案例。每次发现行为不稳定就把当时的输入、Agent 的输出、期望的输出记下来补充到 Skill 的 Key Lessons 或 Hard Rules 里。这是让 Skill 持续变稳的关键动作。验证过程中可以用一个简单的检查清单[ ] Skill 是否被正确触发 [ ] CLAUDE.md 约束是否生效 [ ] MCP 工具是否可调用 [ ] 同一任务三次执行路径是否一致 [ ] 输出格式是否稳定 [ ] 失败案例是否已记录到 Skill这套步骤跑下来你对 Agent 的行为边界就有底了。5. 常见报错排查401、local proxy failed、reading choices、OAuth配置过程中最容易卡在几个典型报错上这里逐个说清楚原因和排查方向。401 Unauthorized 通常出现在 MCP 调用或 API 请求时。原因一般是 Key 无效、过期或者环境变量没传进去。排查步骤先确认settings.json里 env 的 Key 字段拼写正确再确认 Key 本身在控制台是有效的。如果你用的是 TaoToken 的 APIKey 在控制台的 API Keys 页面生成生成后要复制完整不要漏字符。另外注意 Base URL 不要多加斜杠https://taotoken.net/api就是完整地址。local proxy failed 一般出现在网络层配置有问题时。这个报错说明请求没有到达目标服务。排查方向确认 MCP Server 的 command 和 args 能正常执行可以手动在终端跑一遍npx -y your-org/order-mcp-server看是否报错。如果手动能跑通但 Claude Code 里报错检查 settings.json 的 JSON 格式是否合法多余逗号或引号不匹配都会导致加载失败。reading choices 报错通常和模型返回格式有关。当 Agent 期望一个结构化的返回但模型输出不符合预期时会出现。排查方向检查 Skill 里是否对输出格式有明确要求如果没有补上格式约束。另外确认 model 属性指定的模型是否支持你要求的输出格式某些复杂格式在 haiku 上可能不稳定换成 sonnet 或 opus 试试。OAuth 相关报错出现在接入需要 OAuth 认证的外部服务时。排查方向确认 OAuth 的 client_id、client_secret、redirect_uri 是否和服务方要求一致。如果 MCP Server 需要 OAuth token确认 token 是否过期以及刷新机制是否配置。有些服务需要先在浏览器完成授权拿到 code 后再换 token这一步不能跳过。还有一个容易忽略的点如果你同时用了 CC Switch 或 Cline MCP 这类工具管理配置要确保 Base URL、Key、Model ID 三件套在每个工具里都写全。缺任何一个都会导致调用失败。Model ID 要写服务方文档里给出的完整名称不要自己简写。排查时养成看日志的习惯。Claude Code 的日志通常在~/.claude/logs/下MCP Server 的日志看它自己的输出。报错信息里通常有具体的错误码和原因比盲目试错高效得多。6. 让 Skill 进入持续优化的正循环Skill 不是写完就完事的。每一轮使用都会暴露新问题推动它进入下一轮优化。这个循环跑起来Agent 才会越来越稳。循环的起点是发现重复工作或行为不稳定。当你发现自己又在向 Agent 解释同一件事或者同一个任务两次结果不一致这就是信号。把这个场景记下来写成第一版 Skill。用一段时间后SKILL.md 会变胖。超过 500 行就是需要优化的信号。这时候让 AI 帮你诊断“看一下这个 SKILL.md有没有可以精简的地方脚本是不是应该剥离出去” AI 会识别出内嵌脚本、冗余说明、可以外移的内容。然后给它明确指令“把所有脚本都剥离到 scripts/ 目录SKILL.md 里只保留调用说明和引用。” 它会自动完成拆分和引用更新。重构完要测试。让 AI 设计测试用例先跑全自动测试建立基线再逐步引入需要人工确认的测试。测试过程中发现的 Bug能修的就修结构性限制就记录到 Known Limitations 里不要强行绕过。继续使用又会发现新的重复工作进入下一轮。这个循环的关键是每次发现问题都沉淀到 Skill 里而不是每次靠临场解释。沉淀得越多Agent 越不需要你盯着。如果你还没开始用 Skill建议从最小的场景入手找一个你每周都要重复做的任务把它写成 Skill跑一周看看效果。配置上CLAUDE.md 管规则Skill 管流程MCP 管外部系统三者分工清楚Agent 的行为就会稳定下来。需要生成 API Key 或查看接入文档可以从 API Keys 页面和控制台入手想先验证模型对话效果用模型对话页面快速试如果是长期编码或 Agent 场景Coding Plan 更适合持续使用。