Claude Agent Skills 的四种设计模式；从渐进式披露到最小权限

一、地基:为什么 Skill 需要"设计模式"

Agent Skill 的本质,是一个包含指令、脚本与资源的文件夹,让 agent 能够更准确、更高效地完成某类专业工作。它最简的形态只是一个 SKILL.md,靠 YAML frontmatter 里的 name 和 description 被发现和触发。

真正让 Skill 可扩展的,是 Anthropic 反复强调的唯一核心原则——渐进式披露(Progressive Disclosure)。它把信息分成三层,按需加载:

渐进式披露解决的是"上下文经济"问题。但一个成熟 Skill 面对的风险远不止上下文膨胀,还有:输出格式漂移、模型算错数、权限越界。于是社区在这条地基之上,沉淀出四种设计模式——它们彼此正交,每一种约束一个独立的风险维度:

下面逐一展开。

二、模式一:模板驱动(约束"输出格式")

意图:用预定义模板严格约束输出结构,让结果可预期、可对比、可自动化后处理。

适用:周报、事故复盘、代码审查报告、合规检查单——任何"格式必须统一、下游还要机器解析"的场景。在此模式下,Claude 的输出严格遵循模板骨架,不再自由发挥。

要点:模板本体应放进引用文件或 assets/,SKILL.md 正文只写"何时套用 + 每个字段怎么填"。这样既约束了格式,又不让整段模板挤占正文的 token 预算——它天然与"知识分层"复用同一套机制。

实战示例:事故复盘报告生成器

场景:SRE 团队每次线上事故后产出结构一致的复盘文档,便于归档、检索、季度汇总。

incident-postmortem/├── SKILL.md├── assets/│ └── template.md└── reference/└── severity.md

SKILL.md

---name: incident-postmortemdescription: 线上事故复盘报告生成。当用户提供事故时间线、影响范围,或要求撰写 postmortem / 事故报告 / 复盘时使用。---# 事故复盘报告生成## 何时使用用户描述了一次线上事故并需要产出正式复盘文档时。## 步骤1. 读取 `assets/template.md` 作为唯一输出骨架,**不得增删任何一级标题**。2. 若用户未提供严重等级,依据 `reference/severity.md` 判定,并在报告中注明判定依据。3. 按下列规则填写: - **影响范围**:必须量化(受影响用户数 / 请求数 / 时长);无数据写"待补充",禁止编造。 - **时间线**:`HH:MM` 单调递增,每行一个事件。 - **改进项**:每条含负责人占位 `@owner` 与截止日期 `YYYY-MM-DD`,便于下游脚本抽取建单。4. 输出纯 Markdown,不要整体包进代码块。## 硬约束- 不臆测未提供的数字。- 一级标题顺序与模板完全一致(看板按标题解析)。

assets/template.md

# 事故复盘:<一句话标题>## 元信息- 事故编号:INC-- 严重等级:- 发生时间:- 恢复时间:- 总时长:## 影响范围## 时间线## 根因分析### 直接原因### 根本原因## 处置与恢复## 改进项| 措施 | 负责人 | 截止日期 | 状态 || ---- | ------ | -------- | ---- |## 经验教训

reference/severity.md

# 严重等级判定| 等级 | 判定标准 || ---- | -------- || P0 | 核心功能全站不可用,或数据丢失/泄露 || P1 | 核心功能部分不可用,影响 >10% 用户 || P2 | 非核心功能不可用,或有降级方案 || P3 | 轻微影响,无用户可感知中断 |判定就高不就低:同时命中多个等级时取最严重者。

三、模式二:脚本增强(约束"计算可靠性")

意图:把确定性计算逻辑封装成脚本,由 Claude 调用执行,而不是用自然语言推导。

适用:财务计算、正则匹配、数据清洗与格式转换、批量文件操作。相较大模型推理,脚本执行更精准、更省 token、可复现、可测试。

一条黄金法则(源自官方 Skill authoring best practices):

实战示例:SLA 可用性计算器

场景:从停机记录 CSV 精确计算月度可用性、累计停机时长、错误预算消耗。数字必须精确,绝不让模型估算。

sla-calculator/├── SKILL.md└── scripts/└── sla.py

SKILL.md

