Agent Skill 完全指南：从 SKILL.md 创建到渐进式加载全流程

1. 为什么你的 Agent 总是“重新学一遍”如果你用 Claude Code、Cline 这类编码 Agent 有一段时间大概率遇到过这种场景你花半小时调好一套代码审查规则换一个会话窗口Agent 又变回那个只会说“这段代码看起来不错”的老好人。团队里三个人用同一套 Agent输出的审查风格能差出三个版本——有人拿到的是资深架构师口吻有人拿到的是刚毕业实习生的语气。问题的根子不在模型在于能力没有沉淀。你每次输入的 Prompt 是临时的、一次性的会话结束就蒸发。Agent Skill 要解决的就是这件事把“怎么干这个活”写成文件让 Agent 在需要时自己去翻。Agent Skill 是 Anthropic 在 2025 年 10 月随 Claude Skills 推出的能力封装机制同年 12 月作为开放标准发布目前 Claude Code、Cursor、Codex CLI、VS Code GitHub 等工具都已跟进。它的本质是一个带 SKILL.md 的文件夹里面装着指令、脚本和参考资料。Agent 启动时只读每个 Skill 的元数据约 100 tokens判断当前任务匹配哪个 Skill 后才加载完整指令和资源。这套机制叫渐进式加载也是 Skill 相比传统 Prompt 最值钱的地方。这篇文章不讲概念史直接给你能跑的东西一份可复制的 SKILL.md 骨架、settings.json 配置片段、用 Cline 触发一次 Skill 加载并验证日志的完整动作。适合已经用过 Claude Code 或 Cline、想让 Agent 能力可复用的人。2. 前置准备TaoToken 接入与 Skill 目录约定在写 SKILL.md 之前先把模型接入这条链路打通。我用 TaoToken 做统一入口原因是它同时提供 Claude 和 GPT 系列模型的 API切换模型不用改代码调试 Skill 时比较省事。2.1 获取 API Key登录 TaoToken 控制台在 API Keys 页面创建一个新 Key。建议按用途命名比如cline-skill-debug方便后面排查是哪个 Key 在消耗额度。创建后立刻复制页面刷新后不再显示完整 Key。拿到 Key 后先确认模型列表和计费口径避免调试时把额度跑超。模型对话页面可以直接测试 Key 是否可用不用写代码。2.2 配置 Cline 使用 TaoTokenCline 是 VS Code 里的 Agent 插件支持自定义 OpenAI 兼容端点。在 Cline 设置里选 “OpenAI Compatible”填入配置项值Base URLhttps://taotoken.net/apiAPI Key你刚创建的 KeyModel ID按需填如claude-sonnet-4-5或gpt-4o保存后 Cline 会做一次连通性检查能列出模型就说明接入成功。这一步不做后面 Skill 触发了也没有模型响应日志里只会看到空返回。2.3 Skill 目录放哪Claude Code 和 Cline 都遵循同一套约定两个位置二选一项目级推荐project_root/.claude/skills/skill-name/SKILL.md全局级~/.claude/skills/skill-name/SKILL.md项目级的好处是能跟代码仓库一起提交团队 clone 下来就能用。全局级适合个人跨项目复用的通用技能。注意skill-name必须和 SKILL.md 里name字段完全一致大小写、连字符都不能差这是后面排障时最高频的坑。3. 可复制配置SKILL.md 骨架与 settings.json3.1 SKILL.md 的两段式结构SKILL.md 由 YAML frontmatter 和 Markdown 正文组成。frontmatter 是元数据层正文是指令层。先建目录mkdir -p .claude/skills/code-reviewer/scripts cd .claude/skills/code-reviewer touch SKILL.md然后写入下面这份骨架可以直接复制改--- name: code-reviewer description: 对代码片段进行安全、性能和风格审查。当用户请求代码审查、Review、检查漏洞时使用此技能。 license: Apache-2.0 compatibility: 无需额外依赖 --- # 代码审查技能 ## 适用场景 - 用户粘贴代码并说“帮我 Review 一下” - 用户询问某段代码是否存在安全风险 - 用户要求按团队规范检查命名和结构 ## 审查维度 ### 1. 安全漏洞 检查 SQL 注入、XSS、命令注入、不安全的反序列化。 发现直接拼接用户输入到查询语句的一律标 Critical。 ### 2. 性能问题 - 循环内重复创建对象或发起 IO - 未使用索引的数据库查询 - 不必要的深拷贝 ### 3. 代码风格 - 命名是否符合项目约定 - 函数是否超过 50 行 - 是否有必要的注释 ## 输出格式 每个问题按以下结构输出 - 严重级别Critical / High / Medium / Low - 位置文件名:行号 - 问题描述一句话说清 - 修复建议给出可替换的代码 ## 示例 输入 python def get_user(id): return db.execute(fSELECT * FROM users WHERE id{id})输出严重级别Critical位置get_user 函数问题描述SQL 注入用户输入直接拼接进查询修复建议改用参数化查询db.execute(SELECT * FROM users WHERE id?, (id,))frontmatter 里 name 和 description 是必填。description 是 Agent 判断是否调用这个 Skill 的**唯一依据**必须同时写清“技能用途”和“触发场景”。只写“代码审查工具”不够要写到“当用户请求代码审查、Review、检查漏洞时使用”。 ### 3.2 settings.json 配置片段 Claude Code 通过 settings.json 控制 Skill 的加载行为。在项目根目录建 .claude/settings.json json { skills: { enabled: true, paths: [ .claude/skills ], autoLoad: true, maxSkillTokens: 5000 }, permissions: { allow: [ Read(.claude/skills/**), Bash(python .claude/skills/**) ] } }autoLoad: true让 Agent 启动时扫描元数据maxSkillTokens限制单个 Skill 指令层的 token 上限超过会截断建议压在 5000 以内。permissions.allow里的两条是给 Skill 里的脚本开权限不加的话脚本调用会被拦。Cline 没有独立的 settings.jsonSkill 路径和权限在插件设置面板里配逻辑一样开启自动加载、允许读取 skills 目录、允许执行 scripts 下的脚本。3.3 加一个脚本让 Skill 真干活光有指令的 Skill 只能“说”加上 scripts 才能“做”。在scripts/下放一个检查函数长度的脚本# .claude/skills/code-reviewer/scripts/check_length.py import sys def check(file_path, limit50): with open(file_path, r, encodingutf-8) as f: lines f.readlines() funcs [] current None for i, line in enumerate(lines, 1): if line.strip().startswith(def ): if current: funcs.append(current) current {name: line.strip(), start: i, end: i} elif current: current[end] i if current: funcs.append(current) for fn in funcs: length fn[end] - fn[start] if length limit: print(f[WARN] {fn[name]} 长度 {length} 行超过 {limit} 行限制) if __name__ __main__: check(sys.argv[1])然后在 SKILL.md 的审查维度里加一句“调用scripts/check_length.py检查函数长度”Agent 执行时就会去读这个脚本。4. 验证请求用 Cline 触发一次 Skill 加载配置写完必须验证 Skill 真的被加载了而不是 Agent 在瞎编。4.1 触发动作在 Cline 对话框里输入帮我 Review 一下这段代码 def get_user(id): return db.execute(fSELECT * FROM users WHERE id{id})4.2 看日志确认加载Cline 的输出面板会打印 Agent 的决策过程。正常情况下你会看到类似这样的日志序列[Skill] Scanning metadata: code-reviewer [Skill] Match found: code-reviewer (score: 0.92) [Skill] Loading SKILL.md instructions [Skill] Executing scripts/check_length.py如果只看到Scanning metadata没有Match found说明 description 没写对触发词。如果看到Match found但没有Loading说明 SKILL.md 路径或 name 字段有问题。4.3 验证输出格式Skill 被正确加载时输出会严格按 SKILL.md 里定义的格式来- 严重级别Critical - 位置get_user 函数 - 问题描述SQL 注入用户输入直接拼接进查询 - 修复建议改用参数化查询 db.execute(SELECT * FROM users WHERE id?, (id,))如果输出是自由发挥的一段话说明指令层没生效Agent 只是在用默认行为回答。4.4 用 API 直接验证模型侧想确认是 Skill 的问题还是模型的问题可以绕过 Agent 直接打 APIcurl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-5, messages: [ {role: system, content: 你是代码审查助手按 Critical/High/Medium/Low 分级输出。}, {role: user, content: Review: def get_user(id): return db.execute(f\SELECT * FROM users WHERE id{id}\)} ] }返回里能看到模型是否按分级格式输出。这一步能排除模型本身不听话的可能把问题锁定在 Skill 配置上。5. 本篇常见错排查5.1 Skill 完全没被触发最高频的原因是name字段和文件夹名不一致。文件夹叫code-reviewerSKILL.md 里写name: code_reviewer下划线Agent 扫描时匹配不上。统一用连字符全小写。第二个原因是 description 太泛。写“代码相关工具”等于没写Agent 不知道什么时候该用。要写到具体触发词“当用户请求代码审查、Review、检查漏洞时使用”。5.2 触发了但指令没生效检查 SKILL.md 是否超过maxSkillTokens限制被截断。把长文档拆到references/目录SKILL.md 里只留索引和核心流程。比如把完整的团队编码规范放到references/style-guide.mdSKILL.md 里写“风格检查参考 references/style-guide.md”。5.3 脚本不执行三个检查点脚本是否在scripts/目录下SKILL.md 里是否明确写了调用路径settings.json 的permissions.allow是否放行了脚本执行。Cline 里对应的是插件设置里的命令执行权限默认可能是关的。5.4 Token 消耗比预期高用/cost或 Cline 的 token 统计看单次调用的消耗。如果 Skill 加载后 token 暴涨多半是 SKILL.md 正文太长。实测下来指令层控制在 2000 tokens 以内Agent 执行精度和成本最平衡。超过 5000 就开始出现指令漂移Agent 会挑着执行。5.5 跨平台失效Agent Skills 是开放标准但各平台对路径的识别有差异。Claude Code 和 Cline 认.claude/skills/部分工具只认自己的目录。跨平台复用时把 Skill 文件夹复制到目标平台的约定路径下不要指望软链接。6. 把 Skill 用起来从调试到长期运行单次调试通过只是起点。真正让 Skill 产生价值是把它放进版本控制、随项目走。.claude/skills/目录直接提交到 Git团队成员 clone 后 Agent 启动就能用不需要每个人重新配一遍。如果你打算长期跑编码类 Agent或者要搭多 Skill 协同的 Agent 工作流建议用 Coding Plan 这类按周期计费的方式比按 token 计费更适合高频调试场景。调试阶段用模型对话页面快速验证指令格式稳定后再接入 Cline 或 Claude Code 跑完整流程。Skill 的迭代节奏和代码一样改 SKILL.md、提交、观察 Agent 行为变化。每次调整 description 或指令结构后重新触发一次验证请求看日志里的匹配分数和加载路径有没有变化。这套动作跑顺了你的 Agent 才算真正有了“肌肉记忆”。