Skills:智能体技能(2)：从描述到加载：让智能体在正确时机用上技能

在上一篇中，我们介绍了概览、仓库结构、15 个示例技能分类、三种入口与入门写法。Anthropic 官方公开的 Agent Skills 示例仓库 anthropics/skills 创建于 2025 年 9 月 22 日，默认分支为 main，提交数 62，无 Release、无 Tag，在 2026 年 11 月 11 日 GitHub Trending 当日榜位列第 2 名（主要语言标注为 Python），Star 达 192,425，Fork 为 22,654，Watchers 为 1,171。Skill 是「指令、脚本与资源组成的文件夹」；根目录含 skills、spec、template、.claude-plugin 及 README.md、THIRD_PARTY_NOTICES.md。

当技能装好后，新问题随之而来：为什么技能有时不触发，又如何避免大量文档撑爆上下文？目前 skills 目录下共有 19 个技能文件夹：academy-guide、algorithmic-art、brand-guidelines、canvas-design、claude-api、discernment-nudge、doc-coauthoring、docx、frontend-design、internal-comms、mcp-builder、pdf、pptx、skill-creator、slack-gif-creator、theme-factory、web-artifacts-builder、webapp-testing、xlsx。spec 下仅有 agent-skills-spec.md，正文仅一句：规范现位于 agentskills 网站的 specification 页面；template 下仅有 SKILL.md，前置元数据为 name: template-skill 与一句提示替换为技能描述与何时使用的 description 占位话，正文只有「在下方插入指令」一行。本篇结合这三个技能，拆解从描述触发到加载评估的完整机制。

一、渐进披露三层加载机制

核心在于 skill-creator 的 Skill Writing Guide 提出的「渐进披露三层加载」机制：

**第 1 层：元数据（name 加 description）：**位于 SKILL.md 顶部 YAML 前置元数据中，约 100 词，始终在上下文里。

**第 2 层：SKILL.md 正文：**只在技能触发时进入上下文，理想长度在 500 行以内。

**第 3 层：配套资源：**包含脚本、参考文档与素材，按需加载，脚本无需加载进上下文即可直接执行。

围绕这三层结构，skill-creator 规定了三条具体的写作规矩：

**接近 500 行时再加一层：**并在正文中写清下一步去哪读。

**大参考文件附目录：**超 300 行的参考文件附目录，方便智能体定位。

**多领域技能按变体分文件：**例如 cloud-deploy 技能下的 references/ 目录分别建立 aws.md、gcp.md、azure.md，让 Claude 只按需读取相关的那一份文档。

二、写好 description：触发的第一道门与「推力」写法

根据 skill-creator 的规范，前置元数据中的 description 是技能的首要触发机制，编写时必须遵循两项原则：

**同时写清「技能做什么」与「何时使用」：**所有关于「何时使用」的信息都必须放在 description 里，绝不放在正文中，因为未触发时智能体看不到正文。

**描述要写得稍带「推力」：**Claude 目前有「触发不足」的倾向，因此描述要写得稍带「推力」，把用户可能的潜在表达兜进来。例如不要只写「如何搭建展示内部数据的看板」，而要补上一句：「当用户提到看板、数据可视化、内部指标，或想展示任何公司数据时都要用这个技能，哪怕用户没明说看板」。

以 skill-creator 自身为例，其 description 大意为：用于创建新技能、修改与改进已有技能、衡量技能表现；在用户想从零创建技能、编辑或优化已有技能、跑评估测试技能、做方差分析基准测试，或优化技能描述以提高触发准确率时使用。

三、技能文件夹解剖：三分法与正文准则

根据 skill-creator 的 Skill Writing Guide 对技能文件夹的通用解剖，除必需的 SKILL.md（内含 YAML 前置元数据与 Markdown 指令）外，可选配套资源分为三类：

**scripts/：**存放确定性、重复性任务的可执行代码，无需加载即可执行。

**references/：**存放按需读入上下文的参考文档。

**assets/：**存放输出用的模板、图标、字体等静态文件。

在编写技能正文时，skill-creator 给出了四点写作风格要求与一条安全底线：

**指令多用祈使句：**直接交代具体动作。

**少用生硬的「必须」，多解释为什么重要：**讲明背后的原因，帮助模型在复杂场景下准确理解意图。

**保持通用，不只盯着个别例子：**避免为迁就个别样例而把指令写得过于死板。

**写完初稿后换个眼光再改一遍：**重新审视结构以消除歧义。

**安全底线（Principle of Lack of Surprise）：**技能不得含恶意软件、漏洞利用代码或任何可能危害系统安全的内容，不得让用户产生与描述不符的意外；不得配合制作误导性技能或用于未授权访问、数据外泄等恶意用途的技能。

四、用 skill-creator 走一遍创建与评估迭代

skill-creator 正文定义了创建与打磨技能的六步工作流：

先定技能要做什么、大致怎么做；写初稿；编几个测试提示词并跑「带技能的 Claude」；定性与定量评估结果；按反馈重写；满意后再扩大测试集重跑。

过程保持灵活：只想凭感觉聊着改，也可以不跑评估；完成后还可用描述改进脚本优化触发。

当执行正式评估时，具体方法与文件规范如下：

