Claude 终极使用指南

主题

08.4 渐进式披露与资源组织 ​

一个 Skill 的真正威力，在于它能挂载脚本、参考文档和模板，而这些平时零成本。

读完你能做什么：组织一个带支持文件的复杂 Skill，让长参考资料按需加载。

一、三层加载再回顾 ​

text
第 1 层  name + description        始终在上下文（几十 token）
第 2 层  SKILL.md 正文             被调用时加载
第 3 层  技能目录下的其他文件        Claude 需要时才读（用工具）

渐进式披露的省钱逻辑全在第 3 层：你可以在技能目录里放一份 5000 行的 API 规范、一堆脚本、多个模板 —— 它们平时完全不占上下文，只有 Claude 真正需要某一份时，才用 Read 工具把它读进来。

二、目录结构 ​

text
.claude/skills/
└── api-designer/
    ├── SKILL.md              # 入口：frontmatter + 简短指令
    ├── reference/
    │   ├── conventions.md    # API 命名规范（长）
    │   ├── error-codes.md    # 错误码表（长）
    │   └── examples.md       # 标准示例
    ├── scripts/
    │   ├── validate.sh       # 校验脚本
    │   └── gen-openapi.py     # 生成 OpenAPI
    └── templates/
        └── endpoint.md.tmpl  # 接口文档模板

SKILL.md 保持简短，把重内容放到子目录：

markdown
---
name: api-designer
description: 按本团队规范设计 REST API。当用户需要设计新接口、加 endpoint，
  或提到"设计 API""加个接口""RESTful"时使用。
---

# API 设计

## 流程
1. 先读 `reference/conventions.md` 了解命名与结构规范
2. 设计接口，用 `templates/endpoint.md.tmpl` 作为文档模板
3. 涉及错误处理时，查 `reference/error-codes.md` 选用标准错误码
4. 设计完成后，运行 `scripts/validate.sh` 校验是否符合规范

## 关键约束（这几条必须记住，不用读文件）
- 资源用复数名词：/users 而非 /user
- 版本放路径：/v1/users
- 分页用 limit + cursor，不用 offset

注意 SKILL.md 的设计：把"必须始终记住的核心约束"直接写在正文（第 2 层），把"需要时才查的详细规范"放到 reference/（第 3 层）。

三、${CLAUDE_SKILL_DIR} 变量 ​

技能里引用自己的文件时，用 ${CLAUDE_SKILL_DIR} 表示技能目录路径：

markdown
---
name: render-chart
description: 从 CSV 生成图表。当用户需要把数据可视化成图表时使用。
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/render.sh *)
---

# 图表渲染

运行 `${CLAUDE_SKILL_DIR}/scripts/render.sh <csv文件> <输出路径>` 生成图表。
脚本支持的图表类型见 `${CLAUDE_SKILL_DIR}/reference/chart-types.md`。

这样技能无论被安装到哪，路径都能正确解析。

四、脚本：把确定性逻辑固化 ​

有些逻辑不该让 Claude 每次"即兴发挥"，而应该固化成脚本。Skill 可以挂载脚本让 Claude 调用。

4.1 例子：数据校验脚本 ​

bash
#!/usr/bin/env bash
# scripts/validate.sh —— 校验 API 定义是否符合规范
set -euo pipefail

FILE="$1"
ERRORS=0

# 检查资源命名是否复数
if grep -qE '"/[a-z]+[^s]"' "$FILE"; then
  echo "❌ 发现单数资源名，应用复数"
  ERRORS=$((ERRORS+1))
fi

# 检查是否有版本前缀
if ! grep -qE '/v[0-9]+/' "$FILE"; then
  echo "❌ 缺少版本前缀 /vN/"
  ERRORS=$((ERRORS+1))
fi

[ "$ERRORS" -eq 0 ] && echo "✅ 校验通过" || exit 1

价值：校验规则是确定的，用脚本执行比让 Claude "肉眼检查"可靠得多。这呼应了本手册的核心原则 —— 能用程序判定的，就不要靠模型自觉（见 04.5 元技巧 3）。

4.2 用 allowed-tools 限定脚本 ​

