1. Agent 自写 skill 的真实边界从玩具到可验证骨架Agent 自写 skill 这件事最近被讨论得很多。简单说skill 就是一份标准化的能力文件夹里面有一份 SKILL.md 描述「这个技能是什么、怎么用、什么时候触发」还可以附带可执行脚本让 Agent 不只是「知道怎么做」而是能真正动手。它和 MCP 那种「你能调用什么工具」不是一回事skill 补的是「一件具体的事你该怎么把事做对」这层 know how。适合谁适合已经在用 Claude Code、Cursor、Codex CLI 这类编码 Agent想让 Agent 自己沉淀工作流、又担心它写出一堆跑不通的垃圾 skill 的开发者。我试过让 Agent 连续生成十几个 skill结论很直接原子级、单步、边界清晰的 skillAgent 写得又快又好一旦涉及多步嵌套、外部 API、异常分支自动生成的 skill 大概率是玩具。这不是模型不够聪明而是 skill 的验证成本被严重低估了。Anthropic 自带的 skill-creator 上线第一周有开发者观察了 100 多个用户的使用情况结论是大多数实现更像玩具而不是工具——该触发时不触发、指令塞太多把 Agent 绕晕、文件格式出错反复出现。所以这篇不聊「Agent 能不能自己写 skill」这种是非题而是给你一套可验证的配置骨架用 TaoToken 统一 Key 接入把 settings.json / config.toml 骨架搭好再附上判断「这个自动生成的 skill 到底能不能用」的具体检查动作。核心目标是让你能明确划线——什么时候放手让 Agent 自己写什么时候必须人工兜底。2. 前置用 TaoToken 统一 Key 接入别让配置成为变量在验证 skill 之前先把模型接入这层固定住。原因很简单如果你一边调 skill 逻辑一边还在换模型、换 Key、换 base_url那 skill 失败时你根本分不清是 skill 写得烂还是接入层在抖。TaoToken 在这里的价值就是一个 Key 打通多家模型把接入层收敛成常量让 skill 的验证结果可复现。TaoToken 的官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 这个不加 UTM。它的定位是统一的大模型 API 接入层兼容 OpenAI 风格的接口协议所以你在 Claude Code、Codex CLI、Cursor 或者自己写的 Agent 脚本里基本只需要改 base_url 和 api_key 两个字段。对 skill 验证来说这一点很关键。因为 skill 的触发和执行依赖模型的理解能力不同模型对同一份 SKILL.md 的解析差异很大。用统一 Key 接入后你可以固定 skill 文件不变只切换模型快速判断「是 skill 描述有问题还是这个模型能力不够」。这比每次重配环境高效得多。你需要先拿到 Key。进入控制台创建 API Key路径是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite Key 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。创建后复制保存后面所有配置都用它。注意Key 只显示一次建议创建后立刻存进本地环境变量或密钥管理工具不要硬编码进会提交到 Git 的文件里。3. 可复制配置settings.json 与 config.toml 骨架下面给两套骨架。settings.json 面向 Claude Code / 类 Claude 的 Agent 配置config.toml 面向 Codex CLI 这类用 TOML 的工具。两套都指向 TaoToken 的统一入口你按自己用的工具选一套即可。3.1 settings.json 骨架{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoToken密钥, ANTHROPIC_MODEL: claude-sonnet-4-20250514, ANTHROPIC_SMALL_FAST_MODEL: claude-haiku-4-20250514 }, permissions: { allow: [ Read, Write, Bash(npm run test:*), Bash(python -m pytest:*) ], deny: [ Bash(rm -rf:*), Bash(curl:* | sh) ] }, skills: { directory: ./.agent/skills, autoLoad: true, validateOnLoad: true } }这里有几个点值得展开。ANTHROPIC_BASE_URL指向 TaoToken 的 API 基址ANTHROPIC_AUTH_TOKEN填你的 Key。skills.directory指定 skill 文件夹的根目录validateOnLoad打开后Agent 加载 skill 时会先做一次结构校验格式不对的直接拒绝加载——这一步能挡掉相当一部分自动生成的残次品。permissions里的deny是给自动生成 skill 兜底的关键。Agent 自己写的 skill 可能包含你没预期的命令先把危险操作拉黑比事后审计省事。3.2 config.toml 骨架[model] provider openai-compatible base_url https://taotoken.net/api api_key sk-你的TaoToken密钥 model gpt-5.2 small_model gpt-5.2-mini [skills] root ./.agent/skills auto_discover true strict_schema true [skills.validation] require_frontmatter true require_trigger true max_instruction_tokens 2000 allow_scripts true [sandbox] enabled true timeout_seconds 30 network falsestrict_schema true和require_frontmatter true是这套骨架的核心。它强制每个 skill 必须有规范的元数据头否则不加载。max_instruction_tokens限制单个 skill 的指令长度——前面提到「指令塞太多导致 Agent 晕掉」这个参数就是硬性防线。sandbox.network false默认断网防止自动生成的 skill 偷偷发起外部请求。3.3 SKILL.md 的最小可用模板Agent 自写 skill 时最容易出问题的就是 SKILL.md 结构。给它一个模板比让它自由发挥靠谱得多。--- name: extract-table-from-html description: 从 HTML 页面中提取表格并转为结构化数据 trigger: 当任务涉及解析网页表格提取 HTML 表格数据时触发 version: 0.1.0 --- ## 用途 把一段 HTML 中的 table 元素解析为 JSON 数组。 ## 输入 - html: string原始 HTML 片段 ## 输出 - rows: array每项为一行记录 ## 步骤 1. 定位所有 table 标签 2. 解析 thead 作为字段名 3. 逐行解析 tbody 生成记录 4. 处理空值和合并单元格 ## 边界 - 不处理嵌套表格 - 不处理 JS 动态渲染的表格trigger字段是重中之重。skill 该触发时不触发绝大多数是因为 trigger 描述太模糊。让 Agent 写 skill 时强制它把 trigger 写成「当任务涉及 X 时触发」的具体句式命中率会明显提升。4. 验证请求判断 Agent 生成的 skill 到底能不能用配置搭好只是开始真正决定边界的是验证。下面这套检查动作是我实测下来最能区分「能用」和「玩具」的流程。4.1 结构校验先过机器这一关第一步不调模型纯静态检查。写一个脚本扫描 skill 目录import os, re, sys SKILL_ROOT ./.agent/skills REQUIRED [name, description, trigger] def check_skill(path): errors [] with open(path, encodingutf-8) as f: content f.read() if not content.startswith(---): errors.append(缺少 frontmatter) return errors fm content.split(---)[1] for field in REQUIRED: if not re.search(rf^{field}\s*:, fm, re.M): errors.append(f缺少字段: {field}) if len(content) 8000: errors.append(指令过长可能拖垮上下文) return errors failed 0 for root, _, files in os.walk(SKILL_ROOT): for fn in files: if fn SKILL.md: p os.path.join(root, fn) errs check_skill(p) if errs: failed 1 print(f[FAIL] {p}: {errs}) print(f总计失败: {failed}) sys.exit(1 if failed else 0)这一步能挡掉大约三成的自动生成 skill——缺 frontmatter、缺 trigger、指令超长都是高频问题。4.2 触发验证该触发时到底触没触发结构过了接着验证触发。准备一组正例和反例 prompt看 Agent 是否在正确的时机加载 skill。import requests API https://taotoken.net/api/v1/chat/completions KEY sk-你的TaoToken密钥 cases [ (帮我从这个 HTML 里提取表格数据, True), (今天天气怎么样, False), (解析这段网页里的 table, True), (写一首诗, False), ] for prompt, should_trigger in cases: resp requests.post(API, headers{ Authorization: fBearer {KEY}, Content-Type: application/json }, json{ model: claude-sonnet-4-20250514, messages: [{role: user, content: prompt}], metadata: {skills_root: ./.agent/skills} }) triggered extract-table in resp.text status OK if triggered should_trigger else MISMATCH print(f[{status}] {prompt} - triggered{triggered})正例不触发说明 trigger 描述太窄反例乱触发说明 trigger 太宽。两种情况都要回去改 SKILL.md而不是改模型。4.3 执行验证跑通一次真实任务触发对了最后看执行。给 skill 一个真实输入检查输出是否符合预期同时记录 token 消耗和执行时间。python -m pytest tests/test_skill_extract_table.py -v测试用例里至少覆盖三种情况正常输入、空输入、格式异常的输入。自动生成的 skill 最常见的翻车点就是只处理了正常路径空值和异常格式直接崩。如果这三种都过这个 skill 才算初步可用。4.4 嵌套验证组合才是真正的分水岭单个 skill 跑通不代表能用。前面提到单个 skill 执行成功率 95%三层嵌套后只剩 85.7%五层剩 77.4%。所以对涉及组合的 skill必须单独验证嵌套。构造一个需要两层调用的任务比如「提取表格 → 格式化输出」看整条链路是否稳定。如果嵌套失败逐层拆开单独测定位是哪一层的边界条件没处理。排查成本经常超过直接打平重做所以嵌套层数建议控制在两层以内超过就考虑拆成独立 skill 由主 Agent 编排。5. 本篇常见错排查5.1 skill 加载了但完全不触发先查 frontmatter 的 trigger 字段。最常见的是 trigger 写成了功能描述而不是触发条件比如写成「用于提取表格」而不是「当任务涉及提取表格时触发」。前者模型不知道什么时候该用后者才有明确的触发语义。5.2 触发后 Agent 行为混乱、答非所问大概率是指令太长。单个 SKILL.md 超过 2000 token模型注意力会被稀释。把步骤压缩到 5 步以内细节挪到附带的脚本里SKILL.md 只留「做什么、什么时候做、边界在哪」。5.3 报 401 或 base_url 相关错误检查ANTHROPIC_BASE_URL或base_url是否写成了https://taotoken.net/api注意不要多加/v1后缀导致路径重复。Key 是否复制完整、有没有多余空格。这类问题在接入文档里有对照说明https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。5.4 skill 执行时报权限错误自动生成的 skill 可能调用了 settings.json 里deny列表中的命令。先看报错的具体命令判断是否真的需要放行。如果确实需要把精确的命令模式加进allow不要图省事直接删掉deny。5.5 嵌套 skill 偶发失败、难以复现这是隐藏缺陷的典型表现。底层 skill 创建时测试通过是因为当时的输入没触发特殊情况被高层调用碰到新输入才暴露。解法是给底层 skill 补边界测试用例尤其是空值、超长输入、格式异常这三类。5.6 换模型后 skill 行为突变skill 质量和模型编码能力高度相关。弱模型造的 skill 给自己用会出问题给别人用更糟。如果换模型后 skill 失效先确认这个 skill 是不是由当前模型生成的。跨模型使用 skill 时建议重新跑一遍 4.2 和 4.3 的验证。6. 什么时候放手什么时候兜底把边界说清楚。可以让 Agent 自己写的情况单步操作、输入输出明确、无外部依赖、有现成测试用例可验证。比如格式转换、字段提取、固定流程的文本处理。这类 skill 自动生成后跑一遍 4.1 到 4.3通过就能用。必须人工兜底的情况涉及多步嵌套、外部 API 调用、异常分支处理、安全敏感操作。这类 skill 自动生成后即使单测通过也要人工审查边界条件和权限范围。嵌套层数越多人工介入的必要性越高。如果你打算长期让 Agent 积累 skill、跑编码或 Agent 类任务可以考虑用 Coding Plan 把额度固定下来路径是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。想先直观感受不同模型对同一份 SKILL.md 的解析差异可以直接在模型对话里试https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 。接入和 Key 相关的细节都在 API Keys 和接入文档里按前面的路径走一遍就能把骨架跑起来。最后留一个我踩过的坑别指望 Agent 一次写出完美 skill。把它当成一个需要你写测试、定边界、做审查的初级工程师产出质量会稳定得多。真正好用的 skill从来都是人机协作打磨出来的不是自动生成的。