设计一套可长期维护的 Agent Skills 体系，核心是把技能做成「带元数据的文件夹 + 按需加载的说明文档」，而不是一堆散落的提示词。Anthropic 的 Agent Skills 给出了可参照的标准：每个技能是一个含 SKILL.md 的目录，前置元数据只保留 name 和 description，正文控制在 500 行以内，长内容拆到 references/ 子文件按需读取。真正难的不是写第一个技能，而是技能数量上去之后的管理：命名混乱导致不被调用、上下文膨胀、验证缺位、版本漂移。
一、单个 Skill 的标准结构
Skill 的本质是「领域知识 + 辅助脚本」的标准化封装。目录结构约定如下：
my-skill/
├── SKILL.md # 必需：元数据 + 指令正文
├── scripts/ # 可选：可执行脚本
├── references/ # 可选：长篇参考资料
└── assets/ # 可选：模板与资源文件SKILL.md 的最小可用写法：
---
name: processing-pdfs
description: 当用户需要提取、合并或拆分 PDF 文件时使用此技能。
---
# PDF 处理
1. 用 pdfplumber 提取文本，先验证页数与预期一致；
2. 合并文件前备份原件到 backup/ 目录；
3. 输出前用 pypdf 重新打开校验页数与可读性。命名用「动名词」结构（analyzing-data、processing-pdfs），拒绝 helper、tools 这类模糊名。description 是技能的广告位，必须写清功能与触发时机，Agent 是否调用某个技能，完全取决于它读到的名称和描述。
二、体系层面的设计原则
2.1 上下文经济
上下文窗口是昂贵的公共资源。每加一个技能，它的 description 都会进入每次会话的上下文，无论是否被触发。100 个 token 的描述、1000 名工程师、每天 10 次会话，就是每天 100 万 token 的固定开销。所以技能只写模型不知道的领域知识，通用常识一律不写。
2.2 渐进式披露
SKILL.md 只做「地图」，正文给索引和关键指令；详细指南、模板、参考数据放子文件，Agent 确实需要时再读。超过 100 行的资源文件在顶部加目录。这一层设计同时省 token 和防注意力分散。
2.3 指令僵硬度分级
按任务风险设定自由度，这是体系设计里最容易被忽略的一条：
| 任务类型 | 风险 | 指令形态 | 示例 |
|---|---|---|---|
| 代码审查 | 低 | 高自由度，给原则即可 | 只列检查要点 |
| 数据提取 | 中 | 步骤化，给清晰流程 | 分步操作 + 中间校验 |
| 数据库迁移 | 高 | 脚本化，严格清单 | 逐项打勾 + 强制验证 |
2.4 验证闭环
复杂流程提供显式 Checklist，要求 Agent 逐项勾选。关键操作后必须跟验证步骤，形成「执行 → 验证 → 修正」循环。Anthropic 官方 xlsx 技能在生成表格后用 recalc.py 重算公式并检查 #REF!、#DIV/0! 错误，就是这个模式。
三、落地一个 Skills 体系的三步流程
- 先裸测：不写任何技能，让 Agent 直接做任务，记录它绕的路和失败点，这些缺口才是技能要填的内容；
- 写评测再写技能：把任务编码成可重复的 eval，拿到基线分数，技能上线后再测一次，确认它真的带来提升而不是噪音；
- 规范治理：技能纳入 Git 管理，用 tag 和 CHANGELOG 做版本，变更走代码评审，高风险技能强制 human-in-the-loop。
四、实际项目中的四个挑战
技能不被调用。 多数情况是 description 写得含糊。修复方法：用第三人称写清触发条件，加入具体关键词，跨模型实测——轻量模型往往需要更明确的触发描述。
自我验证偏差。 Skill 架构下 Agent 自己执行、自己验证，前一步的错误会带进下一步。补强手段有三档：工具层强制验证脚本（可编码规则）、关键输出点引入独立 Reviewer Agent（高风险任务）、对外发布内容强制人工审核。
版本与漂移。 官方未定义 pin 语义，团队要自建纪律：Git tag 定版本、CHANGELOG 记兼容性、生产环境锁定技能版本，禁止静默更新。
生态与合规。 Anthropic 开源仓库里 example 类技能是 Apache 2.0，docx/pdf/pptx 文档类技能仅 source-available，商用需逐一核对授权。第三方技能安装前审计 scripts/ 里的依赖与外呼行为，按最小权限给凭据。
常见问题（FAQ）
Q1：Skill 和 Tool 有什么区别？
Tool 是 JSON Schema 函数接口；Skill 封装领域知识、脚本与资源，教 Agent 怎么用好工具。
Q2：SKILL.md 写多长合适？
正文 500 行以内、约 5000 token 以内，超出就拆到 references/ 按需加载。
Q3：技能越多人越强吗？
不是。每个技能描述都占上下文，低触发率的技能是纯成本，应定期下线。