**测试提示词与双路运行：**先写 2 到 3 个真实用户会说出的测试提示词，存入 evals/evals.json，初期先只写提示词、不写断言。每个用例在同一轮次一起启动跑两路——带技能一路与基线一路（新建时基线是不带技能，改进旧技能时基线是旧版快照）。

**工作区目录组织：**运行结果放在平级的 <技能名>-workspace/ 下，按 iteration-1/、iteration-2/ 分轮；每轮每用例一个目录，内分带技能与不带技能的输出目录。

**元数据、耗时与打分文件：**每个用例配 eval_metadata.json（含断言字段，初期可为空）；跑完后记耗时数据到 timing.json（含总 token 数与毫秒数）；打分结果存入 grading.json，每条期望结果须含 text、passed、evidence 三个字段；查看结果时运行 eval-viewer/generate_review.py 脚本生成评审页。

**断言原则：**好断言要客观可验证；写作风格、设计质量等主观技能更适合定性评估，不要硬套断言。

五、以 mcp-builder 为例看复杂技能的四阶段

mcp-builder 的 description 大意是创建高质量 MCP（模型上下文协议）服务器的指南，让大语言模型通过设计良好的工具与外部服务交互；在用 Python（FastMCP）或 Node/TypeScript（MCP SDK）搭建 MCP 服务器、接入外部 API 或服务时使用。其流程分为四个阶段：

**第一阶段：深入研究与规划：**在 API 全覆盖与工作流工具间取平衡，不确定时优先全面覆盖；工具命名要清晰并带一致前缀（如 github_create_issue、github_list_repos）；工具描述要简洁并支持过滤与分页；报错信息要给出具体建议与下一步。推荐语言为 TypeScript，传输方式为远程用可流式 HTTP、本地用标准输入输出；TypeScript SDK v2（@modelcontextprotocol/server）是当前稳定版，v1（@modelcontextprotocol/sdk）只收缺陷与安全修复，迁移命令为 npx @modelcontextprotocol/codemod@latest v1-to-v2 .，同一项目不要混用两个版本；Python 走 FastMCP。

**第二阶段：实现：**输入模式用 Zod（TypeScript）或 Pydantic（Python）并加约束、清晰描述与示例；尽量定义输出模式并用结构化内容返回；工具标注含 readOnlyHint、destructiveHint、idempotentHint、openWorldHint；异步处理输入输出并做好报错与分页。

**第三阶段：评审与测试：**TypeScript 跑 npm run build 验证编译，用 MCP Inspector（npx @modelcontextprotocol/inspector）测试；Python 用 python -m py_compile your_server.py 验语法，同样用 MCP Inspector 测试；评审时查重复代码、报错一致性、类型全覆盖与工具描述清晰度。

**第四阶段：创建评估：**检验大语言模型能否用该 MCP 服务器回答真实复杂问题；需编 10 道复杂、真实、可验证的问题，均为只读操作，答案单一明确且长期稳定；输出为 XML 格式，每对问答包在 qa_pair 里。

六、以 frontend-design 为例看设计类技能怎么写指令

frontend-design 的 description 大意是在新建或重塑界面时提供有辨识度、有意图的视觉设计指导，帮人定审美方向、排版与字体，避免读起来像模板默认值。其正文指令包含四个核心要点：

**角色与前置思考：**要求像以「每个客户都有独特视觉身份」著称的设计工作室的设计总监那样工作，先按简报定具体主题、受众与首要任务，再做设计。

**排版量化标准：**规定文字排版的默认行长少于 80 字符。

**两遍工作法：**工作分两遍推进，先出包含色彩、字体、布局与原则的紧凑设计方案并对照简报自查，确认不是通用默认款后再写代码。

**克制原则与质量底线：**遵循「把大胆用在一个地方」的克制原则，其余保持安静克制；质量底线包括移动端适配、键盘焦点可见、尊重减弱动效设置、视觉可访问与配色和谐。

七、落地清单与注意事项

本套方法适用于想沉淀重复工作、想解决技能触发时灵时不灵、想照官方示例写复杂技能的人：

守好第 1 层触发门：name 加 description 约 100 词，把「做什么」与所有「何时使用」放进 description 并写出「推力」。

控好第 2 层与第 3 层边界：SKILL.md 正文控制在 500 行内，超 300 行参考文件附目录，多领域变体按 aws.md、gcp.md、azure.md 拆分。

**落实资源三分法：**确定性重复代码放 scripts/，按需文档放 references/，模板图标字体放 assets/。

**遵守文风与无意外原则：**多用祈使句、多解释原因、保持通用，严守安全底线，杜绝恶意代码或偏离描述的行为。

**用双路评估迭代：**以 evals/evals.json、<技能名>-workspace/、timing.json、grading.json 与 eval-viewer/generate_review.py 做对照验证，主观技能优先定性评估。

最后需注意，仓库中许多技能以 Apache 2.0 开源，mcp-builder 与 frontend-design 的前置元数据中另有 license 字段，完整条款见 LICENSE.txt。官方提示这些技能仅作演示与教学用途，实际产品中的实现与行为可能与仓库展示不同，关键任务前应在自己的环境里充分测试。