Anthropics 官方对 Claude Skills 做了一次重大更新：SKILL.md 配置骨架与验证动作

1. 从一次 PR 说起SKILL.md 为什么突然值得重学Anthropics 官方维护的 Claude Skills 仓库在 2026 年 2 月底合并了一次架构级更新PR 编号 #465。这次改动在社区里讨论度不算高但如果你正在做 Prompt Engineering 或者 Skill Creation它其实改变了你写 SKILL.md 的方式。简单说Claude Skills 是 Anthropics 官方提供的一套扩展能力标准开发者通过特定文件结构核心就是 SKILL.md让 Claude 能加载外部工具、执行复杂工作流、遵循企业规范。它支撑了 docx、pdf、pptx 这类高级能力的底层实现也是学习高质量系统提示词的最佳教材。这次更新把 Skill 创建从「概念说明」推向了「流程化执行」新增了 grader、comparator、analyzer 三个 agent 角色引入了 run_loop.py、run_eval.py 和 HTML 评估报告把 Prompt 开发从「凭感觉写」变成「测试驱动」。同时明确了迭代触发规则——测试发现低效或错误必须立即更新 SKILL.md 并复测文档校验不通过要回退上一版本禁止带病发布。统一了简洁性、精准性、可读性、兼容性四大评估维度。对普通开发者来说这意味着两件事第一SKILL.md 的写法有了更明确的骨架要求不再是随便写段提示词就行第二你本地跑通一个 Skill 之后得有一套验证动作确认它真的生效而不是「感觉好像可以了」。下面我会给你一份可直接复制的 SKILL.md 配置骨架、目录结构以及从拿 Key 到验证生效的完整动作。适合正在做 Agent 落地、Prompt 工程化、或者想把自己的一套工作流封装成可复用 Skill 的人。2. 前置准备TaoToken 接入与目录规划在写 SKILL.md 之前先把调用链路打通。Claude Skills 本身是能力定义层真正跑起来还是要有模型接口。我这边用的是 TaoToken 的 API 来做本地验证它的接口兼容 Anthropic 风格配置起来比较直接。官网入口在这里https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 这个不加 UTM。你需要先去控制台创建一个 API Key然后把它放到环境变量里不要硬编码在代码或 SKILL.md 里。目录结构建议按官方仓库的约定来组织一个 Skill 一个独立文件夹SKILL.md 放在根目录辅助脚本放 scripts/评估用例放 evals/。下面是我实测下来比较顺手的结构my-skill/ ├── SKILL.md # 核心定义文件 ├── scripts/ │ ├── run_loop.py # 评估循环可选 │ └── run_eval.py # 单次评估可选 ├── evals/ │ └── cases.jsonl # 真实业务任务用例 └── assets/ └── template.md # 输出模板可选这里有个坑要提前说SKILL.md 不是越长越好。更新后的规范强调冗余文件管控你放太多无关说明反而会拉低加载效率。骨架清晰、职责单一比堆砌内容更重要。3. 可复制的 SKILL.md 配置骨架下面这份骨架是我根据更新后的规范整理的你可以直接复制改。它包含四个必备区块元信息、能力描述、执行流程、验证断言。注意 YAML front matter 里的字段名要和官方约定一致否则加载会失败。--- name: doc-summarizer description: 将长文档压缩为结构化摘要保留关键数据与结论 version: 1.0.0 author: your-name tags: - document - summarization --- # Doc Summarizer ## 能力说明 本 Skill 接收一段长文本或文档路径输出包含「核心结论、关键数据、待办事项」三段式的结构化摘要。适用于会议纪要、技术方案、调研报告的快速提炼。 ## 输入约束 - 输入长度单次不超过 8000 字 - 输入格式纯文本或 Markdown - 不支持图片、扫描件、加密文档 ## 执行流程 1. 通读全文识别文档类型纪要 / 方案 / 报告 2. 提取核心结论控制在 3 条以内 3. 抽取关键数据保留原始单位和上下文 4. 列出待办事项标注责任人与时间节点若有 5. 按输出模板组装检查是否遗漏 ## 输出模板 markdown ### 核心结论 - ... ### 关键数据 - ... ### 待办事项 - ...验证断言摘要长度不超过原文的 20%核心结论必须可追溯到原文具体段落关键数据不得出现单位丢失或数值篡改待办事项若原文未提及输出「无」写这份骨架时有几个细节值得注意。description 字段要写清楚「做什么」和「适用场景」这是模型判断是否触发该 Skill 的主要依据。执行流程要拆成可执行的步骤不要写成一段模糊描述。验证断言是这次更新强化的重点它对应评估闭环里的断言检查你写得越具体后面跑 run_eval.py 时越容易发现问题。 ## 4. 验证动作从本地请求到确认生效 骨架写完之后必须做验证。更新后的规范明确要求基于「真实业务任务」测试而不是模拟用例。我一般分三步走先做单次请求确认接口通再跑评估脚本确认质量最后用真实任务复测确认落地可用。 第一步用 curl 发一个最小请求确认 API Key 和模型调用链路正常 bash export TAOTOKEN_API_KEY你的key curl -s https://taotoken.net/api/v1/messages \ -H x-api-key: $TAOTOKEN_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 1024, messages: [ {role: user, content: 用一句话说明什么是 SKILL.md} ] }如果返回里有正常的 content 字段说明链路通了。这一步失败的话先检查 Key 是否复制完整、环境变量是否生效。第二步把 SKILL.md 的内容作为 system prompt 注入测试 Skill 是否按预期格式输出import os import requests api_key os.environ[TAOTOKEN_API_KEY] skill_md open(my-skill/SKILL.md, encodingutf-8).read() resp requests.post( https://taotoken.net/api/v1/messages, headers{ x-api-key: api_key, anthropic-version: 2023-06-01, content-type: application/json, }, json{ model: claude-sonnet-4-20250514, max_tokens: 2048, system: skill_md, messages: [ {role: user, content: 请总结以下会议纪要\n\n open(evals/sample.txt, encodingutf-8).read()} ], }, ) print(resp.json()[content][0][text])跑完之后对照验证断言逐条检查长度是否超标、结论是否可追溯、数据有没有被改、待办是否标注。任何一条不满足就回到 SKILL.md 修改对应区块然后重新跑。这就是更新里说的「测试发现低效或错误后必须立即更新并复测」。第三步用真实业务任务复测。找一份你手头真实的文档走一遍完整流程看输出能不能直接用。如果还需要大量人工返工说明 Skill 的约束还不够紧继续迭代。5. 本篇常见错排查实际落地时下面这几个问题出现频率最高我按排查顺序列出来。SKILL.md 加载后模型没反应。先看 YAML front matter 的格式冒号后面要有空格缩进用两个空格不要用 Tab。name 字段不能有空格和大写字母建议全小写加连字符。description 太短也会导致触发判断失败至少写清楚动作和对象。请求返回 401 或 403。检查 API Key 是否放在x-api-key头里而不是Authorization: Bearer。Anthropic 风格的接口用的是前者。另外确认环境变量在当前 shell 会话里已经 export子进程能读到。输出格式不稳定有时带模板有时不带。这是 system prompt 约束不够硬。把输出模板用代码块包起来并在执行流程最后一步明确写「严格按输出模板组装不得增删区块」。更新后的规范强调精准性模糊描述会被模型自由发挥。评估脚本跑不通。run_eval.py 依赖 evals/cases.jsonl每行一个 JSON 对象至少包含 input 和 expected_assertions 两个字段。文件末尾不要留空行否则解析会报错。如果用的是官方脚本注意 Python 版本要求 3.10 以上。改了 SKILL.md 但效果没变化。大概率是缓存或者路径问题。确认你加载的是修改后的文件而不是旧副本。如果是通过某个框架加载检查它有没有做文件监听。最稳妥的方式是每次修改后重启一次调用进程。真实任务复测时输出质量波动大。这通常不是 Skill 本身的问题而是输入长度超了约束。回到输入约束区块把长度上限调低或者在执行流程第一步加一个「超长则分段处理」的分支。6. 把 Skill 变成可持续迭代的资产这次更新最核心的信号是 Skill 从「一次性创作」变成了「持续优化的活资产」。你写完 SKILL.md 只是起点后面的评估循环才是重点。我自己的习惯是每改一版就存一个版本号在 evals 里保留对应的用例这样回退时有依据。如果你要长期做编码类或 Agent 类的 Skill 开发可以考虑用 Coding Plan 来跑批量评估成本比单次调用可控。想先验证模型对某个 Skill 的响应效果可以直接在模型对话里贴 SKILL.md 试。需要管理多个 Key 或者查看调用量去控制台和 API Keys 页面操作就行。接入文档里有完整的参数说明和错误码对照遇到报错先查那里。最后留一个实用技巧SKILL.md 里的验证断言尽量写成可程序化检查的形式。比如「长度不超过原文 20%」可以算「结论可追溯」可以要求模型输出时带上原文段落编号。断言越可测你的评估循环就越省力Skill 的质量也越稳。