---name: sla-calculatordescription: 根据事故记录计算 SLA 可用性、停机时长与错误预算。当用户提供停机 CSV,或询问月度可用性、错误预算是否耗尽时使用。allowed-tools: Bash(python3 *), Read---# SLA 可用性计算## 关键原则**所有数值计算必须调用脚本完成,禁止在对话中心算。**## 步骤1. 确认停机记录为 CSV,列:`start,end`(ISO8601)。2. 执行: `python3 scripts/sla.py --file <路径> --target 99.9 --month 2026-07`3. 将脚本输出的 JSON 转述为结论,并明确指出错误预算是否已耗尽。4. **不要修改脚本输出的任何数字。**

scripts/sla.py

#!/usr/bin/env python3"""从停机记录计算月度可用性与错误预算。计算集中于此以保证可复现。"""import argparse, csv, json, calendarfrom datetime import datetimedef parse(ts):return datetime.fromisoformat(ts.replace("Z", "+00:00"))def month_seconds(month):year, mon = map(int, month.split("-"))return calendar.monthrange(year, mon)[1] * 24 * 3600def main():p = argparse.ArgumentParser()p.add_argument("--file", required=True)p.add_argument("--target", type=float, required=True)# SLA 目标 %,如 99.9p.add_argument("--month", required=True)# YYYY-MMa = p.parse_args()total = month_seconds(a.month)down = 0with open(a.file, newline="", encoding="utf-8") as f:for row in csv.DictReader(f):down += (parse(row["end"]) - parse(row["start"])).total_seconds()uptime = (total - down) / total * 100allowed = total * (100 - a.target) / 100# 允许停机秒数budget_used = down / allowed * 100 if allowed else 0print(json.dumps({"month": a.month,"uptime_pct": round(uptime, 4),"target_pct": a.target,"downtime_seconds": int(down),"downtime_human": f"{int(down)//3600}h{int(down)%3600//60}m","error_budget_used_pct": round(budget_used, 2),"budget_exhausted": budget_used >= 100,"meets_sla": uptime >= a.target,}, ensure_ascii=False, indent=2))if __name__ == "__main__":main()

体会一下黄金法则的价值:uptime、error budget 这类公式一旦出现在正文里让 Claude 心算,结果就不可复现、还费 token;搬进 sla.py 后,它变成一次确定性的工具调用。脚本还能通过 allowed-tools: Bash(python3 *) 把执行面收窄到"只能跑 Python"——这正好引出下一个模式。

四、模式三:知识分层(约束"上下文经济")

意图:按使用频率组织知识,是渐进式披露的模式化表达。

遵循 80/20 法则——80% 的请求只需要 20% 的核心知识。于是:

• 高频核心内联进 SKILL.md;
• 低频细节(完整 API 参考、边缘案例、长表单说明)拆到引用文件,用一句话说明"什么情况下去读它"。

一个常被忽略的第二维度:除了频率,还要看互斥性。官方建议把"mutually exclusive or rarely used"的上下文拆到不同文件——否则 Claude 会同时载入相互冲突的指令。分层不只是为了省 token,也是为了避免指令打架。

实战示例:REST API 设计规范

场景:统一团队 API 风格。90% 的问题只涉及命名/状态码/版本(内联);分页、错误体、鉴权是低频且互斥的细节(外置)。

rest-api-guide/├── SKILL.md└── reference/├── pagination.md├── errors.md└── auth.md

SKILL.md(内联 20% 核心)

---name: rest-api-guidedescription: 团队 REST API 设计规范。设计/评审 HTTP 接口、命名端点、选状态码,或问及 API 版本、分页、错误格式、鉴权时使用。---# REST API 设计规范## 核心规则(高频,直接遵循)- **资源命名**:复数名词 + kebab-case,如 `/user-groups`;不出现动词。- **层级**:`/orders/{id}/items`,嵌套不超过两层。- **方法语义**:GET 只读且幂等;POST 创建;PUT 全量替换;PATCH 局部更新;DELETE 删除。- **状态码**:200/201/204 · 400/401/403/404/409/422 · 500。- **版本**:URL 前缀 `/v1/`,仅破坏性变更升版本。## 何时查阅引用文件(低频,按需加载)- 设计**分页 / 游标** → 读 `reference/pagination.md`- 定义**错误响应体** → 读 `reference/errors.md`- 涉及**鉴权 / Token / 权限** → 读 `reference/auth.md`> 这三个主题互斥且少同时出现,故不内联——既省 token,也避免规则相互干扰。

