skill规范详解（8）— references目录

存放按需加载的详细参考文档。当Agent在执行过程中需要查阅专业知识时，才去读取这些文件，而不是在激活Skill时一次性全部加载。

SKILL.md正文有500行/5000tokens的软限制。如果把所有参考资料都塞进正文，会导致：

references/通过渐进式披露解决了这个问题——正文只放核心流程和索引，详细文档按需读取。

规范一：文件名语义清晰

references/
├── api-errors.md            # 清晰
├── expense-policy-2026.md   # 清晰
├── doc1.md                  # 无意义
├── misc.md                  # 含糊

规范二：在正文中建立索引
SKILL.md正文中必须明确告诉Agent"什么时候去读哪个文件"：

## 参考资料
- 完整的API错误码说明，请阅读references/api-errors.md
- 费用报销政策详情，请阅读references/expense-policy-2026.md
- 数据库表结构定义，请阅读references/schema.md

规范三：单文件聚焦单一主题
每个参考文件只覆盖一个主题，方便Agent按需精准加载，而不是读一个巨大的文件：

# ✅ 按主题拆分
references/
├── api-errors.md
├── api-auth.md
├── api-rate-limits.md

# ❌ 全部塞进一个文件
references/
└── api-docs.md    # 500行，包含错误码、认证、限流...

iShane.cn