企业官网建设流程全解析

教 Claude 新技能的正确姿势：从 YAML 元数据到幂等脚本，手写你的第一个技能包

【免费下载链接】skillsPublic repository for Agent Skills项目地址: https://gitcode.com/GitHub_Trending/skills3/skills

Claude 很强，但"强"和"听话"之间隔着一道巨大的鸿沟。你可以在提示词里反复描述公司周报的格式要求，也可以在每次生成 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 below

name是技能的唯一标识，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_only=True加载原始文件比对，而不是凭感觉。

最系统化的验证机制藏在 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 updates（Progress/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