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

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

Agent Skill说到底，就是一个装了指令、脚本和资源的文件夹。它的最简形态，甚至只是一个SKILL.md文件，靠YAML frontmatter里的name和description就能被识别和触发。但真正让Skill具备可扩展性的，是Anthropic反复强调的一个核心原则——渐进式披露。

关键就在一个原则——渐进式披露。说白了，就是把信息分成三层，按需加载：第一层是元数据，也就是name和description，启动时全部载入，用于判断"什么时候该用这个Skill"，体量很小，大约100 tokens；第二层是正文，即SKILL.md的主体指令，只在任务命中description时才被读入，建议控制在5000 tokens以内；第三层是资源，包括参考资料、脚本、模板等，只有正文指示时才按需读取或执行，体量没有限制。

这就像一个三层漏斗，只把最关键的、最常用的信息放在最前面，其他的学问都藏在后面，等着按需调用。结果就是节省了上下文预算，也降低了模型被无关信息干扰的概率。但一个成熟的Skill，面对的风险远不止上下文膨胀，还有输出格式漂移、模型算错数、权限越界。于是社区在这条地基之上，沉淀出四种设计模式。它们彼此正交，每一种约束一个独立的风险维度：

• 模板驱动
  约束输出格式，通过预定义模板严格约束结构；

• 脚本增强
  约束计算可靠性，把确定性逻辑封装成脚本；

• 知识分层
  约束上下文经济，按频率与互斥性分层加载；

• 工具隔离
  约束权限安全，通过allowed-tools声明能力边界。

下面逐一展开。

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

先用预定义模板把输出结构死死钉住，让结果可预期、可对比、可自动化后处理。适用场景非常明确：周报、事故复盘、代码审查报告、合规检查单——任何"格式必须统一、下游还要机器解析"的场景。在这种模式下，Claude的输出严格遵循模板骨架，不再自由发挥。

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

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

SRE团队每次线上事故后都需要产出结构一致的复盘文档，便于归档、检索和季度汇总。

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

SKILL.md

---
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

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

## 元信息
- 事故编号: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-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

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

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

SKILL.md（内联20%核心）

---
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

# 错误响应体规范
统一使用 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-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

# 安全审计清单

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

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

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

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

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

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

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

• 如果你最担心

  输出格式会漂移
  ，优先采用模板驱动，关键动作是把模板外置，正文只写填写规则。
• 如果担心

  模型会算错
  ，优先采用脚本增强，公式一律搬进脚本。
• 如果担心

  上下文会爆 / 指令会打架
  ，优先采用知识分层，按频率加互斥性拆文件。
• 如果担心

  会越权操作
  ，优先采用工具隔离，最小权限，SDK场景另设边界。

七、结语

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

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