这个机制为什么重要

按 Anthropic Skills 文档(访问于 2026-05-19),Claude 上下文窗口是有限的(Opus 4.7 也才 200k),如果你给 Claude Code 装 12 个 Skill,每个 Skill 平均 5k token,光 Skills 就吃掉 60k 上下文——还没开始写代码就已经占了 30% 窗口。

渐进式披露解决这个问题:Skills 平时只暴露轻量 metadata,Claude 模型基于 metadata 判断要不要激活、激活哪一个。

三层结构详解

第一层:metadata(始终在上下文)

---
name: stripe-integration
description: Stripe webhook 接入、签名验证、订阅状态同步。用户提 Stripe / 订阅 / 支付失败 / webhook 时触发。不处理 PayPal / Paddle。
---

通常 30-80 token。description 是模型判断是否触发的唯一依据,要写清楚什么时候用、什么时候不用。

第二层:SKILL.md 主体(触发时加载)

通常 200-600 token。只放「触发后 Claude 立刻需要的少量信息」+ 路由表,具体参考资料引用 resources 文件。

第三层:resources(按需读)

每个 resource 文件 800-3000 token。Claude 通过 Read 工具按需加载,一次会话经常只读 1-2 个,平均省 70-80% token。

实测对比:12 个 Skill 项目

我有一个 indie hacker SaaS 项目,装了 12 个常用 Skill:

加载方式基线上下文单 Skill 触发峰值
全部一次性加载(伪 Skills)≈ 60k token60k(不变)
渐进式披露三层结构≈ 800 token3-5k
节省98.7%92%

按 Anthropic Pricing(访问于 2026-05-19)算,每次会话省 55k input token ≈ ¥0.7,日均 30 次会话 ≈ 月省 ¥600。一年 ¥7000+,够付半年中转套餐。

完整示例:stripe-integration Skill

.claude/skills/stripe-integration/
  SKILL.md
  resources/
    webhook-setup.md     (1500 token)
    webhook-verify.py    (800 token)
    subscription-sync.md (2000 token)
    troubleshooting.md   (3000 token)

SKILL.md 关键片段:

---
name: stripe-integration
description: Stripe webhook 接入 + 签名验证 + 订阅同步。用户提 Stripe / 订阅 / 支付失败 / webhook 触发。不处理 PayPal / Paddle。
---

# Stripe Integration Skill

你是 Stripe 集成专家。
- 「接 webhook」→ Read resources/webhook-setup.md
- 「签名验证」→ Read resources/webhook-verify.py
- 「订阅同步」→ Read resources/subscription-sync.md
- 「webhook 报错」→ Read resources/troubleshooting.md

永远验证签名、重试 idempotent、secret_key 不暴露前端。

整个 SKILL.md ≈ 250 token。description 必须显式写「触发关键词 + 不做什么」,Claude 才能准确路由,避免误触发。

跨地区使用 / 切换设备

Skills 文件夹 commit 到 git 后,新设备 clone 完直接生效。但你需要确保新设备能稳定访问 Anthropic API——~/.zshrc 里同样的 ANTHROPIC_BASE_URL 与 ANTHROPIC_API_KEY。

出差或海外切换时,选一条独立开发者用得起的 Claude 4.7 / GPT-5.5 中转作为统一入口,Skills 加载与按需 Read resources 都走同一条线路,不用为不同环境维护多套 baseURL。

常见失败原因

  • description 太泛:「处理支付相关问题」→ Claude 啥都触发它,误触率高
  • SKILL.md 太厚:把所有 resources 塞进 SKILL.md,失去渐进式披露的意义
  • resources 命名混乱:a.md / b.md 这种文件名很难判断用途,应该用语义化文件名
  • 没装 Read / Glob 工具:Skill 想读 resources 但工具白名单没给,触发后跑不通
  • 过度拆分:把 10 token 的小提示也拆成独立文件,反而增加 Read 次数

月预算样例

按上面 12 个 Skill 项目,日均 30 次 Claude Code 会话:

项改造前改造后
Skills 平均上下文60k token/次800 token/次(峰值 5k)
日 input token 浪费1.8M24k
月 input token 浪费54M720k
月成本(中转 Sonnet 4.6)≈ ¥720≈ ¥10

省下来的 ¥700/月,够多付半年中转套餐,或者你的 Claude Pro / Cursor Pro 订阅。

关联文章