1. 先搞清楚 SKILL.md 到底解决什么问题Agent Skills 这个词最近出现频率很高但很多人第一次接触会误以为它又是某种 prompt 模板或者插件格式。实际上它更接近一种「带发现元数据的文件系统知识包」一个目录入口固定叫SKILL.md里面用 YAML frontmatter 声明name和description正文写流程和约束旁边可以挂references/、scripts/、assets/。Agent 启动时只把元数据放进上下文等用户请求命中description之后才去读正文更深层的资料和脚本只在任务真正需要时才访问。这套机制叫渐进式披露progressive disclosure核心价值是让一个 Agent 同时「会很多流程」又不把上下文撑爆。我试过把一份两千行的内部规范直接塞进 system prompt结果每轮对话都在为它付 token而且模型经常在无关任务里被这些规范干扰。换成 Skill 目录之后启动阶段每个技能只占大约一百 token 的元数据未触发的技能几乎零成本。这就是它适合的场景可重复的程序性工作流比如按仓库约定开 PR、填 PDF 表单、走固定审计步骤、生成周报细节很长但单次任务只碰一小块的参考资料希望用脚本落地确定性校验的环节。不适合的场景也要说清楚需要稳定契约化外部调用的那是 MCP tools 的职责一次性临时指令直接写在对话里就行运行面没有文件系统和代码执行能力的按官方模型根本没法用 bash 读 Skill。三级加载的分工可以这样理解。Level 1 是name加description启动时进入 system模型靠它做相关性匹配所以description不是产品简介而是触发条件说明书。Level 2 是匹配成功后读入SKILL.md正文官方表记在 5k token 以内实践上正文控制在 500 行以内比较稳。Level 3 是references、scripts、assets按需访问引用文件读入才占上下文脚本经 bash 执行后只有输出进入上下文源码本身不计费。这三层咬合起来才叫真正的渐进式披露把三层压成一层就等于退化成 system 塞满。字段规则必须先钉死否则后面全是白忙。name只允许小写字母、数字、连字符最长 64 字符不能含 XML 标签也不能出现anthropic、claude这类保留词。description非空、最长 1024 字符并且必须同时说明「做什么」和「何时用」。Claude Code 的目录约定是个人级~/.claude/skills/、项目级.claude/skills/。API 侧 Skills 跑在带 code execution 的容器里自定义 Skill 的共享范围因表面而异claude.ai 是个人上传API 是 workspace 共享Claude Code 是本地目录或插件分发不要假设上传一次处处可用。安全边界也得提前讲。官方安全章节明确要求只使用可信来源使用前审计SKILL.md、脚本与资源警惕外链拉取内容把安装 Skill 当作安装软件。API 容器常见约束是无网络、不能随意装包Claude Code 与本机权限一致网络可达性更强治理要更严。这一段不是客套话社区包里出现诱导 bash 调用和外联的案例并不少见。2. 接入前的准备统一 Key 与 API 通道要把这套东西跑起来验证你需要一个能稳定调用模型、并且支持工具调用轨迹观察的通道。我这边习惯用 TaoToken 做统一入口官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 。它的作用是把你对不同模型的调用收敛到一套 Key 和一套 Base URL 上省得在多个平台之间来回切换配置。注意这里说的是正常 API 接入不是任何形式的网络绕行方案配置里只出现 Base URL 和 Key 两个变量。前置动作分三步。第一步在控制台创建 API Key地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 创建后立刻复制保存页面通常只完整展示一次。第二步确认你要用的模型 ID这个值必须和通道侧声明的名称完全一致写错一个字符就会在请求阶段报模型不存在。第三步把 Base URL、Key、Model ID 这三件套记在一个地方后面所有配置文件都从这里取值避免同一篇文章里出现两套不一致的参数。如果你打算长期做编码类 Agent 的调试可以顺带看一下 Coding Plan 的说明页 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 它面向的是持续编码和 Agent 场景的用量安排。只是偶尔验证一次模型行为的话用按量 Key 就够了不必上套餐。模型对话的在线调试入口在 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 适合先手动问两句确认通道通不通再去写配置文件。这里有个容易忽略的点Skills 的验证依赖「工具调用轨迹」也就是你要能看到模型到底有没有去cat那个SKILL.md。所以通道侧必须允许工具调用并且你的客户端要能把工具调用记录打印出来。纯文本补全接口是看不到这些的。选模型时优先挑支持 function calling 或工具协议的型号否则你只能验证「回答像不像」验证不了「加载对不对」。另外提醒一句Key 不要写进会提交到 Git 的文件。项目级.claude/skills/是要进版本库的但 Key 应该走环境变量或者本地未跟踪的配置文件。我见过有人把 Key 直接写进settings.json然后推上公开仓库几分钟内就被扫到。养成习惯目录结构可以分享凭据永远外置。3. 可复制配置目录树、SKILL.md 与客户端设置先落盘目录。以项目级为例在仓库根目录建这样一棵树.claude/skills/ └── pr-checklist/ ├── SKILL.md ├── references/ │ └── REVIEW_POLICY.md └── scripts/ └── check_diff_stats.sh目录名和name字段保持一致人和机器对齐排查时少一层心智负担。个人级就把整个pr-checklist放到~/.claude/skills/下。接着写最小可用的SKILL.md。frontmatter 里description必须同时含 WHAT 和 WHEN正文保持短把长政策外置--- name: pr-checklist description: 按仓库约定检查 PR 的测试、changelog 与风险说明。在用户要求开 PR、自检 diff、或提到 pull request / changelog 时使用。 --- # PR Checklist ## 快速流程 1. 用 git 查看当前分支相对主分支的 diff 范围。 2. 确认测试命令与 changelog 条目是否齐全。 3. 若 diff 统计异常过大或仅格式化先读 references/REVIEW_POLICY.md。 4. 需要机器汇总时运行 scripts/check_diff_stats.sh只根据脚本输出决策。 ## 约束 - 不要在未读 diff 的情况下声称「已覆盖全部文件」。 - 政策细节以 references/REVIEW_POLICY.md 为准不要凭记忆编造门槛。references/REVIEW_POLICY.md放阈值、禁止合并条件、审查问题清单只在流程走到「需要政策」时才读。scripts/check_diff_stats.sh输出增删行数、文件类型分布这类短结果避免把脚本全文贴进正文反复占用 L2。客户端配置以 Claude Code 的settings.json为例路径与原文一致放在项目.claude/settings.json或用户级配置里{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的Key, ANTHROPIC_MODEL: 你的模型ID } }三件套齐了Base URL 指向https://taotoken.net/apiKey 走ANTHROPIC_AUTH_TOKENModel ID 填通道侧声明的名称。如果你用的是 Cline 这类支持 MCP 的客户端配置形态换成对应的 JSON 字段但 Base URL、Key、Model ID 这三个值不变。Codex 系的auth.json同理字段名不同语义一致。{ base_url: https://taotoken.net/api, api_key: sk-你的Key, model: 你的模型ID }写完配置后新开一个会话让发现机制重新扫描技能目录。改完不重启是最常见的「配置没生效」原因先排除这一条再怀疑别的。4. 验证请求与成功结果用访问轨迹验收验证不要靠感觉要靠轨迹。准备两条对照请求一条明显无关比如问今天天气一条明显命中比如「按仓库约定帮我自检这个 PR 的 diff」。然后观察工具调用记录。无关请求下轨迹里不应该出现对该 Skill 目录下SKILL.md的读取上下文占用应该主要是元数据。命中请求下应该出现一次或少量对SKILL.md的读取随后步骤与正文流程一致。如果任务只需要文本抽取不应该额外读取REVIEW_POLICY.md如果流程走到需要机器汇总应该出现 bash 执行脚本且上下文增量主要是输出文本而不是脚本源码。用 curl 先确认通道本身通不通这一步和 Skill 无关但能快速定位问题层级curl https://taotoken.net/api/v1/messages \ -H Content-Type: application/json \ -H x-api-key: $ANTHROPIC_AUTH_TOKEN \ -H anthropic-version: 2023-06-01 \ -d { model: 你的模型ID, max_tokens: 64, messages: [{role: user, content: 回复 ok}] }返回里出现正常的content数组就说明 Key、Base URL、Model ID 三件套没问题。如果这里就失败先别去动 Skill 目录问题在接入层。通道通了之后把观察写成测试记录格式建议固定下来请求类型、是否读取SKILL.md、读取次数、是否读取 reference、是否执行脚本、上下文增量大致量级。这份记录比「感觉它加载了」有用得多团队里换人接手也能复现。如果你在自建 Agent 里复刻这套机制最小实现同样是三层启动时注入 metadata 列表触发时read_file(SKILL.md)正文解析出的路径再按条件read_file或run_script。千万不要在启动时把所有SKILL.md正文拼进 system那会直接退化成 system 塞满渐进式披露名存实亡。5. 常见报错排查401、local proxy failed 与 reading choices排障第一步永远是分层接入层、发现层、加载层、执行层。下面这几类是我实际遇到频率最高的。401 Unauthorized基本都在接入层。先确认 Key 有没有多余空格复制时首尾带空格是高频事故再确认请求头字段名对不对Anthropic 风格用x-api-keyOpenAI 兼容风格用Authorization: Bearer混用会直接 401最后确认 Base URL 有没有多写或少写/v1路径拼错有时表现为 404有时表现为鉴权失败。用上面那段 curl 单独测能快速把接入层和 Skill 层切开。local proxy failed这类报错通常出现在客户端尝试走本地转发但端口没起来或者环境变量里残留了旧的代理配置。检查settings.json里有没有多余的代理字段检查 shell 环境里有没有遗留的HTTP_PROXY之类变量。清掉之后重启客户端。注意这里说的是清理本地残留配置不是让你去搭任何转发通道配置里只应该出现https://taotoken.net/api这一个地址。reading choices或类似的响应解析错误多半是返回体结构和客户端预期不一致。常见原因是 Model ID 写错导致通道返回了错误对象客户端却按成功响应去解析choices字段。先把 Model ID 和通道侧声明逐字符比对再用 curl 看原始返回别在客户端日志里猜。OAuth 相关报错出现在 Claude Code 登录态场景。如果你用的是 Key 方式接入就不该触发 OAuth 流程出现这类报错说明客户端还在走账号登录分支。检查配置优先级确保ANTHROPIC_AUTH_TOKEN生效必要时清掉旧的登录缓存再试。Skill 不触发是另一类问题报错信息往往没有只是「装了等于没装」。九成是description只写了能力没写场景。把用户可能说出的关键词写进 WHEN比如「提到 pull request / changelog 时使用」。其次是name含大写、下划线、空格或保留词导致发现阶段被拒。再其次是目录放错位置项目级放到了用户级路径下或者改完没新开会话。脚本执行失败要看运行面差异。API 容器常见无网络、不能随意装包同一个脚本在 Claude Code 能跑、在 API 容器里就挂。排查时先确认脚本只依赖容器内已有命令把外部依赖降到最低。脚本输出也要控制体量输出几千行日志等于把 L3 的成本又拉回 L2。6. 把验证闭环固定下来这套东西真正落地之后我建议把两件事固化成习惯。第一每个 Skill 配一份对照请求清单无关一条、命中短路径一条、命中长路径一条、命中脚本一条改完description或正文就跑一遍看轨迹是否符合预期。第二description当成路由表条目来维护同一仓库多个 Skill 并存时让它们的 WHEN 互斥到不会同时命中或者命中后可组合比如pdf-extract强调文本表格抽取、pdf-forms强调填表与字段映射两者在触发词上切开。需要长期跑编码类 Agent、频繁调试工具调用轨迹的话Coding Plan 页面 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里有用量安排说明只是验证模型行为和 Skill 加载用按量 Key 配合模型对话入口 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 手动问两句就够。Key 的创建和管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 接入细节和字段说明看文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。Claude Code 相关的接入说明在 https://taotoken.net/ClaudeCodeAnthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 配置字段和本文的settings.json片段对得上。最后留一个实操细节把scripts/下的脚本都加上可执行位chmod x scripts/check_diff_stats.sh否则 bash 执行时会报权限拒绝而这个报错在轨迹里看起来很像「脚本没被调用」容易误判成加载问题。改完权限、改完description、新开会话、跑对照请求四步走完再下结论。