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

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

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

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

层级	内容	加载时机	体量建议
① 元数据	`name` + `description`	启动时全部载入,用于判断"何时该用"	~100 tokens
② 正文	`SKILL.md` 主体指令	任务命中 description 时才读入	< 5,000 tokens
③ 资源	`reference.md`、脚本、模板...	正文指示时才按需读取 / 执行	无限制

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

设计模式	约束的维度	核心手段
模板驱动	输出格式	预定义模板严格约束结构
脚本增强	计算可靠性	确定性逻辑封装为脚本
知识分层	上下文经济	按频率与互斥性分层加载
工具隔离	权限安全	`allowed-tools` 声明能力边界

下面逐一展开。

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

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

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

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

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

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

arduino 复制代码

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

SKILL.md

markdown 复制代码

---
name: incident-postmortem
description: 线上事故复盘报告生成。当用户提供事故时间线、影响范围,或要求撰写 postmortem / 事故报告 / 复盘时使用。
---

# 事故复盘报告生成

## 何时使用
用户描述了一次线上事故并需要产出正式复盘文档时。

## 步骤
1. 读取 `assets/template.md` 作为唯一输出骨架,**不得增删任何一级标题**。
2. 若用户未提供严重等级,依据 `reference/severity.md` 判定,并在报告中注明判定依据。
3. 按下列规则填写:
   - **影响范围**:必须量化(受影响用户数 / 请求数 / 时长);无数据写"待补充",禁止编造。
   - **时间线**:`HH:MM` 单调递增,每行一个事件。
   - **改进项**:每条含负责人占位 `@owner` 与截止日期 `YYYY-MM-DD`,便于下游脚本抽取建单。
4. 输出纯 Markdown,不要整体包进代码块。

## 硬约束
- 不臆测未提供的数字。
- 一级标题顺序与模板完全一致(看板按标题解析)。

assets/template.md

markdown 复制代码

# 事故复盘:<一句话标题>

## 元信息
- 事故编号:INC-
- 严重等级:
- 发生时间:
- 恢复时间:
- 总时长:

## 影响范围

## 时间线

## 根因分析
### 直接原因
### 根本原因

## 处置与恢复

## 改进项
| 措施 | 负责人 | 截止日期 | 状态 |
| ---- | ------ | -------- | ---- |

## 经验教训

reference/severity.md

markdown 复制代码

# 严重等级判定

| 等级 | 判定标准 |
| ---- | -------- |
| P0 | 核心功能全站不可用,或数据丢失/泄露 |
| P1 | 核心功能部分不可用,影响 >10% 用户 |
| P2 | 非核心功能不可用,或有降级方案 |
| P3 | 轻微影响,无用户可感知中断 |

判定就高不就低:同时命中多个等级时取最严重者。

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

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

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

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

如果你发现自己正在 SKILL.md 里写公式、让 Claude 去"心算"------立刻停下,这段逻辑应当被搬进脚本。

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

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

markdown 复制代码

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

SKILL.md

markdown 复制代码

---
name: sla-calculator
description: 根据事故记录计算 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

python 复制代码

#!/usr/bin/env python3
"""从停机记录计算月度可用性与错误预算。计算集中于此以保证可复现。"""
import argparse, csv, json, calendar
from datetime import datetime

def 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 * 3600

def main():
    p = argparse.ArgumentParser()
    p.add_argument("--file", required=True)
    p.add_argument("--target", type=float, required=True)  # SLA 目标 %,如 99.9
    p.add_argument("--month", required=True)                # YYYY-MM
    a = p.parse_args()

    total = month_seconds(a.month)
    down = 0
    with 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 * 100
    allowed = total * (100 - a.target) / 100          # 允许停机秒数
    budget_used = down / allowed * 100 if allowed else 0

    print(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% 的问题只涉及命名/状态码/版本(内联);分页、错误体、鉴权是低频且互斥的细节(外置)。

css 复制代码

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

SKILL.md(内联 20% 核心)

markdown 复制代码

---
name: rest-api-guide
description: 团队 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

markdown 复制代码

# 错误响应体规范

统一使用 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

markdown 复制代码

# 分页规范

默认游标分页,大数据集禁用 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

markdown 复制代码

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

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

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

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

⚠️ 一个必须知道的边界 :allowed-tools 这个 frontmatter 字段只在 Claude Code CLI 下生效,通过 Agent SDK 使用 Skill 时不生效 。因此不能只靠 skill 的 allowed-tools 当安全边界 ------在 SDK / 生产 agent 场景,真正的权限边界必须落在 agent 的 tools 白名单、permission 系统或 hooks 上。skill frontmatter 更像"约定 + CLI 层加固",不是不可绕过的沙箱。

实战示例:只读安全审计

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

markdown 复制代码

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

SKILL.md

markdown 复制代码

---
name: security-audit
description: 只读代码库安全审计。当用户要求安全体检、扫描硬编码密钥、检查危险调用或上线前安全审查时使用。
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

markdown 复制代码

# 安全审计清单

## 密钥与凭证
- 硬编码密钥:形如 `key/secret/password/token = "<长字符串>"` 的赋值
- 私钥文件头:出现 PRIVATE KEY 文件头
- 云访问密钥:符合各云厂商 Access Key 格式的字符串

## 危险调用
- 命令注入:拼接用户输入调用系统命令 / 开启 shell 执行
- 不安全反序列化:对不可信数据做反序列化
- SQL 拼接:用字符串拼接构造 SQL 而非参数化查询

## 配置
- 生产开调试:生产配置中调试开关为开
- 过宽 CORS:允许来源为通配符

## 风险等级
Critical=可直接远程利用 · High=需前置条件 · Medium=纵深防御问题 · Low=最佳实践偏差

上表为起点清单,落地时请配合具体扫描规则,并按实际技术栈裁剪。

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

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

分层组织正文 + 引用模板 + 关键计算走脚本 + 收紧工具权限

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

你最担心的问题	优先采用	关键动作
输出格式会漂移	模板驱动	模板外置,正文只写填写规则
模型会算错	脚本增强	公式一律搬进脚本
上下文会爆 / 指令会打架	知识分层	按频率 + 互斥性拆文件
会越权操作	工具隔离	最小权限;SDK 场景另设边界

七、结语

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

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