教 Claude 新技能的正确姿势从 YAML 元数据到幂等脚本手写你的第一个技能包【免费下载链接】skillsPublic repository for Agent Skills项目地址: https://gitcode.com/GitHub_Trending/skills3/skillsClaude 很强但强和听话之间隔着一道巨大的鸿沟。你可以在提示词里反复描述公司周报的格式要求也可以在每次生成 PDF 表单时祈祷它记得上次的排版约定——但每一次这样的现场教学都意味着上下文窗口被占用、结果不可复现、流程无法沉淀。Anthropic 在 2025 年推出的 Agent Skills 机制就是为了终结这种状态把如何完成某类任务封装成一份可动态加载的技能包让模型负责理解让代码负责执行。社区里围绕它的讨论几乎同步爆发——从1.17 万赞的 321 字节 ELI5 技能到各大开发者对 16 个官方技能的拆解Skill 正在成为继 MCP 之后又一个改变 AI 工程化形态的抓手。这篇文章不打算停留在概念层面。我会直接翻开skills3/skills这个官方仓库的真实源码拆解一个技能包的标准解剖结构、YAML 元数据规范以及幂等 结构化输出这两个让技能可重跑、可验证的硬约束最后带你从零手写一个每周周报自用技能。读完你就能动手造出自己的第一个.skill文件。技能包结构解剖说明、脚本、资源三件套与 YAML 元数据规范仓库 README.md 对 Skill 给出了一个精确定义Skills are folders of instructions, scripts, and resources that Claude loads dynamically——一个技能本质上就是一个文件夹里面装着教模型怎么干的说明、替模型干重活的脚本和供模型取用的资源。在 skills/skill-creator/SKILL.md 中这个结构被画成了标准的解剖图skill-name/ ├── SKILL.md (required) │ ├── YAML frontmatter (name, description required) │ └── Markdown instructions └── Bundled Resources (optional) ├── scripts/ - Executable code for deterministic/repetitive tasks ├── references/ - Docs loaded into context as needed └── assets/ - Files used in output (templates, icons, fonts)三个子目录各有分工scripts/放确定性的、重复性的可执行代码references/放按需载入的文档assets/放产出物要用的模板、图标、字体。你可以直接打开仓库里的任何技能验证这套结构——比如 skills/webapp-testing 用scripts/with_server.py管理服务器生命周期skills/slack-gif-creator 在core/下提供了GIFBuilder工具类而 skills/theme-factory 则在themes/里放了 10 套配色主题资源。目录骨架只是表象真正的规范核心是SKILL.md顶部的YAML frontmatter。仓库根目录的 template/SKILL.md 给出了最小可用形态只有两个必填字段--- name: template-skill description: Replace with description of the skill and when Claude should use it. --- # Insert instructions belowname是技能的唯一标识description是何时触发、做什么事的完整描述。这两个字段不是随便填的仓库自带的校验脚本 skills/skill-creator/scripts/quick_validate.py 暴露了全部硬性规则name必须是 kebab-case仅小写字母、数字、连字符最长 64 字符description最长 1024 字符且禁止出现尖括号可选的license、allowed-tools、metadata、compatibility也是白名单内的合法字段。也就是说一个合法技能的元数据是机器可校验的——这也是它和普通 Markdown 提示词最本质的区别。关于description官方还藏着一个容易被忽视的工程建议skills/skill-creator/SKILL.md 明确指出它是唯一的触发机制而 Claude 有一种欠触发倾向——明明技能有用却不调用。对策是让描述写得强势一点pushy把触发场景穷举进去。对比仓库里真实的 skills/docx/SKILL.md你会发现它的 description 长达数行不仅说了创建/读取/编辑 Word 文档还枚举了.docx、.dotx、report、memo、template 等大量触发词甚至反向声明PDF、电子表格、Google Docs 不用本技能。这种写法不是啰嗦而是精确划定技能边界。元数据之下是正文。规范对正文同样有约束理想情况下控制在 500 行以内如果内容变厚就增加一层层级并在 SKILL.md 里明确下一步该读哪个 reference 文件。整套设计遵循的是**渐进披露progressive disclosure**三级加载模型name description 永远在上下文中约 100 词SKILL.md 正文在技能被触发时加载500 行捆绑资源按需加载无上限脚本甚至可以在不载入的情况下直接执行。这意味着你写的技能包越大越要为模型设计好先读什么、再看什么的导航路径。幂等与结构化输出让技能「可重跑、可验证」的两个硬约束元数据规范解决的是什么时候用而让一个技能真正能进生产环境靠的是两个比提示词更硬的约束——幂等与结构化输出。社区里不少教程在总结自建技能经验时都把这俩列为新手三大易错点中的前两名而这个仓库正是践行这两点的范本。先看幂等。一个技能封装的脚本往往会被反复调用用户可能会要求再跑一遍、把上个月的数据也过一遍或者技能在多步工作流里被重复触发。如果脚本每跑一次就叠加一份副作用——重复插入行、重复追加段落、覆盖已有结果——技能就变成了一次性消耗品。仓库的做法是让脚本自带原地重跑能力skills/xlsx/SKILL.md 要求所有产出必须经过scripts/recalc.py重算该脚本会把工作簿原地重写并返回 JSON 状态报告status为success才允许交付skills/docx/SKILL.md 的编辑流程则是标准的 unzip → 修改 XML → rezip用scripts/merge_runs.py把 Word 拆散的文本 run 合并后再查找替换保证同样的操作重复执行不会因 run 结构差异而结果漂移。这些设计背后是同一个原则同一份输入无论跑多少次产出都应该稳定一致。再看结构化输出。技能区别于闲聊式提示词的关键在于它的产出可以被程序化验证。文档类技能普遍遵循产出 → 渲染 → 目检的验证链比如 skills/docx/SKILL.md 中生成完.docx后必须soffice转 PDF、pdftoppm渲染成图片让模型亲眼看一遍排版skills/xlsx/SKILL.md 更是把Zero formula errors列为硬性验收标准并注明一个你引入的错误看起来和继承来的错误一模一样——所以必须用data_onlyTrue加载原始文件比对而不是凭感觉。最系统化的验证机制藏在 skill-creator 的评测体系里。它要求每个技能配套evals/evals.json用可客观验证的断言assertion描述成功标准比如输出包含 John Smith 这个名字、单元格 B10 有 SUM 公式评测时对同一个测试 prompt 同时跑 with-skill 和 without-skill 两组基线聚合出 pass_rate、耗时、token 消耗的对比数据完整 schema 见 skills/skill-creator/references/schemas.md。这套机制把技能好不好从主观感觉变成了可量化的指标——正如 schema 注释里写的那样好的断言应当即使换一个模型去跑也能稳定判出通过与否。此外还有一个实用的工程惯例脚本要作为黑盒使用。 skills/webapp-testing/SKILL.md 明确要求永远先跑--help再看用法不要一上来读源码因为大脚本会污染上下文窗口。这揭示了一个关键认知技能里的脚本存在的意义是替你省 token、省步骤而不是被逐行理解。你的技能脚本也应该追求这种自包含、带参数说明、一次调用出结果的设计。从高频痛点选题把「每周周报」封装成第一个自用技能理解了结构和约束选题就成了最后一块拼图。什么样的任务值得封装成技能标准很简单高频、重复、有明确格式、产出可验证。每周五都要写的周报就是这个标准最典型的猎物。仓库里的 skills/internal-comms 就是一个极好的参照——它把公司内部沟通拆成了 3P updatesProgress/Plans/Problems、公司简报、FAQ、状态报告等类型每种对应examples/下的一个模板文件触发时按类型加载对应指南。照着这个模式我们可以手写一个weekly-report技能。第一步是定元数据--- name: weekly-report description: 生成符合团队格式的每周工作周报。当用户提到周报、本周总结、weekly report、写周报时使用本技能即使他们只给了零散的聊天记录或 git 提交。注意这是高频自用技能不要因为任务看起来简单就跳过它。 --- # Weekly Report Generator 按以下步骤生成周报 1. 收集材料优先读取用户指定的 git log、任务列表或会议记录 2. 按 3P 结构组织内容Progress / Plans / Problems格式参考下方模板 3. 输出为结构化 Markdown并额外渲染一份 .docx 交付物 4. 交付前检查每条 Progress 都有对应证据提交号/链接没有空话套话。注意 description 里的pushy写法——这正是从官方 skills/skill-creator/SKILL.md 学来的触发优化技巧。第二步是把重复劳动脚本化与其每次让模型在上下文里翻 git log不如在scripts/里放一个collect_changes.py自动汇总两个日期之间的提交、按模块聚类、输出 JSON。这样一来收集材料这个步骤就从模型自由发挥变成了确定性执行——模型负责组织和表达脚本负责事实采集这正是模型理解、代码执行分工范式的落地。第三步是测试。按官方流程写完后要准备 2-3 个贴近真实的测试 prompt比如我这周做了 X 功能帮我写周报这是 git log 路径分别跑带技能和不带技能两组用 skills/skill-creator/scripts/aggregate_benchmark.py 聚合对比。一个合格的周报技能应该让输出是否包含 3P 结构每条进展是否有证据支撑这类断言稳定通过。最后用 skills/skill-creator/scripts/package_skill.py 打包——该脚本会先跑 quick_validate 校验再剔除__pycache__、node_modules、.pyc等构建产物把技能目录压成一个可分发、可安装的.skill文件zip 格式。至此一个完整的自用技能闭环就成立了YAML 元数据定义触发边界Markdown 正文定义工作流scripts/承载幂等的确定性逻辑评测断言保证产出可验证打包脚本让它可分发。这 30 分钟的手工活换来的是以后每一次周报都稳定、可复现、不占提示词额度。当 AI 的能力不再只靠现场发挥而开始依赖你亲手沉淀的技能资产时你才算真正从使用 AI迈向了教 AI。【免费下载链接】skillsPublic repository for Agent Skills项目地址: https://gitcode.com/GitHub_Trending/skills3/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考