1. 从一次 Code Review 翻车说起上周帮朋友看一个 Agent 项目他吐槽说明明在 SKILL.md 里写了审查代码时优先看安全风险结果 Agent 每次还是先挑命名和缩进。我让他把文件发过来扫了一眼就明白了——他把 SKILL.md 写成了项目 README前面三百字在讲项目背景安全规则埋在第四段Agent 加载完正文后注意力早被稀释了。这个场景其实很典型。Agent Skills 这套机制从 2025 年下半年开始被越来越多团队用起来但真正落地时卡住大家的往往不是概念不懂而是三个具体问题SKILL.md 到底怎么写才能被稳定触发Prompt、Function Calling、MCP、Skill 这四个词到底怎么分工Skill 多了之后路由怎么做才不乱这篇就围绕这三个问题展开。我会先给一份可以直接复制的 SKILL.md 骨架再给 MCP 的配置片段和验证动作最后把常见的报错和踩坑点列出来。适合两类人刚接触 Agent 想跑通第一个 Skill 的新手以及在企业里要把 Skills 做成基础设施的架构师。读完你应该能独立写出一个能被 Agent 稳定调用的 Skill并且知道它和 MCP 怎么配合。2. 先把 TaoToken 的接入准备好在写 SKILL.md 之前得先有一个能跑 Agent 的模型入口。我这边测试用的是 TaoToken 的 API它兼容 OpenAI 和 Anthropic 两种协议格式配置起来比较省事。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。第一步是拿 Key。登录后进控制台在 API Keys 页面创建一个新 Key建议按项目命名比如agent-skills-demo方便后面排查调用来源。创建完记得立刻复制页面刷新后就看不到了。拿到 Key 之后先别急着写 Skill用一条最简单的请求验证通道是否通。下面这段是 curl 版本把$TAOTOKEN_API_KEY换成你自己的 Keycurl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d { model: claude-sonnet-4-5, messages: [ {role: user, content: 回复 OK 两个字母即可} ], max_tokens: 16 }如果返回里能看到content: OK之类的字段说明 Key 和网络都没问题。这一步很重要因为后面 Skill 调试时如果 Agent 行为异常你得先排除模型根本没调通这个可能性。如果你用的是 Claude Code 这类客户端配置方式略有不同需要在环境变量里指定 base URL 和 Key。具体写法可以参考接入文档里面有各客户端的完整配置示例。想先直观感受一下模型对话效果的话也可以直接在模型对话页面里试几句确认模型选型和响应风格符合预期。3. SKILL.md 骨架从元数据到正文现在进入正题。一个 Skill 的最小形态就是一个目录加一个 SKILL.md 文件目录结构建议这样组织code-review-expert/ ├── SKILL.md # 主文件命中时加载 ├── scripts/ # 可执行脚本运行时调用 ├── references/ # 参考资料按需读取 └── assets/ # 模板与静态资源scripts/、references/、assets/不是必须的但功能稍复杂的 Skill 基本都会用到。SKILL.md 本身分两块YAML 前置元数据和正文。3.1 元数据name 和 description 决定生死元数据里最核心的是name和description。Agent 不会逐个读 SKILL.md 全文而是先扫 description 决定要不要加载。所以 description 写不好Skill 写得再漂亮也不会被触发。name的硬规则长度不超过 64 字符只允许小写字母、数字和连字符不能用anthropic、claude这类保留字。命名建议用动名词形式一眼能看出能力边界推荐命名不推荐命名原因processing-pdfshelper含义模糊reviewing-codedocuments过于宽泛test-driven-developmenttools等于没说analyzing-spreadsheetsanthropic-helper含保留字description要覆盖两件事这个 Skill 做什么什么场景下触发。对比一下好坏写法# 好的能力 场景 触发词 description: 从 PDF 文件中提取文本和表格、填充表单、合并文档。在处理 PDF 文件或用户提及 PDF、表单、文档提取时使用。 # 差的第一人称 触发条件不明 description: 我可以帮助您处理 PDF 文件 # 差的只写能力缺少场景 description: 处理 Excel 文件建议在 description 里嵌入用户可能说出的关键词比如PDF表单提取commit messagegit diff。无论规则匹配还是语义匹配都能提升命中率。3.2 正文操作手册不是科普文正文是 Agent 真正消费的部分。有个关键认知Skill 启动时只加载元数据正文要等模型判断相关后才读取。但正文一旦被加载每个 token 都要和系统提示、对话历史争夺注意力。写正文前拿三个问题自检每一段Agent 执行任务时真需要这段解释吗这是项目私有知识还是大模型本就掌握的常识这段文字值不值得占用上下文对比两种写法# 精准直接给方案和调用方式 ## 提取 PDF 文本 使用 pdfplumber 进行文本提取 import pdfplumber with pdfplumber.open(file.pdf) as pdf: text pdf.pages[0].extract_text() # 冗余科普风格信息密度低 ## 提取 PDF 文本 PDF 全称便携式文档格式广泛用于图文混排场景。 要从 PDF 中提取文字需借助专门的解析工具。 社区有多个可用方案包括 pypdf、pdfplumber、PyMuPDF 等。 综合易用性和覆盖面pdfplumber 是较稳妥的选择。第二种看着完整但对 Agent 来说全是噪音。它不需要你科普 PDF 概念也不需要横向对比库选型。Agent 真正关心的是默认用哪个、怎么调、输出怎么处理、异常怎么办。最有价值的内容其实是项目特有的踩坑记录# 这种信息 Agent 推断不出来必须明确写 users 表采用软删除方案。所有正式查询务必追加 WHERE deleted_at IS NULL。 # 这是通用常识写进去只会浪费上下文 所谓软删除就是用字段标记来代替物理删除记录仍保留在数据库中。主文件建议控制在 500 行以内超出的话把细节拆到单独文件用渐进式披露让 Agent 按需读取。3.3 自由度看风险等级决定写 Skill 时有个常被忽略的问题你打算给 Agent 多大自主裁量权答案取决于任务风险等级。自由度适用场景推荐写法高判断类任务答案不唯一给检查方向不锁定步骤中有固定模板允许微调给模板、参数和边界低操作敏感出错代价大给精确命令标注不可修改我的经验法则是凡是涉及改数据、发请求、部署、迁移、删文件的自由度必须收紧做分析、评审、归纳、生成草稿的可以适当放宽。低自由度示例——数据库迁移红线不能碰## 数据库迁移 执行以下命令 python scripts/migrate.py --verify --backup 不要修改命令不要添加额外参数。 如果命令执行失败立即停止将错误输出返回给用户。高自由度示例——代码审查给方向不锁步骤## 代码审查 重点检查 1. 是否有明显 Bug 或边界情况遗漏 2. 是否存在安全风险 3. 是否影响性能或资源使用 4. 是否违反项目已有约定 5. 是否有更简单的实现方式 输出时优先写会影响正确性和线上稳定性的问题不要只做格式建议。4. MCP 集成让 Skill 真正能动手Skill 管怎么做MCP 管怎么连。一个只做代码审查的 Skill 可以完全不依赖外部工具但如果你的 Skill 需要读文件、查数据库、调 GitHub就得靠 MCP 把外部能力接进来。4.1 MCP 配置片段以 Claude Code 为例MCP Server 的配置通常写在项目根目录的.mcp.json里。下面是一个文件系统 MCP 的配置示例{ mcpServers: { filesystem: { command: npx, args: [ -y, modelcontextprotocol/server-filesystem, /Users/yourname/projects ] }, github: { command: npx, args: [-y, modelcontextprotocol/server-github], env: { GITHUB_PERSONAL_ACCESS_TOKEN: your_token_here } } } }配置完重启客户端用/mcp命令可以查看已连接的 Server 列表。如果某个 Server 显示failed先看它的 stderr 输出通常是命令路径不对或者依赖没装。4.2 Skill 里怎么引用 MCP 工具Skill 正文里不需要写 MCP 的连接细节只需要描述什么时候用哪个工具。比如一个分析报表的 Skill## 分析流程 1. 先用 filesystem 的 read_file 读取报表文件 2. 检查字段定义确认数值列和维度列 3. 用 github 的 search_code 查找相关口径定义 4. 按先看字段定义、再看异常值、最后归纳业务结论的顺序输出Agent 在执行时会自己判断需要调哪个 MCP 工具Skill 只负责把流程和约束讲清楚。这里有个容易踩的坑别在 Skill 里写死工具名比如调用 read_file 工具因为不同客户端的工具命名可能不一样。更稳妥的写法是描述意图比如读取目标文件内容。4.3 延迟加载与渐进式披露上下文窗口是稀缺资源Skill 绝不能写成资料库。更合理的做法是渐进式披露先给轻量目录用到哪块再加载哪块。三层架构是这样的层级加载时机加载内容体量广告层启动时name description极短指令层命中后SKILL.md 正文建议 ≤500 行资源层执行时references/、scripts/按需正文里经常看到这种导航式写法## 高级功能 **表单填充**完整指南请参阅 FORMS.md **API 参考**所有方法请参阅 REFERENCE.mdAgent 只有在真正需要处理表单时才会去读 FORMS.md。以 BigQuery 数据分析 Skill 为例bigquery-analysis/ ├── SKILL.md # 概览和导航 └── reference/ ├── finance.md # 收入、ARR、账单指标 ├── sales.md # 机会、管道、账户 ├── product.md # API 使用、功能采用 └── marketing.md # 活动、归因、电子邮件用户问上个季度销售管道如何Agent 读完 SKILL.md 后只需打开 sales.md其余三份文件不进入上下文。注意避免链式引用SKILL.md → advanced.md → details.md → 关键规则藏在第三层Agent 很可能只读了第一层就停了。保持一级引用主文件直接指向目标文件。5. 验证请求确认 Skill 真的被触发写完 SKILL.md 和 MCP 配置后怎么确认 Agent 真的加载了这个 Skill我一般用三步验证法。第一步检查元数据是否被正确识别。在客户端里输入/skills或类似命令不同客户端命令不同看列表里有没有你的 Skill。如果没有多半是目录结构不对或者 YAML 格式有问题。第二步发一条应该触发 Skill 的请求观察 Agent 的行为。比如你的 Skill 是code-review-expert就发帮我审查一下当前 git 变更如果 Agent 开始按你定义的流程走先看架构、再看安全、最后看实现说明 Skill 被加载了。如果它还是泛泛而谈说明 description 没匹配上回去改触发词。第三步发一条不应该触发的请求确认没有误触发。比如发今天天气怎么样如果 Agent 还去调代码审查流程说明 description 写得太宽泛了。下面是一个完整的验证脚本用 Python 调 TaoToken API 模拟一次带 Skill 的请求import os import requests API_KEY os.environ[TAOTOKEN_API_KEY] BASE_URL https://taotoken.net/api # 模拟宿主注入 Skill 元数据后的请求 system_prompt 你可以使用以下 Skill - code-review-expert: Expert code review of current git changes with a senior engineer lens. Detects SOLID violations, security risks, and proposes actionable improvements. response requests.post( f{BASE_URL}/v1/chat/completions, headers{ Authorization: fBearer {API_KEY}, Content-Type: application/json }, json{ model: claude-sonnet-4-5, messages: [ {role: system, content: system_prompt}, {role: user, content: 帮我审查一下当前 git 变更} ], max_tokens: 1024 } ) print(response.json()[choices][0][message][content])如果返回内容里出现了SOLID安全风险这类你定义的关键词说明 Skill 的元数据被模型识别并采纳了。这一步跑通整个链路就通了。6. 常见报错与排查清单实际调试时下面这几类问题出现频率最高。Skill 不触发先检查 description 里有没有用户可能说的关键词。如果用户说看看这段代码有没有问题而你的 description 只写了code review语义匹配可能就飘了。补救办法是在元数据里加triggers字段相当于给冷启动阶段喂一批伪训练样本name: jvm-runtime-diagnosis description: Diagnose Spring Boot production runtime issues including OOM, Full GC, high CPU, slow APIs, and thread deadlocks. triggers: - 接口卡死了 - 频繁 Full GC - 帮我看看这段 Java 堆栈 - 服务 OOM 了怎么排查MCP Server 连接失败先看客户端日志里的 stderr 输出。常见原因有三个npx 命令路径不对、依赖没装、环境变量没传进去。如果是 GitHub MCP检查 token 有没有过期。Agent 跳过关键步骤这是 Skill 设计问题不是配置问题。解决办法是在流程里加必须停下来验证的节点。比如 TDD Skill 里的 Verify RED 阶段### Verify RED - Watch It Fail **MANDATORY. Never skip.** Confirm: - Test fails, not errors - Failure message is expected - Fails because feature missing, not typos末尾再加一份可判定的验证清单## Verification Checklist Before marking work complete: - [ ] Every new function/method has a test - [ ] Watched each test fail before implementing - [ ] Each test failed for expected reason - [ ] Wrote minimal code to pass each test - [ ] All tests pass每个检查项必须是具体动作保证质量遵循最佳实践这类空话 Agent 无法判定。上下文被稀释如果 Agent 加载 Skill 后表现反而变差多半是正文太长。把主文件压到 500 行以内细节拆到 references/。另外检查有没有链式引用SKILL.md → A.md → B.md 这种结构会让 Agent 只读第一层就停。术语不一致同一个概念在一个 Skill 里只用一个名称。前面写API 端点后面就别换成 URL、API 路由或路径。人能推断这些词指同一类东西Agent 不保证次次稳定。让 LLM 做确定性工作格式转换、精确计算、批量处理这些能交给脚本就交给脚本。脚本里错误条件要写清楚别让 Agent 靠猜def process_file(path): try: with open(path) as f: return f.read() except FileNotFoundError: print(f未找到文件 {path}正在创建默认文件) with open(path, w) as f: f.write() return 第三方 Skill 不审就用SKILL.md 本质上是指令可能夹带不安全操作。企业环境里至少要审一遍正文、脚本和参考文件。7. 下一步把 Skill 跑进真实项目到这里一个完整的 Skill 从编写到验证的链路就走通了。如果你还在调试阶段建议先去 API Keys 页面确认 Key 状态再对照接入文档检查客户端配置。想快速验证模型对 Skill 元数据的理解能力可以直接在模型对话里贴一段 description 试试触发效果。如果准备把 Skills 用到长期编码或 Agent 项目里Coding Plan 会更合适它针对长会话和工具调用做了优化比按次调用省心。配置入口在控制台的 Coding Plan 页面开通后把 base URL 换成https://taotoken.net/api即可。最后留一个我自己的经验Skill 不怕小怕边界模糊。先把一个具体问题解决稳定再考虑扩展。我见过太多团队一上来就写万能助手结果每个场景都跑不通。从code-review-expert或者test-driven-development这种边界清晰的 Skill 开始跑顺了再拆第二个比一次性铺开十个要快得多。