reference/errors.md

# 错误响应体规范统一使用 RFC 9457 (Problem Details):```json{"type": "https://api.example.com/errors/out-of-stock","title": "库存不足","status": 409,"detail": "商品 SKU-123 当前库存为 0","instance": "/orders/8821"}```- `type` 为可跳转错误文档 URL;无专属文档时用 `about:blank`。- 校验错误(422)追加 `errors` 数组,每项含 `field` 与 `message`。- 绝不在 `detail` 泄露堆栈、SQL 或内部主机名。

reference/pagination.md

# 分页规范默认游标分页,大数据集禁用 offset。请求:`GET /orders?limit=50&cursor=eyJpZCI6MTAwfQ````json{"data": [ ... ],"page": { "next_cursor": "eyJpZCI6MTUwfQ", "has_more": true }}```- `limit` 默认 50,上限 200,越界返回 400。- `next_cursor` 为空表示已到末页。

reference/auth.md

# 鉴权规范- 传输:仅 HTTPS;Token 放 `Authorization: Bearer `。- 过期:access token ≤ 15min,配合 refresh token。- 401 = 未认证 / Token 失效;403 = 已认证但无权限。二者不可混用。

五、模式四:工具隔离(约束"权限安全")

意图:通过 allowed-tools 明确界定 Skill 的能力边界。它属于安全设计,核心价值在于声明"禁止做什么"——这往往比定义"能做什么"更关键。

典型的最小权限实践:审计类 Skill 不给写权限,生成类 Skill 不给修改权限。

实战示例:只读安全审计

场景:上线前跑一遍安全体检,只报告不改动,防止 agent 顺手"帮忙修复"反而引入风险。

security-audit/├── SKILL.md└── reference/└── checklist.md

SKILL.md

---name: security-auditdescription: 只读代码库安全审计。当用户要求安全体检、扫描硬编码密钥、检查危险调用或上线前安全审查时使用。allowed-tools: Read, Grep, Glob---# 只读安全审计## 能力边界(重要)本 Skill **只读**。frontmatter 未授予任何写入/执行工具:- 只发现、只报告,**绝不修改文件**。- 如需修复,输出建议交由人工或另一个具备写权限的流程处理。## 步骤1. 依据 `reference/checklist.md` 逐项用 Grep / Glob 扫描。2. 每条发现给出:`文件:行号`、风险等级、证据片段、修复建议。3. 输出风险清单表,按严重度降序;无发现则明确写"未发现"。## CLI 与 SDK 边界提示`allowed-tools` 仅在 Claude Code CLI 生效。若本 Skill 经 Agent SDK 调用,只读约束不由 frontmatter 强制,须在 agent 的 tools 白名单或权限系统中另行限定。

reference/checklist.md

# 安全审计清单## 密钥与凭证- 硬编码密钥:形如 `key/secret/password/token = "<长字符串>"` 的赋值- 私钥文件头:出现 PRIVATE KEY 文件头- 云访问密钥:符合各云厂商 Access Key 格式的字符串## 危险调用- 命令注入:拼接用户输入调用系统命令 / 开启 shell 执行- 不安全反序列化:对不可信数据做反序列化- SQL 拼接:用字符串拼接构造 SQL 而非参数化查询## 配置- 生产开调试:生产配置中调试开关为开- 过宽 CORS:允许来源为通配符## 风险等级Critical=可直接远程利用 · High=需前置条件 · Medium=纵深防御问题 · Low=最佳实践偏差

六、组合与取舍:先识别最大的风险维度

这四种模式正交、可叠加。上面四个示例分别把格式、计算、上下文、权限四类不确定性,外移到了模板 / 脚本 / 引用文件 / 工具白名单。一个成熟 Skill 往往是四者的组合:

但真正的设计判断,不是"全都用上",而是先识别这个任务里最大的风险维度,再优先套对应模式:

七、结语

渐进式披露是地基,四种模式是建在其上的承重墙——分别扛住格式、计算、上下文、权限四类载荷。

写 Skill 的成熟标志,不是把 SKILL.md 写得更长、更全,而是学会用最小的正文,把不确定性外移:格式外移给模板,计算外移给脚本,细节外移给引用文件,权限外移给工具白名单。留在正文里的,只剩下那句最关键的——"什么时候,该做什么"。