高质量测试 Skill 编写手册：用渐进式披露拆解 SKILL.md 结构

1. 为什么你的 SKILL.md 越写越臃肿Agent 反而越用越笨如果你正在给 Agent 写测试类 Skill大概率踩过这个坑一开始 SKILL.md 只有几十行写着写着变成几百行最后连自己都不敢改。每次 Agent 执行任务都要把整份文件塞进上下文结果模型开始走神——明明规则里写了要用基类它偏要自己造一个明明指定了参考文件它当没看见。这不是模型不行而是上下文被污染了。Transformer 的注意力机制在长上下文里会稀释关键信息你塞进去的每一条无关规则都在抢真正重要规则的权重。测试场景尤其明显权限测试、计费测试、模型广场测试的写法差异很大如果全写在一个文件里模型很容易把 A 模块的写法套到 B 模块上。这篇要解决的就是这个问题。我会给你一套可复制的 SKILL.md 目录骨架用渐进式披露把知识分成三层再配上自动化测试脚本验证技能加载顺序和命中率。适合正在做 Agent 测试工程、被 Skill 文件维护成本折磨的同学。整套思路我在接口自动化测试项目里跑过下面直接上结构。2. 渐进式披露把知识拆成三层让 Agent 按需加载渐进式披露的核心就一句话不要把全部规则一次性交给模型只在必要的时候加载对应的知识。落到文件结构上就是三层分离。第一层是 SKILL.md 本身只放工作流和跨模块的公共知识。它像一个调度中心告诉 Agent 先做什么、再做什么、什么时候去读哪个文件。第二层是references/目录每个功能域一个文件。权限测试读auth.md计费测试读billing.md互不干扰。这些文件里放的是该领域专用的基类、Service、API 调用模式。第三层是具体用例目录下的.rules文件和已有测试用例。Agent 在写新用例前先读同目录的规则文件和 1-2 个最相近的已有用例学习命名风格、导入方式、步骤写法。这样做的收益很直接单次加载的 token 量下降模型注意力集中在当前任务相关的知识上一次通过率明显提升。维护也简单——改权限逻辑只动auth.md不会波及计费模块。3. 前置准备TaoToken 接入与模型选择在写 SKILL.md 之前先把执行环境搭好。Agent 跑测试 Skill 需要一个稳定的模型入口我用的是 TaoToken 的 API 网关它兼容 OpenAI 和 Anthropic 的接口格式切换模型不用改代码。先去控制台创建 API Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentskill_progressive_disclosure创建完在 API Keys 页面复制密钥注意别提交到 Git 仓库https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentskill_progressive_disclosure模型选择上测试 Skill 涉及代码生成和规则遵循建议用长上下文能力强的模型。如果你要长期跑编码类 Agent 任务Coding Plan 比按量计费更划算https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentskill_progressive_disclosure接入文档在这里包含各语言的 SDK 示例https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentskill_progressive_disclosureAPI 基础地址统一用https://taotoken.net/api不带任何参数。下面配置环境变量export TAOTOKEN_API_KEYsk-你的密钥 export TAOTOKEN_BASE_URLhttps://taotoken.net/apiPython 里验证一下连通性import os from openai import OpenAI client OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL], ) resp client.chat.completions.create( modelclaude-sonnet-4-5, messages[{role: user, content: 回复 OK 两个字母}], ) print(resp.choices[0].message.content)返回OK就说明链路通了。这一步别跳过后面自动化测试脚本依赖这个环境。4. 可复制的 SKILL.md 目录骨架与分层配置先看完整目录结构这是整套方案的地基skills/ └── api-test-writer/ ├── SKILL.md ├── references/ │ ├── auth.md │ ├── billing.md │ ├── prompt-tpl.md │ ├── model-market.md │ └── multi-agent.md └── cases/ ├── platform_management/ │ ├── auth/ │ │ ├── .rules │ │ └── test_workspace_permission.py │ └── price/ │ ├── .rules │ └── test_billing_flow.py └── prompt_templates/ ├── .rules └── test_prompt_crud.pySKILL.md 的开头部分定义工作流强制 Agent 按顺序执行# 自动化测试用例编写 - 公共知识库 ## 工作流必须严格按顺序执行 ### Step 1阅读规则 1. 阅读本文件获取公共模块知识 2. 根据用例所属功能域读取 references/ 下对应的参考文件 3. 读取用例目标目录下的 .rules 文件 ### Step 2参考已有用例 1. 在目标目录下找 1-2 个功能最相近的已有用例 2. 阅读其基类、导入、命名、步骤风格 3. 新用例风格必须与同目录已有用例保持一致 ### 分层参考文件索引 | 功能域 | 参考文件 | 对应用例路径 | |--------|---------|------------| | 权限测试 | references/auth.md | cases/platform_management/auth/ | | 计费测试 | references/billing.md | cases/platform_management/price/ | | 提示词模板 | references/prompt-tpl.md | cases/prompt_templates/ | | 模型广场 | references/model-market.md | cases/model_marketplace/ | | 多Agent模型 | references/multi-agent.md | cases/app_dev/multi_agent_model/ |references/auth.md里放权限模块的专用知识比如三种授权方式的 API 差异from lib.lke_api.platform_management.auth.auth_api import AuthAPI from cases.platform_management.auth.permissions import AppPermissions # 用户直接授权 res AuthAPI.SetUserResourcePermissions( SpaceIdself.workspace_id, AccountUinself.sub_uin, PermissionsAppPermissions.adpAPP_no_permission, ResourceIds[*], ResourceTypeapp, ) if Error in res[Response]: raise Exception(f设置子账号权限失败. {res}) # 组织授权SubjectType1 表示组织 res AuthAPI.SetSubjectResourcePermissions( SpaceIdself.workspace_id, SubjectIdself.dept_id, SubjectType1, PermissionsAppPermissions.adpAPP_view, ResourceIds[*], ResourceTypeapp, ) time.sleep(40) # 等待权限生效注意time.sleep(40)这种细节必须写在 references 里而不是 SKILL.md。因为只有权限测试才需要等这么久计费测试可能只需要 5 秒。这就是分层披露的价值——把领域特有的坑隔离在对应文件里。.rules文件则记录更细粒度的约束比如某个目录下所有用例必须继承BaseAuthCase断言必须用self.assert_permission而不是原生 assert。5. 自动化测试验证加载顺序与命中率骨架搭好了怎么确认 Agent 真的按预期加载了正确的文件靠人眼看输出不靠谱写个自动化测试脚本。思路是给 Agent 一个测试任务拦截它读取文件的调用记录加载顺序然后断言关键文件是否被命中。import json import re from openai import OpenAI client OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL], ) SKILL_ROOT skills/api-test-writer def build_system_prompt(): with open(f{SKILL_ROOT}/SKILL.md, encodingutf-8) as f: return f.read() def extract_file_reads(text): 从模型输出中提取它声明要读取的文件路径 pattern r(?:读取|read|load)\s*[\]?([\w/\.\-]\.(?:md|rules|py)) return re.findall(pattern, text, flagsre.IGNORECASE) def run_case(task_desc, expected_files): resp client.chat.completions.create( modelclaude-sonnet-4-5, messages[ {role: system, content: build_system_prompt()}, {role: user, content: task_desc}, ], temperature0, ) output resp.choices[0].message.content reads extract_file_reads(output) hit [f for f in expected_files if any(f in r for r in reads)] miss [f for f in expected_files if f not in hit] rate len(hit) / len(expected_files) print(f任务: {task_desc[:40]}...) print(f命中: {hit}) print(f遗漏: {miss}) print(f命中率: {rate:.0%}) return rate # 测试用例权限测试应命中 auth.md 和对应 .rules rate run_case( 为权限模块编写一个新测试用例验证角色授权后成员继承权限, [references/auth.md, platform_management/auth/.rules], ) assert rate 0.8, f命中率过低: {rate}跑几次下来如果命中率低于 80%说明 SKILL.md 里的索引表描述不够明确或者工作流步骤的措辞让模型产生了歧义。我试过把根据用例所属功能域改成根据用例存放路径匹配下表命中率从 60% 提到了 95%。加载顺序也要验证。正确的顺序是 SKILL.md → references → .rules → 已有用例。如果模型先读用例再读规则说明工作流的强制力不够可以在 Step 1 里加一句在读取任何用例文件之前必须先完成规则文件的读取。6. 常见报错与排查清单报错一模型跳过了 references 直接写代码。症状是输出里没有文件读取声明直接开始生成。原因通常是 SKILL.md 的工作流用了建议可以这类软措辞。改成必须严格按顺序后基本能解决。如果还不行在系统提示末尾追加一句未读取 references 就生成代码视为任务失败。报错二命中率忽高忽低。检查索引表的路径是否和实际目录完全一致。大小写、下划线、复数形式都可能导致匹配失败。建议用脚本扫描一遍目录自动生成索引表避免手写笔误。报错三.rules文件被读取但内容没生效。这通常是.rules文件本身太长或者规则之间互相矛盾。.rules控制在 30 行以内只放该目录特有的约束公共规则上提到 SKILL.md。报错四API 返回 401 或 403。检查TAOTOKEN_API_KEY是否有多余空格以及 base_url 是否误加了路径后缀。正确写法是https://taotoken.net/api不要写成/api/v1。报错五模型输出被截断。长上下文任务容易触发 max_tokens 限制。在请求里显式设置max_tokens8192或者把任务拆成先读规则、再写用例两轮对话。排查时建议开temperature0排除随机性干扰。等结构稳定了再调高温度做多样性测试。7. 下一步把验证脚本接进 CI骨架和测试脚本都有了接下来把它接进 CI 流程。每次修改 SKILL.md 或 references 后自动跑一遍命中率测试低于阈值就阻断合并。这样技能文件的质量就有了可量化的保障而不是靠感觉好像变好了。如果你还在选模型阶段可以先用模型对话页面手动验证几轮确认工作流描述没有歧义https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentskill_progressive_disclosure长期跑编码类 Agent 任务的话Coding Plan 的额度模型更适合高频调用场景。接入细节参考官方文档里面有完整的 SDK 示例和错误码说明。整套方案的核心就一句让 Agent 只读它当下需要的知识剩下的交给目录结构去管理。