markdown
---
name: db-migrate
description: ...
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/*.sh *)
---

限制这个技能只能跑自己目录下的脚本，不能执行任意命令。

五、参考文档：长知识的正确归宿 ​

5.1 为什么放第 3 层而不是正文 ​

text
一份 3000 行的 API 规范：

写进 SKILL.md 正文（第 2 层）
  → 每次技能被调用都加载全部 3000 行

放进 reference/conventions.md（第 3 层）
  → 只有 Claude 真的需要查规范时才读
  → 而且它可以只读相关的部分（用 Grep 定位）

5.2 组织参考文档 ​

text
reference/
├── conventions.md     # 一个主题一个文件
├── error-codes.md
└── examples.md

在 SKILL.md 里给出"什么时候读哪个"的指引：

markdown
## 参考资料（按需查阅）
- 命名和结构规范 → `reference/conventions.md`
- 选择错误码 → `reference/error-codes.md`
- 需要示例 → `reference/examples.md`

不要一次性读完所有参考文件，只读当前任务需要的部分。

最后那句很重要 —— 它防止 Claude 把所有第 3 层文件一股脑读进来，破坏了渐进式披露的意义。

六、模板：标准化产出 ​

模板保证 Claude 每次生成的东西格式一致：

markdown
<!-- templates/endpoint.md.tmpl -->
## {METHOD} {PATH}

{DESCRIPTION}

### 请求参数
| 参数 | 类型 | 必填 | 说明 |
| :--- | :--- | :---: | :--- |

### 响应
```json
{RESPONSE_EXAMPLE}
```

### 错误码
| 码 | 含义 |
| :--- | :--- |

SKILL.md 指示使用它：

markdown
生成接口文档时，严格套用 `templates/endpoint.md.tmpl` 的结构。

七、渐进式披露的设计原则 ​

内容类型放哪层理由
触发条件第 1 层（description）必须常驻才能触发
核心流程 + 必记约束第 2 层（正文）调用时就要知道
长参考资料第 3 层（reference/）按需读，省上下文
脚本第 3 层（scripts/）执行时才需要
模板第 3 层（templates/）生成时才读

7.1 一条黄金法则 ​

SKILL.md 正文应该像一份"目录 + 核心要点"，而不是"完整手册"。 完整内容放第 3 层，正文告诉 Claude"什么时候去查哪一份"。

八、控制第 3 层的读取 ​

渐进式披露的风险是 Claude 可能"过度读取" —— 把所有支持文件都读进来，反而失去了省上下文的意义。

在 SKILL.md 里明确约束：

markdown
## 读取原则
- 只读当前任务直接需要的参考文件
- 参考文件很长时，用 Grep 定位相关章节再读，不要整篇读
- 校验/生成类脚本直接运行，不要读脚本源码

九、一个完整的资源型 Skill ​

「按团队规范写数据库迁移」：

text
.claude/skills/db-migrate/
├── SKILL.md
├── reference/
│   ├── migration-rules.md      # 迁移规范（向后兼容、可回滚、分批）
│   └── common-pitfalls.md      # 常见坑
├── scripts/
│   ├── check-reversible.sh     # 检查迁移是否可回滚
│   └── estimate-lock-time.sh   # 估算锁表时间
└── templates/
    └── migration.sql.tmpl
markdown
---
name: db-migrate
description: 按团队规范编写数据库迁移。当用户需要改表结构、加字段、建索引、
  写 migration，或提到"改数据库""加字段""迁移脚本"时使用。
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/*.sh *) Read Edit Write
---

# 数据库迁移

## 必守的三条（始终记住）
1. 向后兼容：新旧代码要能同时跑（先加列不删列，分两次发布）
2. 可回滚：每个迁移必须有对应的 down
3. 大表分批：避免长时间锁表

## 流程
1. 用 `templates/migration.sql.tmpl` 起草
2. 详细规范查 `reference/migration-rules.md`
3. 起草后运行 `scripts/check-reversible.sh` 确认可回滚
4. 涉及大表运行 `scripts/estimate-lock-time.sh` 评估锁表时间
5. 常见坑对照 `reference/common-pitfalls.md`

## 读取原则
只读当前迁移涉及的部分，不要整篇读参考文件。

三条核心约束在正文（一定记住），详细规范和脚本在第 3 层（按需用）。

延伸阅读 ​

基于 VitePress 构建 · 内容采用原作者授权

© 2026 星创数学 XCMath