HumanLayer Skills 深度指南：references 目录如何组织技能参考资料
【免费下载链接】skills项目地址: https://gitcode.com/GitHub_Trending/skills53/skills
HumanLayer Skills 是一个 Claude Code 技能包仓库（skills53/skills），收录了 improve-claude-md、design-control-loop 等可直接安装的 AI 编程代理技能。本文将拆解其中被公认设计最规范的design-control-loop技能，带你快速看懂 references 目录的组织方式，帮你轻松写出结构清晰的技能。
先认识项目：一个技能由什么组成
每个技能都遵循统一的目录结构：一个SKILL.md主文件 + 一个references/参考资料目录。
以本仓库 README.md 中列出的四个技能为例：
| 技能 | 作用 | references 目录 |
|---|---|---|
| improve-claude-md | 用<important if>块重写 CLAUDE.md | 无 |
| narrow-react-prop-types | 收窄 React 组件 props 类型 | 有 |
| design-control-loop | 设计并构建智能体控制回路 | 有（10 个文件） |
| show-me | 用图表可视化解释当前话题 | 无 |
规律很清晰：技能越复杂，references 目录越丰富。简单技能（如 improve-claude-md）把所有指令写在一个 SKILL.md 里就够了；复杂技能则把长模板和示例拆进 references，主文件只留"骨架"。
核心理念：渐进式披露，主文件保持精简
references 目录背后的设计原则是渐进式披露（progressive disclosure）：
- SKILL.md：只写有序的工作步骤、核心规则、可检查的完成标准；
- references/：放长模板、完整示例、可运行的代码片段——代理走到对应阶段时才读取。
design-control-loop 的 SKILL.md 中明确写道："把有序行为写成带完成标准的步骤，长的模板和示例移到同级 reference 文件"。这样主文件保持几百行以内，不会撑爆上下文窗口。
案例解剖：design-control-loop 的 10 个参考文件
references/ 目录下共 10 个文件，按职责可分为四类：
1️⃣ 概念教学类
- control-loop-taxonomy.md — 控制回路术语表（设定值/传感器/控制器/执行器/扰动），用于教用户理解概念
- example-control-loop.md — 一个完整走通的示例回路，"是说明，不是模板"
2️⃣ 可复用模板类
- skill-template.md — 生成新技能时的骨架（含 Core Requirements、Workflow、Review Checklist 标准结构）
- workflow-template.yml — CI 定时工作流的骨架
- prompt-template.md — 嵌入 CI 的提示词结构
- memory-template.md — 跨运行记忆文件的骨架
- response-template.md — 代理最终输出的 PR 正文格式
3️⃣ 完整示例类
- example-skill.md — 一个格式规范的成品技能示例
- agent-runner-templates.md — 各编码代理（Claude Code、Codex 等）的无头命令与密钥配置
4️⃣ 可安装代码类
- agent-iteration.ts — 支持
/iterate交互的辅助脚本，直接放进目标仓库即可用
精华技巧：按工作阶段"点名"引用
这个技能最巧妙的一点：每个工作阶段开头都写明该读哪些 references。例如：
- Phase B（设计回路）→ 读 taxonomy、示例、runner 模板
- Phase C（构建执行器技能）→ 读 skill-template、example-skill、response-template
- Phase E（接入 CI）→ 读 workflow-template.yml、prompt-template
这种"到点才读"的方式避免了代理一次性吞下全部资料。SKILL.md 末尾 还附了一份完整索引，每个文件用一句话说明"是什么、何时读"——相当于一张自文档化的地图。
对比：narrow-react-prop-types 的精简版做法
该技能的 references 只有 3 个文件，体现了"按需拆分"的克制：
- agent-narrow-component-props.yml — 示例 CI 工作流
- narrow-component-props-memory.md — 示例记忆文件
- response-template.md — PR 正文模板（含 Summary、Changes Made 表格、Risk Assessment 等固定结构）
主 SKILL.md 则完整保留 11 步工作流和 180 行的核心规则——因为它本身就是需要逐步执行的"流程型"技能。
给你的实践清单 ✍️
- 主文件只放步骤和判据：每个步骤配一条可观测的"完成标准"（参考 skill-template.md 的结构）
- 长内容外置：模板、示例、CI 配置一律进 references/，文件名用"类型-用途"命名（如
memory-template.md） - 按阶段点名引用：在工作流的相应步骤写明"Read: references/xxx"，避免全量加载
- 模板与示例分开：
*-template.md是可填充的骨架，example-*.md是填好的成品，两者各司其职 - 只保留单一事实源：同一条规则不要同时写在技能、提示词和记忆文件里
掌握了这套 references 组织法，你写出的技能会像 HumanLayer 的官方技能一样：主文件清爽、资料可检索、代理执行时"随用随取"。
【免费下载链接】skills项目地址: https://gitcode.com/GitHub_Trending/skills53/skills
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
