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

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

Agent Skill 的本质,是一个包含

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

真正让 Skill 可扩展的,是 Anthropic 反复强调的唯一核心原则——

。它把信息分成三层,按需加载:

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

。但一个成熟 Skill 面对的风险远不止上下文膨胀,还有:

输出格式漂移、模型算错数、权限越界

。于是社区在这条地基之上,沉淀出四种设计模式——它们:

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

下面逐一展开。

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

:用预定义模板严格约束输出结构,让结果。

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

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

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

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

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

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

# 事故复盘报告生成

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

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

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

# 事故复盘:一句话标题

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

## 影响范围

## 时间线

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

## 处置与恢复

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

## 经验教训

# 严重等级判定

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

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

小提示

:将模板文件置于 assets/ 目录下是一种良好的实践,它不仅能保持 SKILL.md 的简洁,还能让模板本身独立迭代。当团队需要调整报表格式时,只需修改模板文件,而无需改动 Skill 的核心指令。

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

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

:财务计算、正则匹配、数据清洗与格式转换、批量文件操作。相较大模型推理,脚本执行。

(源自官方 Skill authoring best practices):

如果你发现自己正在 SKILL.md 里写公式、让 Claude 去"心算"——

立刻停下

,这段逻辑应当被搬进脚本。

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

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

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

---
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. **不要修改脚本输出的任何数字。**

#!/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"——这正好引出下一个模式。

小提示

:脚本编写时,建议使用 argparse 处理命令行参数,并确保输出为结构化的 JSON 格式。这样,Claude 可以轻松解析结果,并直接将其整合到最终的回答中,避免了额外的文本解析步骤。

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

:按组织知识,是渐进式披露的模式化表达。

遵循

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

(内联 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,也避免规则相互干扰。

# 错误响应体规范

统一使用 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 或内部主机名。

# 分页规范

默认游标分页,大数据集禁用 offset。

请求:`GET /orders?limit=50&cursor=eyJpZCI6MTAwfQ`

```json
{
  "data": [ ... ],
  "page": { "next_cursor": "eyJpZCI6MTUwfQ", "has_more": true }
}
```

- `limit` 默认 50,上限 200,越界返回 400。
- `next_cursor` 为空表示已到末页。

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

小提示

:在 SKILL.md 中,使用一种清晰、一致的方式(如"何时查阅引用文件"部分)引导 Claude 去读取外部文件。这比在正文中嵌入冗长的条件判断要高效得多,也更容易维护。

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

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

典型的最小权限实践:

。

:allowed-tools 这个 frontmatter 字段。因此——在 SDK / 生产 agent 场景,真正的权限边界必须落在 agent 的 tools 白名单、permission 系统或 hooks 上。skill frontmatter 更像"约定 + CLI 层加固",不是不可绕过的沙箱。

实战示例:只读安全审计

:上线前跑一遍安全体检,,防止 agent 顺手"帮忙修复"反而引入风险。

security-audit/
├── SKILL.md
└── reference/
    └── checklist.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 白名单或权限系统中另行限定。

# 安全审计清单

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

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

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

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

上表为

起点清单

,落地时请配合具体扫描规则,并按实际技术栈裁剪。

小提示

:在 description 中明确声明 "只读" 属性,既是对用户意图的清晰传达,也能帮助 Claude 在任务选择阶段就做出正确判断。这是安全实践中的第一道防线。

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

这四种模式

。上面四个示例分别把四类不确定性,外移到了模板 / 脚本 / 引用文件 / 工具白名单。一个成熟 Skill 往往是四者的组合:

分层组织正文

+

引用模板

+

关键计算走脚本

+

收紧工具权限

但真正的设计判断,不是"全都用上",而是

:

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

七、常见问题

问题 1: 我应该如何选择使用哪种设计模式?

: 这取决于你的 Skill 面临的最大风险。请参考上文的"组合与取舍"章节。首先,评估你的 Skill 最可能失败的地方:如果输出格式不一致,优先考虑模板驱动;如果计算容易出错,优先考虑脚本增强;如果上下文过长,优先考虑知识分层;如果涉及敏感操作,优先考虑工具隔离。一个 Skill 可以同时应用多种模式,但不要过度设计。

问题 2: 我可以向一个 Skill 应用多种设计模式吗?

: 当然可以。这些模式是正交且可叠加的。例如,一个成熟的 Skill 可以同时使用知识分层来组织内容,引用模板来约束输出,通过脚本增强来进行关键计算,并使用工具隔离来限制权限。这正是构建健壮、可靠 Agent Skill 的推荐做法。

问题 3: 在 Agent SDK 环境下,allowed-tools 不生效,我该如何确保安全?

: 这是一个非常关键的问题。在 SDK 或生产环境中,你必须在 agent 的 tools 白名单、权限系统或 hooks 中定义真正的安全边界。Skill 的 allowed-tools 更像是一个"约定"和 CLI 层加固,不应被视为不可绕过的沙箱。在 SDK 中,你需要通过代码来强制执行权限策略。

八、结语

渐进式披露是

,四种模式是建在其上的——分别扛住格式、计算、上下文、权限四类载荷。

写 Skill 的成熟标志,不是把 SKILL.md 写得更长、更全,而是学会

:格式外移给模板,计算外移给脚本,细节外移给引用文件,权限外移给工具白名单。留在正文里的,只剩下那句最关键的——。 当你掌握了这个核心思想,你就能构建出既强大又可靠的 Agent Skill。