LLM Skills 完整讲解：从 Agentic Coding 到智能体能力集落地

1. 为什么你的 Agent 总是“自由发挥”从一次单元测试翻车说起如果你正在用 Cline、Cursor、Claude Code 这类编程智能体写代码大概率遇到过这种场景你让它“给这个接口写单元测试”它确实写了但写出来的东西跟你的项目规范完全不搭——测试框架用的是 Jest而你项目里明明是 Vitest文件命名是test_user.ts而你团队约定是user.test.ts更别提它压根没跑测试直接甩给你一段代码就完事了。这不是模型不够聪明而是你没有给它一套标准化的任务模板。LLM Skills大模型智能体能力集要解决的就是这个问题把“写单元测试”这件事拆成明确的步骤、约束和输出格式让智能体每次执行都走同一条流水线而不是每次即兴发挥。简单说LLM Skills 是给智能体预先定义好的、可复用的任务执行模板。它告诉模型三件事能做什么、按什么步骤做、输出成什么样。在 Agentic Coding 场景里Skills 就是智能体的“作业指导书”没有它模型只能靠通用能力瞎猜有了它模型会优先按你定义的流程走。这篇文章面向正在做智能体项目、或者想把自己的开发流程沉淀成可复用能力的开发者。我会从 Skills 的构成讲起给出可复制的配置示例然后一步步验证接入效果最后把常见的报错和排查方法整理出来。你不需要是提示词专家只要能写 Markdown 和跑命令行就能跟着做。核心检索词先明确LLM Skills 是什么、能做什么、适合谁。它是一套用 Markdown 文件管理的任务模板能让编程智能体按预设流程完成细分开发任务适合所有在用 Cline、Cursor、Claude Code 做 Agentic Coding 的开发者。2. Skills 和 Tools 到底差在哪一份 Skill.md 的结构拆解很多人第一次接触 Skills 会把它和 Tools 搞混这两个概念确实容易混但分工完全不同。Tools 是底层操作函数比如读文件、执行终端命令、Git 提交、浏览器截图。它回答的是“用什么手段做”。Skills 是业务任务目标比如“重构 TypeScript 接口”“生成单元测试”“排查前端报错”。它回答的是“要做什么、按什么流程做”。一个 Skill 会组合调用多个 Tools 来完成任务Tool 是 Skill 的底层执行手段。用一句话概括Tool 是机器能执行的基础动作Skill 是封装好的完整业务流程。一份标准的 Skill.md 长这样--- name: Generate Unit Test description: 根据目标代码文件自动生成完整单元测试用例 --- # 执行规则 1. 读取目标源码文件解析函数入参、返回逻辑、边界条件 2. 检测项目测试框架jest/vitest安装对应依赖 3. 生成 .test.ts 配套文件覆盖正常/异常分支 4. 运行测试命令验证失败则自动修复用例 5. 输出修改 Diff 等待用户确认保存 # 约束条件 - 测试文件命名必须与源文件同名后缀为 .test.ts - 每个导出函数至少覆盖 3 个用例正常、边界、异常 - 不允许修改源文件逻辑只新增测试文件name是技能唯一名称智能体靠它识别调用description是一句话概括用途模型匹配任务时主要看这个详情规则里写完整执行步骤、输出规范、约束条件以及需要调用哪些 Tools。这里有个关键点Skills 不是写在系统提示词里的而是以独立文件形式存在按需加载。这样做的好处是模块化可插拔——新增业务只需要新建一份 Skill.md不用重写整个系统提示词。比如你想加一个“数据库迁移脚本生成”技能直接新增文件即可生效。在 Coding Agent 里的实际作用也很直接。没有 Skills 时LLM 只会自由发挥加载 Skills 后AI 会优先按预设标准化流程完成开发任务不会跑偏。你只需要说“给这个接口写单元测试”AI 自动匹配 Generate Unit Test 这个 Skill自动走完读代码、装依赖、生成用例、自测全流程不用你分步指挥。每个 Skill 还规定固定返回结构比如代码 Diff、执行日志、修改清单方便 IDE 展示变更、等待你审批。3. 可复制配置把 Skill.md 接入你的智能体项目这一节给出可以直接复制的配置片段。我以 Claude Code 和 Cline 两种常见环境为例路径和原文保持一致你照着放文件就行。先看 Claude Code 的 Skills 目录结构。Claude Code 默认从项目根目录的.claude/skills/读取技能文件每个技能一个子目录里面放SKILL.mdyour-project/ ├── .claude/ │ └── skills/ │ └── generate-unit-test/ │ └── SKILL.md ├── src/ └── package.jsonSKILL.md内容如下注意 frontmatter 里的name和description是模型匹配的关键--- name: generate-unit-test description: 根据目标源码文件自动生成单元测试检测测试框架并运行验证 --- # 生成单元测试 ## 执行步骤 1. 读取用户指定的源码文件解析所有导出函数的入参和返回类型 2. 检查 package.json 中的测试框架依赖优先使用 vitest其次 jest 3. 若依赖缺失执行安装命令npm install -D vitest vitest/coverage-v8 4. 生成与源文件同名的 .test.ts 文件放在同目录下 5. 运行 npx vitest run 测试文件路径 验证 6. 若测试失败读取报错信息修正测试用例后重新运行最多重试 3 次 7. 输出最终 Diff 和测试通过日志等待用户确认 ## 输出格式 - 新增文件列表 - 测试运行结果摘要通过数/失败数 - 完整代码 Diff如果你用的是 Cline配置方式略有不同。Cline 通过.clinerules文件或自定义指令加载技能推荐把 Skill 内容拆成独立文件在.clinerules里引用# .clinerules ## 技能加载 当用户请求生成单元测试时读取 .cline/skills/generate-unit-test.md 并严格按其中步骤执行。 当用户请求排查前端报错时读取 .cline/skills/debug-frontend.md 并严格按其中步骤执行。对应的.cline/skills/generate-unit-test.md内容与上面 Claude Code 版本基本一致只是不需要 frontmatter直接写规则即可。这里必须把三件套写全否则模型无法正确调用Base URL、API Key、Model ID。以接入 TaoToken 为例在 Claude Code 的配置里这样写{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的密钥, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }Cline 的配置在 VS Code 设置里对应字段是{ cline.apiProvider: anthropic, cline.apiKey: sk-你的密钥, cline.baseUrl: https://taotoken.net/api, cline.model: claude-sonnet-4-20250514 }API Key 在控制台的 API Keys 页面创建地址是 https://taotoken.net/api-keys 。创建后复制密钥填到上面的配置里。模型 ID 根据你实际使用的模型填写Claude 系列、GPT 系列都支持。配置完成后重启 Claude Code 或重新加载 Cline 窗口让配置生效。这一步别跳过很多人配完没重启然后说“没反应”其实是旧配置还在内存里。4. 验证请求跑一个真实任务看 Skills 是否生效配置放好了接下来验证它到底有没有生效。我建议用一个最小可复现的任务来测别一上来就丢个大项目。准备一个测试文件src/math.tsexport function add(a: number, b: number): number { return a b; } export function divide(a: number, b: number): number { if (b 0) { throw new Error(Division by zero); } return a / b; }然后在 Claude Code 里输入给 src/math.ts 生成单元测试如果 Skills 生效你会看到智能体按顺序执行先读取src/math.ts然后检查package.json里的测试框架发现没有 vitest 就执行安装接着生成src/math.test.ts运行测试最后输出 Diff 和测试结果。生成的测试文件应该长这样import { describe, it, expect } from vitest; import { add, divide } from ./math; describe(add, () { it(正常相加, () { expect(add(1, 2)).toBe(3); }); it(边界零值, () { expect(add(0, 0)).toBe(0); }); it(负数相加, () { expect(add(-1, -2)).toBe(-3); }); }); describe(divide, () { it(正常相除, () { expect(divide(10, 2)).toBe(5); }); it(异常除零抛错, () { expect(() divide(1, 0)).toThrow(Division by zero); }); });运行npx vitest run src/math.test.ts你应该看到类似输出✓ src/math.test.ts (5 tests) 12ms Test Files 1 passed (1) Tests 5 passed (5)如果测试全部通过说明 Skills 已经正确加载并执行。如果智能体没有按步骤走而是直接甩了一段测试代码给你那说明 Skill 没被匹配到检查description是否写得太模糊或者文件路径是否放对。这里有个实测经验description里最好包含用户可能说的原话关键词。比如用户常说“写单测”“补测试”“生成测试用例”那 description 里就都带上模型匹配命中率会高很多。验证通过后你可以继续加更多 Skill。比如加一个“排查前端报错”的技能description 写“根据控制台报错信息定位前端问题并给出修复方案”执行步骤里写清楚先读报错、再定位文件、再分析原因、最后给修复 Diff。这样你的智能体就从一个通用助手变成了有明确能力边界的开发搭档。5. 常见报错排查401、local proxy failed、reading choices 怎么解接入过程中最容易卡在几个固定报错上这一节按真实报错逐个拆。401 Unauthorized这个最常见基本是 API Key 没填对或者没生效。先检查配置文件里的ANTHROPIC_API_KEY或cline.apiKey是否完整复制有没有多余空格。然后确认密钥没有过期去控制台的 API Keys 页面看一眼状态。如果密钥没问题检查 Base URL 是否写成了https://taotoken.net/api注意结尾不要多加斜杠也不要写成带 UTM 参数的地址。改完配置记得重启工具。local proxy failed / connection refused这个报错通常出现在本地网络环境有额外代理设置的时候。先确认你的终端能直接访问https://taotoken.net/api用curl -I https://taotoken.net/api看返回状态码。如果 curl 能通但工具报错检查工具自身的代理配置把HTTP_PROXY、HTTPS_PROXY环境变量清掉再试。Claude Code 和 Cline 都会读取系统环境变量残留的代理设置会干扰请求。reading choices of undefined这个报错一般出现在用 OpenAI 兼容接口调 Claude 模型的时候。原因是请求发到了 OpenAI 格式的端点但返回结构不匹配。检查你的 Base URL 是否用了正确的 Anthropic 端点。如果用 Cline 的 OpenAI Compatible 模式Base URL 要写https://taotoken.net/api模型 ID 要写完整的 Claude 模型名不能简写。另外确认请求体里的model字段和实际调用的模型一致。OAuth 相关报错如果你用的是 Claude Code 的 OAuth 登录模式但配置里又写了 API Key两者会冲突。解决办法是二选一要么用 API Key 模式把ANTHROPIC_API_KEY填好要么用 OAuth 模式清掉 API Key 配置。混用会导致认证流程混乱报错信息往往不明确。Skill 不生效、模型不按步骤走这不是报错但比报错更让人头疼。排查顺序是先确认 Skill 文件路径正确Claude Code 是.claude/skills/技能名/SKILL.mdCline 是.cline/skills/技能名.md再确认 frontmatter 格式正确name和description之间不能有空行最后确认 description 里的关键词和用户指令能对上。如果还不行在对话里显式说“使用 generate-unit-test 技能”强制模型匹配。Token 开销过大Skills 整体约 20,000 tokens每次对话都会拼入上下文。如果你的 Skill 文件写得太长或者加载了太多技能上下文窗口会被快速占满。解决办法是按需加载把不常用的技能拆到独立文件只在需要时引用。复杂项目建议把 Skill 拆细每个技能只做一件事避免一个文件里塞太多规则。排查完这些基本能覆盖 90% 的接入问题。剩下的多半是模型本身的能力边界问题换个模型或者把 Skill 步骤写得更细就能解决。6. 把能力沉淀成文件长期编码项目的接入建议如果你打算长期用 Agentic Coding 做项目我建议把 Skills 当成项目资产来管理而不是临时写几段提示词。具体做法是在项目根目录建一个skills/目录每个技能一个 Markdown 文件用 Git 跟踪版本。团队里谁改了技能规则走正常的代码评审流程。这样技能会随着项目演进不断优化而不是每次换个人就重新写一遍。对于长期编码和 Agent 场景Coding Plan 提供了更稳定的调用额度适合把 Skills 接入到日常开发流程里。你可以先通过模型对话快速验证 Skill 的匹配效果确认没问题后再落到项目配置里。接入文档里有各工具的详细配置说明包括 Claude Code、Cline、Codex 的完整参数。遇到配置问题时对照文档检查比盲目试错快得多。最后给一个实用技巧Skill 的description不要写得太技术化用用户实际会说的话来写。比如“帮我写单测”比“生成单元测试用例”更容易被匹配到。模型匹配的是语义相似度不是关键词精确匹配所以 description 里多放几种常见说法命中率会明显提升。