humanlayer/skills 怎么用

0030 秒速览：这 5 个东西能替你干什么

读完这一篇，你能做出三个判断：这 5 个技能里哪几个值得你装、它们各自在治哪一种毛病、以及为什么整仓 15 万个安装里有八成集中在最短的那一个文件上。这篇讲的是一整套技能包怎么用（含 5 个文件逐个拆解），不是某一个技能的内部实现细节。

你现在的处境 → 直接用这个

一条可执行的上手路径

一组关键数字：先给量级

01这 5 个 skill 到底是什么

humanlayer/skills 是 HumanLayer 这个团队放在 GitHub 上的一个技能仓库：里面没有应用代码，只有一份"市场清单"、5 个插件目录，以及每个插件里的一份技能说明书（本文把 skill 与"技能"当同一个词用：它就是一份写给 agent 看的说明书文件）。它创建于 2026-03-18，用 MIT 许可（一种很宽松的开源授权，你可以随便改、随便商用），本文核对时 GitHub 的接口返回 3,889 stars / 114 forks（stars 是收藏数，forks 是别人把它复制到自己账号下的份数），最后一次推送是 2026-08-13。

先破掉四个错误印象

整个仓库长什么样：35 个文件、25 个目录

我用 GitHub 的文件树接口一次性取回全部条目（git/trees/main?recursive=1），数出来是 35 个文件、25 个目录。结构简单到可以背下来：

humanlayer/skills
├── .claude-plugin/marketplace.json   # 市场清单：5 个插件的入口与分类
├── README.md / LICENSE / .gitignore
└── plugins/
    ├── show-me/
    │   ├── .claude-plugin/plugin.json       # 插件元数据：名字、版本、关键词
    │   └── skills/show-me/SKILL.md          # 技能本体（唯一文件）
    ├── improve-claude-md/                   # 结构同上：2 个文件
    ├── narrow-react-prop-types/             # 2 + 3 个 references
    ├── build-iterated-agentic-loop/         # 2 + 8 个 references
    └── design-control-loop/                 # 2 + 10 个 references

这个结构里有三个设计决定值得单独说

一个容易忽略的事实

这个仓库自己既没有 CLAUDE.md 也没有 AGENTS.md（文件树里查不到），却携带一个专门帮你重写 CLAUDE.md 的技能。CLAUDE.md 和 AGENTS.md 都是"放在仓库根、给 AI 读的项目说明书"。这不矛盾——它把"仓库里的说明文件"当成用户侧的产物，而不是自己的文档。

02它解决什么问题：一个 skill 治一种毛病

这 5 个技能不是"五个功能"，而是五种具体毛病。先看它们各自的一句话，再决定要不要往下读。

五个 skill 一手对照表

砍成两类：三个"一次性动作" + 两个"造一台机器"

这五个可以再砍成两类，而这个分类直接影响你怎么读它们的说明文件：

文件体量把这件事说得很清楚

5 份 SKILL.md 合计 49,559 字节（复核：用文件树接口筛出 SKILL.md 把 size 相加）。整个仓库的知识密度集中在不到 5 万字节的说明里，剩下的全是给生成物用的模板。

这些技能能替你省下的到底是什么

把它们翻译成"没有它你会怎样"，会更清楚：

• 没有 show-me：你得到三段散文 + 一个 60 行的完整文件引用 + "总结一下，主要有以下几点"。读者要在文字里自己重建结构，而往往真正想问的只有"这个函数在第几步被调用"。
• 没有 improve-claude-md：你的项目说明书继续被一句"这份上下文可能与你的任务相关，也可能不相关"的框架包着，文件里越杂，模型越可能连相关的那部分一起忽略。
• 没有 narrow-react-prop-types：类型系统（在代码运行之前就用"类型"检查它的一层机制）继续允许那些应用真实路径永远不会进入的状态——每一个可选 prop 都是组件必须处理的一个额外分支。
• 没有两个循环技能：重复任务继续靠你手动想起来、手动跑、手动开 PR；而它们要解决的是"在你没盯着的时候也往前走"。

03什么场景该用、什么场景别装

先把结论说了：这 5 个技能里，只有 2 个值得大多数人装——show-me 和 improve-claude-md；另外 3 个是给特定处境的人准备的。下面这张表按"你的处境"来分，比按技能名分好查。

按处境选：四种典型场景

也要说实话：它不适合谁

• 不用 Claude Code 的人，只剩一半功能。show-me 的收尾动作写成 Bash(open …)，那是 Claude Code 的工具调用记法；换到别的 agent 框架你得自己翻译（见 07）。plugin.json／marketplace.json 那套也只为 Claude Code 插件市场服务。
• 想要"一套完整方法论"的人会失望。这里没有编排、没有阶段门、没有进度账本。它更像 5 把独立的工具，不是一条流水线。
• 没有 CI（持续集成，代码一推就自动跑检查的那套东西）、不想让 agent 开 PR 的人，别碰后两个。它们会往你的仓库里写 GitHub Actions、要求配置密钥、并使用绕过权限的 agent 模式。装完不配，只会得到一排红色的失败记录。
• 只想要"生成一篇学习文章"的人应该用别的东西。show-me 的产物是一次性的图与 HTML，不落库、不带校对日期、没有质量门槛。对照见 09。

04怎么装：两条路，先选一条

同一个技能有两条完全不同的安装路。它们的区别不在"装到哪"，而在"谁在读这个仓库"——选一条，用同一条更新。

路 A：skills 命令行工具（CLI，即在终端里敲命令用的界面）（README 官方推荐）

仓库 README 给的就是这一条：

npx skills add humanlayer/skills --skill show-me

这里的 skills 不是 Claude Code 的一部分，而是一个独立的 npm 包（vercel-labs/skills，自称 "The open agent skills ecosystem"）。npx 是 npm（Node 的包管理器）自带的一个命令，意思是"临时下载这个包并执行它"，所以你不需要先全局安装。本文核对时它最新版是 1.5.26（2026-09-11 发布）。它的 README 写着：Supports OpenCode, Claude Code, Codex, Cursor, and 75 more——也就是点名 4 家、另外还有 75 家，合计 79 家 agent；我数了它文档里的"支持列表"表格，共 70 行（有些行一行覆盖多个 agent 名）。这条路不绑定 Claude Code，这是它相对插件市场的最大优势。

先只看不装：用 --list 把仓库里的技能列出来

我实际跑过一次（npx -y skills@1.5.26 add humanlayer/skills --list），它把仓库里 5 个技能连同各自的 description 全部列了出来，顺序是：improve-claude-md、narrow-react-prop-types、build-iterated-agentic-loop、design-control-loop、show-me。

我实测的安装结果（可复核）

在一个空目录里执行 npx -y skills@1.5.26 add humanlayer/skills --skill show-me -a claude-code -y 之后，目录里只多了两样东西：

.claude/skills/show-me/SKILL.md   # 技能本体（3,297 字节）
skills-lock.json                  # 记账文件

CLI 自己打印的是 ✓ show-me (copied) → ./.claude/skills/show-me。注意是 copied 不是 symlink：交互安装时它会让你在"符号链接（一个指向真实文件的快捷方式，推荐，单一真相）"与"复制（各 agent 独立副本）"之间选，非交互模式下的结果就是复制。锁文件长这样：

{
  "version": 1,
  "skills": {
    "show-me": {
      "source": "humanlayer/skills",
      "sourceType": "github",
      "skillPath": "plugins/show-me/skills/show-me/SKILL.md",
      "computedHash": "de32a72f802801f08a84641b467f2c6306d35a58ce5e59ea607ac3a993a18c91"
    }
  }
}

skillPath 这一行顺手回答了一个常见疑问：为什么仓库要把技能埋在三层目录里。因为一个仓库可以有很多插件，CLI 需要精确知道"这个技能到底在哪个文件"，这样同一个仓里的 5 个技能才能被分别安装、分别记账、分别升级。

装到哪儿：项目内还是全局

路 B：Claude Code 插件市场

因为仓库里有 .claude-plugin/marketplace.json，Claude Code 可以把它整个当市场加入，然后按插件安装（插件名与目录名一致：show-me、improve-claude-md、narrow-react-prop-types、build-iterated-agentic-loop、design-control-loop）。这条路的特点是它会连 plugin.json 一起用——也就是说，走市场安装时，插件版本号（1.0.1 之类）与关键词是有意义的；走 CLI 安装时它们基本被忽略，因为 CLI 只读 SKILL.md 目录。

后续维护：四条命令

这几条命令在 CLI 自己的文档里都有对应小节（skills list 可带 -g 只看全局、-a 按 agent 过滤；skills update 可带 -g／-p／-y）。

05show-me：3,297 字节里到底写了什么

这是全文的重点。它的全部内容是 3,297 字节、127 行、460 词（我下载后直接数的）。开头只有三句话，但这三句话就是它的全部哲学：

这三句话各干掉一类毛病

它管的是"媒介选择"，不是"画图技术"

很多人以为 show-me 是个画图技能。它其实规定的是媒介映射：什么类型的疑问，默认该用哪种表达。全文给出了六种视图加一种 diff 形态，没有一句在讲怎么把图画好看——配色、字体、间距这些只出现在最后那个 HTML 分支里，而且写的是"匹配你的产品"，不是给一套自己的样式。

换句话说：它是一份"解释的排版规则"。它的价值不在于教会模型新东西（行数、缩进、Mermaid 语法它都会），而在于收窄选择空间——把"要不要写 800 字"这个每次都摇摆的决定，换成一个查表动作。

06六种视图 + 四种 diff：我该让它画什么

这是 show-me 的全部"语法"。左列是它给出的形态，右列是判断依据——原文只给了示例，没给这张对照表（全文的代码块标记数就是证据：4 个 text、1 个 tsx、1 个 mermaid、4 个 diff、1 个 ts）。所以下面后两列是把它的示例反推成规则，是本文的归纳，不是官方表述。

六种视图 + 整块代码：一张查表

术语补一句：Mermaid 是一种用纯文本描述图表的语法，支持它的阅读器会把那段文字渲染成图；diff 是"两份文本的差异"，+ 开头的行是新增、- 开头是删除、没标记的是原有内容。

diff 的四种形态（同一个 diff，四种内容）

原文给了四个 diff 示例，分别对应四类"变化"。这是全文最实用的一段——因为你问 agent"这次改了什么"的时候，它给的东西质量差别极大：

四种形态都遵守同一条规矩：未改动的行照旧显示，只让变化行带标记。这让读者不必重建整个结构，就能把注意力锁在变更上——这也是它比"贴改后的完整文件"强的地方。

同一个问题、三种形态：并列看一眼

假设问题是"用户点保存之后发生了什么"。三种形态的取舍是这样的（这三段直接来自原文的示例形状）：

# 形态 A：调用树（回答"顺序"）
submitForm
  createSession
    persistPrompt
    launchAgent
  navigateToSession

# 形态 B：Mermaid 时序图（回答"谁跟谁来回说话"）
User -> UI : 选择命令
UI -> Daemon : 发送展开后的提示词
Daemon --> UI : 流式返回结果

# 形态 C：伪代码（回答"判断逻辑长什么样"）
on(save)
  if content is unchanged
    return cached result
  write new content
  return fresh result

三个都对，问题只在于读者此刻卡在哪一层：卡在"我不知道后面还有几步"→ A；卡在"这俩组件到底谁请求谁"→ B；卡在"为什么它有时候不写盘"→ C。show-me 的整篇规范，说到底就是让模型先回答这个前置问题，再选形态。

07它什么时候才会去写一个 HTML 文件

前面六种视图都是"在对话里输出文本"，不碰文件系统。只有一条分支会真的写文件，原文是这么说的：

触发条件有四个，缺一个就别用 HTML

四条里前三条都是"文本天然表达不了"的情形。第四条给了模型很大的自主权，但它同时被前面的 "one focused"（一个、聚焦）和 "Pick the smallest view" 夹住——一个文件、聚焦一个点。

打开动作：原文写的是 Bash(open …)

文件写完之后，原文给的动作是这样的（代码块里就这一行）：

Bash(open path/to/show-me-{description}.html)

Bash(...) 是 Claude Code 的工具调用记法——它的意思是"用 Bash 工具执行括号里的命令"。这一行揭示了 show-me 的出身：它是为 Claude Code 写的，且默认你在 macOS（open 是 macOS 的打开命令）。

文件落在哪里，规范没说

现在的写法是一个相对路径 path/to/show-me-{description}.html。这条规范之前不是这样的（见 08 的一手 diff）：旧版把路径钉死在 .humanlayer/tasks/{task-slug}/show-me-{description}.html，也就是 HumanLayer 自己的任务目录。改成相对路径之后，技能才能脱离 HumanLayer 使用，但代价是落点没人管——它可能出现在仓库根目录、也可能在临时目录。

实用做法：在项目里先约定一个目录（例如 docs/ 或 .scratch/），并把这句约定写进你的项目说明；或者干脆把它加进 .gitignore（一个告诉 git"这些文件不用管"的清单），因为这类产物通常不该被提交。

边界："匹配产品配色"对没有设计系统的仓库是空指令

"Match the product's colors, type, spacing, and components" 的前提是你有一个可被识别的产品视觉。仓库里没有设计变量、没有组件库、agent 也没见过你们的界面时，这条指令无着落，模型只能自由发挥——出来的东西大概率是一份"通用好看的网页"，而不是"你们的界面"。这种场合下，与其让它猜，不如直接给它一份截图或现有页面文件。

最后一段 guidance：它其实在限制你

全文最后一段（也是最后一次修订新增的小节）写的是两件事：把每张图放在它所支撑的短文字旁边；只保留回答当前问题所需的调用、文件、props（组件的入参）、状态和边界。末尾两句话很关键：

这句话是写给模型的"刹车"：六种视图是选项集合，不是清单。它防的是模型最常见的偷懒替代品——"我全都给你来一遍"，看似周到，实际上把"挑出最小视图"这个职责又推回给了读者。

08它被改过四次：一手 commit 逐字节对照

下面的数据是我直接从 GitHub 拉取该文件在四个提交（commit，即一次代码存档）上的原始版本、逐字节比对得到的。它回答一个文档里不会写、但对使用者很要紧的问题：这个技能是往哪个方向演化的。

四个提交的字节数（实测）

四次修订，总量只涨了 320 字节（+10.8%）。这个数字本身就是一个判断：作者没有往里加功能，改的全是措辞与形态。我核对过：仓库当前的 main 分支（提交 3c26291，2026-08-13）上的 show-me 文件，与 6ab9013 的版本逐字节相同（SHA-256 一致），也就是说自 8 月 13 日起它没有再被改过。

从 diff 里读出的三条结论

你怎么自己复核（三条命令）

不需要克隆仓库，按提交哈希取原始文件即可：

curl -s https://raw.githubusercontent.com/humanlayer/skills/<提交哈希>/plugins/show-me/skills/show-me/SKILL.md -o sm-<哈希>.md
wc -c sm-*.md                      # 对照上表的字节数
diff -u sm-a2e3bf7.md sm-d3138e5.md   # 看第一次改了什么

# 校验某一个版本是否被改动过（取当前 main）：
shasum -a 256 plugins_show-me_skills_show-me_SKILL.md
# 当前 main 上的 show-me SKILL.md 应为 bea6da70a58096730b9aeb0bae293ddf4726103a98efc9ce13c481619942a810

我按这三条重跑了一次，四个版本的字节数分别是 2,977 / 3,168 / 3,230 / 3,297，与上表完全一致；当前 main 的 SHA-256 也确实是 bea6da70…。SHA-256 是一种"指纹"算法：把任意长度的内容压成一串固定长度的字符，内容变一个字节，指纹就完全不同——所以拿它对比就能判断文件有没有被改过。顺便记下另外三版的指纹，方便你对照：a2e3bf7 是 19643862…、d3138e5 是 343a1029…、4d8d644 是 2a20c9c8…。

09show-me 与 /learn：两个都产 HTML，验收方式完全不同

如果你手上有多个会生成 HTML 的技能，最该先分清的是这一组。本仓的 /learn（就是写出你正在读的这篇文章的那个技能）与 show-me 都能产出 HTML，因此常被混为一谈，但它们从锚点到验收没有一处相同。

六个维度逐条对照

公平地说，反过来的误用同样存在：用 /learn 去问"这个函数在第几步被调用"是拿大炮打蚊子——它会联网、会写一篇带术语表和参考来源的文章，而你真正需要的是一棵四行的调用树。

10最小例子：敲下 /show-me 之后发生了什么

下面这个场景可以直接照抄：你正在读一个技能目录，想知道"它一次运行到底经过哪些步骤"。

场景

你刚下载了这个仓库，看着 show-me 那 127 行，心里的问题是："我敲下 /show-me 的那一刻，到屏幕上出现一张图，中间发生了什么？"

两种要法：同一件事，问法决定结果

它实际会输出的东西（可以直接当模板）

左边这棵树对应上面"好的要法"，右边的 diff 对应另一种常见疑问——"新版和旧版差在哪"。两段都是可以直接拿去当模板的形状：

# 形态一：回答"经过哪几步"（调用树）
/show-me 被触发
  读当前对话，锁定"当前话题"
  判断话题属于哪一类
    算法/逻辑 → 伪代码
    运行时控制流 → 调用树
    UI 结构 → 组件树
    文件职责/重构 → 文件树
    多参与者交互 → Mermaid
    "变了什么" → diff
    视觉/布局/密概念 → 写一个 HTML 文件并打开
  产出该视图（保持散文极短）
  自查：是不是"最小的那个视图"

# 形态二：回答"新旧版差在哪"（文件布局 diff）
 show-me/SKILL.md
 HTML 分支的写文件动作
-  task-artifact .humanlayer/tasks/{task-slug}/show-me-{description}.html
+  Bash(open path/to/show-me-{description}.html)
 结尾的提醒
-  一段普通段落
+  ### guidance 小节

一次完整的调用长什么样（三步）

11improve-claude-md：把"长清单"改成"条件触发"

插件市场里的原始描述是："Rewrite a CLAUDE.md file using <important if> blocks to improve instruction adherence"——重写 CLAUDE.md，用条件块提高指令的遵守率。

它针对的具体毛病：你的说明被"允许忽略"包着

Claude Code 在你每次对话时注入 CLAUDE.md 的内容，但注入的不是"原文照读"，而是带着一句限定：这句话的大意是"这份上下文可能与你的任务相关，也可能不相关；除非高度相关，否则不要理会它"。技能文档把这句话原文引了出来，并给出推论：文件里跟当前任务无关的内容越多，模型越可能连相关的那部分一起忽略。

所以问题不是"你的 CLAUDE.md 写得不好"，而是"它被一段允许忽略的框架包着，而你没有给模型任何区分信号"。

解法：给条件性内容套上 XML 条件块

把"只在某类任务下才相关"的内容包进 <important if="条件">，利用与系统提示同类的 XML 标记（一种用尖括号包住内容的结构化写法），给模型一个明确的"现在这条适不适用"的判据。

五条原则（浓缩）

错误与正确：条件块怎么写

<important if="你在写或改任何代码">
- 用绝对导入
- 用函数组件
- 文件名用 camelCase
</important>

<important if="你在新增或修改导入">
- 用 @/ 绝对导入
</important>

<important if="你在新建组件">
- 用函数组件 + 显式 props 接口
</important>

<important if="你在新建文件或目录">
- 用 camelCase
</important>

它自带一个完整的改前／改后范例

技能的后半篇是一份 Express（Node 上的网页服务框架）+ React（前端界面库）的样例（项目用 Turborepo 把多个包放在同一个仓库里管理） CLAUDE.md 改写。范例里最值得学的是它明确写出"删了什么、为什么"：

12narrow-react-prop-types：让类型只描述真实会走到的路径

它处理的是一个很具体的病症：组件 props 被 Storybook、mock、测试、demo 撑宽了，于是类型系统开始允许那些应用真实路径永远不会进入的状态。先解释三个词：props 是父组件传给子组件的入参；Storybook 是一个"把组件单独拿出来看"的开发工具；mock 是假的替身数据。

核心要求（原文的六条，重述）

• 改类型之前，先找出真实的、非测试非 Storybook 的调用点；
• 把真实代码路径当作 prop 契约的唯一真相；
• 不要为了让 Storybook／测试／mock 好写而保留可选 prop；
• 只有当"某个非 Storybook、非测试的调用点确实不传它、且有不传的理由"时，才让 prop 保持可选；
• 类型不应该能表达出真实调用点里观察不到的状态；
• 类型越严，代码就能越简单；能推导就推导，别手写重复的形状。

推理链条：为什么"可选"是有代价的

它给出的理由是全文最值得记住的一句推理：每一个可选 prop 都是组件必须处理的一个额外分支。可选 prop 越多，组件要思考的状态越多，要测试的分支越多，要维护的正确性越多。

顺带一个容易搞混的点，技能里专门点出来了：可空（nullability）与可选（optionality）是两件事。如果真实代码总是传这个 prop，但值本身可能是空的，那正确写法是"必需的、可为 null 的 prop"（focusedItem: Item | null），而不是"可选且可为 null"（focusedItem?: Item | null）。前者表达"一定会传，但可能没有当前焦点"；后者多出来一个"压根没传"的状态，而那个状态并不存在。

十一步工作流的压缩版（五步）

错误与正确：一对典型改法

interface RowProps {
  onRename?: (id: string, name: string) => void
  items?: Item[]
}

// 永远渲染这个按钮，但回调可能是 undefined
<button onClick={() => onRename?.(id, name)}>
  重命名
</button>

const list = new Set(expandedIds ?? defaultIds ?? [])

interface RowProps {
  onRename: (id: string, name: string) => void
  items: Item[]
}

<button onClick={() => onRename(id, name)}>
  重命名
</button>

const list = new Set(expandedIds)

它的附件里藏着一个真实运行的例子

三个附件中有一个是完整可用的定时工作流（references/agent-narrow-component-props.yml，11,103 字节），它是这个仓库"技能 + 定时 agent"这套打法的原始样板，也是另外两个循环技能自称参照的"具体参考模式"。我逐条读过里面的真实细节：

• 触发器是每天一次 + 手动派发 + PR 上 /iterate 评论三种（/iterate 指维护者在 PR 下留言 /iterate <反馈>，让当初开这个 PR 的那支工作流按反馈再改一次）（定时的 cron 表达式是 0 13 * * *，即每天 13:00 UTC（协调世界时，比北京时间晚 8 小时）跑一次）；
• 运行机器用的是 blacksmith-8vcpu-ubuntu-2404（不是 GitHub 默认的运行机器）；
• agent 走 CodeLayer，模型写死为 claude-opus-4-8；运行环境是 Node 24（Node 是让 JavaScript 在浏览器之外运行的程序）+ bun 1.3.14（另一个更快的同类工具）；
• 配的记忆文件（narrow-component-props-memory.md，213 字节）全文只有一行有效内容：Focus only on apps/riptide-ui; do not make changes in apps/riptide-cloud. 这是"记忆文件应该写什么"的最好示范——一条永久性的范围约束，而不是任务日志。

13build-iterated-agentic-loop：把一个重复任务变成每天开 PR 的机器

它不是自己执行任务，而是给你造一台机器：一个定义"agent 该怎么判断"的技能，一支会定时运行的 GitHub Actions 工作流（GitHub 自带的自动化：满足条件就自动跑一串命令），一份承载长期反馈的记忆文件，以及一组参考模板。

它会往你的仓库里写四个文件

九个步骤里，三个值得单独讲

四家 agent 的接法不一样，附件里全给了

最后一个附件（agent-runner-templates.md）按 agent 给出无头运行命令（"无头"指不弹界面、直接在命令行里跑）、密钥名与响应提取方式。这里的差异是实打实的——每个 agent 输出格式不同，把最终回复取成 PR 正文的方法就不同：

14design-control-loop：先把"要驱动什么"讨论清楚，再动手建

它是本仓最长的一份，也是最"不像模板"的一份。原文明确说了：没有固定工具集，也没有可复制的模板；你要做的是访谈用户、和用户一起设计，然后再替他实现出来。

五件套：把"agent 偶尔跑一下"变成一台可观测的机器

它借用控制论（研究"系统怎么自我调节"的学科）的词汇，把循环拆成五样东西，外加一个"人在环上"：

它还专门说明了一件事：组件可以融合，而且应该允许融合。一个既能报问题又能按影响排序的工具，就同时干了传感器和控制器的活；一个既选目标又动手改的 agent，就是控制器加执行器。不要人为制造设计里并不存在的分离——这一句直接把它和"为了好看而画三条独立步骤"的做法区分开了。

A–H 八个阶段

流量控制在这里指"限制同时开着多少个 PR"，防止评审积压。阶段 D 是它和别的"自动化技能"最不一样的地方：在接进 CI 之前，传感器、控制器、执行器必须各自能在本地单独跑一遍——先跑传感器确认测量稳定，再拿真实测量结果跑控制器确认选出的目标合理，最后用无头命令让执行器改一个目标并跑通校验。原文的说法是：工作流只应该编排那些你已经能手动运行的东西，这样循环才可调试。

附件里那个完整范例：它到底长什么样

十个附件里有一个是"逐部件注解的一个真实生产循环"（React 代码质量，单应用）。它明确写着这是插图不是模板，但里面的取舍很值得看：

• 传感器选了一个独立于编辑器／lint 配置的扫描器，理由是可以被配置文件集中控制——一个顺手的内联注释关不掉它。原文特意强调这个理由"对这个团队重要，而不是对所有传感器的要求"。
• 控制器与传感器融合：没有独立控制器，工具返回"影响最大的前 3 类规则"，而循环的策略是"这次最多修这 3 类里的 5 个问题"，选择逻辑写在执行器的提示词里。
• 执行器给 agent 三个诚实的选项：修掉、忽略（并在配置文件里写明理由）、跳过（留给人类）。每改一处都单独校验、单独提交。
• 阻尼器是第二支工作流：在每个 PR 与推送到主分支时运行，对比合并基线，只对新增的问题评论，默认只提示（不会把同事的 PR 变红），并留了一条"团队信任信号之后可以升级为拦截"的路。
• 流量控制：所有 PR 打同一个标签，定时运行发现已有开着 PR 就跳过；手动派发绕过。

这个范例的结尾也值得抄：它把"可复用的形状"与"不可复用的细节"分开列出——可复用的是设定值 → 传感器 → 控制器 → 执行器 + 阻尼器 + 记忆文件 + /iterate 转向 + 单 PR 流量控制；不可复用的是那个具体扫描工具、bun 命令、"前 3 类 / 5 个修复"的策略、以及那个应用的包名。这几行恰好就是"该抄什么"的答案。

15两个循环 skill 差在哪：我逐文件比对过

这两个技能看起来很像（都会产出技能 + 工作流 + 记忆文件 + 模板），文档里也互相引用（前者说"某个具体技能是参考模式"，后者说"借用控制论词汇"）。到底该用哪个？我把两边的全部附件下载下来逐个比对，结果很清楚。

附件对照（含哈希）

复核方式：curl 取两个插件各自 references/ 下的同名文件，用 shasum -a 256 比较，或用 diff 看差异。我按这条重跑了一次，agent-iteration.ts 两边都是 5,896 字节、指纹都是 b7a4b53d388faef2a677b11d8b38e44ac53bc8a6734ef905b76afa2f4a0fc6ec。

工作流模板差了哪两段

两者差出来的 1,560 字节，具体落在两处（我 diff 出来的）：

• 常规路径被拆成三个显式步骤：Sensor — measure current state → Controller — select the next increment → Actuator；而 build-iterated 版本只有一个 Run coding agent。/iterate 那条路也单独拆成了一个 Actuator — iterate on feedback 步骤，理由是：迭代是对一段评审意见做一次执行，不是一趟全新的"感测→控制→执行"循环。
• 多了一句免责：如果传感器与控制器本来就融合在 agent 里，就把这三步折叠成一步，别发明设计里没有的分离。

其余差异是措辞：注解里多了"（流量控制）"的标注、"setup 假设是 bun/Node 仓库，请替换成本仓运行时"的提醒。

该用哪个

16九个坑与边界（按踩到的概率排序）

1. 用 show-me 之前，上下文里得先有东西

它没有参数、不联网、不读文件。你在一个空对话里敲 /show-me，它只能拿最近读过的内容来画。先用一句话给它锚点，或先让它读那个文件。

2. Bash(open …) 出了 Claude Code 就不成立

见 07。Linux 换 xdg-open、Windows 换 start，或者干脆让它只报路径。不改这一行，HTML 会静静地躺在某个目录里没人看。

3. HTML 产物没有指定的落点

相对路径 path/to/…html 意味着它可能出现在仓库的任何地方。提前约定目录或加进 .gitignore，否则你的 git status 里迟早会冒出几个不相干的 HTML。

4. "再详细一点"是 show-me 的反向指令

它的全部价值建立在"最小视图"上。不满意时提形状（"用 diff 重画""换成时序图"），不要提信息量。

5. 技能以完全权限运行

skills CLI 在安装完成后自己打印了提醒："they run with full agent permissions"——技能是以 agent 的完整权限运行的，装之前该看一眼内容。CLI 会显示第三方扫描（我在安装时看到的是"Safe / 0 alerts / Low Risk"），但那只是启发式检查，不能替代你自己读一遍。这个仓库只有 5 个 markdown 技能、没有可执行脚本，风险很低；但换成别的仓库就要留意 references/ 里的脚本。

6. 循环型工作流要求配置密钥，且默认放权

四家 agent 的示例都使用绕过审批的模式。这类工作流只应跑在受信任的隔离机器上，密钥要按最小必要配置——不要给一个只是改代码风格的 agent 配生产环境凭证。

7. 定时工作流首次点不动

workflow_dispatch 在工作流从未运行过之前不可用，必须先用一次 push 触发 bootstrap（13 的第 ③ 点）。不知道这条的人会以为自己写错了 YAML（配置文件的格式）。

8. 不设 PR 边界，一周后你会有一堆无人评审的 PR

两个循环技能都推荐"每个循环最多 1 个开着 PR"。这不是保守，是原文给出的经验判断：不设界时，每天一次的运行能在一周内堆出 5 个以上待评审 PR。

9. 别把 skill 当成"模型会自动想起的能力"

本仓 5 个技能的 description 都是陈述功能的写法，没有声明触发条件。多数情况下你需要显式敲命令，或明确说"用 show-me 讲"。指望它在你需要时自动出现，多半会落空。

这条差别值得留意：仓库里的 description 是陈述功能的写法，不是声明触发条件的写法。它把"什么时候用"交给了你，而不是模型——对 show-me 这种影响输出形态的技能，这是合理的选择：你不会希望模型在解释任何东西时都自作主张改画图。

17什么情况下不要用这些技能

上面讲的是"怎么用"。这张表讲"什么时候别用"——它比前一张更重要，因为装错了技能的成本不是零：它会一直在你的技能目录里，被模型按名字看到。

18装对了没：本机实测记录（含 SHA-256 核对）

下面每一行都是我在核对日（2026-09-13）实际执行过的，不是转述文档。

与上次核对的差异（本文改掉了哪些旧事实）

本文的上一版写于 2026-09-10。这次重核，有四处数字变了，其余一手料（提交字节数、SHA-256、附件哈希、文件树）完全没变：

另外一处旧版措辞我改准了：旧版说 CLI 支持"80 家 agent"，其实 CLI 自己的 README 写的是 "Supports OpenCode, Claude Code, Codex, Cursor, and 75 more"——点名 4 家加 75 家，合计 79 家；它的支持列表表格共 70 行（有些行一行覆盖多个 agent 名）。"80 家"是四舍五入，不够准，本文改成 79。

19常见问题

20术语对照表

21参考来源与证据边界

我实际读了什么

• github.com/humanlayer/skills 仓库 main 分支（最新提交 3c26291，2026-08-13）的全部 5 份 SKILL.md 与全部 21 个 references 附件，以及根 README.md、LICENSE、.claude-plugin/marketplace.json、5 份 .claude-plugin/plugin.json。
• GitHub REST API（GitHub 提供的网址接口：用一条 URL 就能取回仓库数据）：仓库元数据（stars / forks / 创建与最后推送时间）与提交列表（用于 08 的四个提交）；git/trees/main?recursive=1 用于 35 文件 / 25 目录与全部字节数。
• raw.githubusercontent.com：按提交哈希取 show-me 的四个历史版本做逐字节 diff，并取两个循环技能的同名附件做哈希比对。
• skills.sh 的 humanlayer/skills 页面：5 个技能的装机量与仓库总量（页面显示的是四舍五入到 0.1K 的值）。
• vercel-labs/skills 的 README 与 npm registry：CLI 版本、支持的 agent 数与安装作用域、各子命令、--list／--copy 等选项。
• 本机实测：用 npx skills@1.5.26 列出、安装（空目录）、检查落点与锁文件、用 shasum 与上游原文比对，并另装一次带 references 的技能确认附件会一起落地。
• humanlayer.dev 首页：用于确认 HumanLayer 是什么产品（多人协作的 coding agent IDE 加云端）。

本文实算的数字（复核方式都写在正文里）

35 个文件 / 25 个目录；5 份 SKILL.md 合计 49,559 字节；各技能字节数（3,297 / 9,450 / 7,764 / 13,553 / 15,495）；各插件总字节（3,691 / 9,847 / 21,336 / 48,163 / 62,488）；show-me 四版字节数（2,977 / 3,168 / 3,230 / 3,297）；show-me 的行数／词数（127 / 460）；两个循环技能共用附件的 SHA-256 比对；装机量分项之和与页面总数的两次交叉验证；安装副本与上游原文的 SHA-256 一致性。全部由本地脚本、curl、diff、shasum 算出，不依赖任何二手摘要。

证据边界与时效

• 版本口径。所有事实的读取时间是 2026-09-13；上游 main 当时最新提交是 3c26291（2026-08-13）。这是一份会过时的资料——5 个技能里有 4 个仍是 1.0.0 的初版，show-me 在 8 月 9 日至 13 日之间被改过四次，说明这个仓库还在活跃修改。
• 明确的推断（未验证）。18 里"computedHash 可能是整目录清单哈希"是从"它不等于文件哈希"这一实测事实推出的，文中已就地标注为推断；我没有读 CLI 源码确认它的构造方式。
• 没有验证的东西。① Claude Code 插件市场那条安装路径我没有真实执行——plugin.json 与 marketplace.json 的字段含义来自文件内容与插件规范的常识，没有跑通安装验证；② 两个循环技能生成的 GitHub Actions 我没有在一个真实仓库里跑过，"首次不能手动派发"这条来自技能文档的自述与 GitHub 的公开行为，不是我实测；③ show-me 的 HTML 分支在真实项目里的产出效果我没有现场对照过。
• 一处口径说明。装机量（installs）是 skills.sh 平台自己统计的数，页面只给出四舍五入到 0.1K 的值；本文只转述并标明来源与日期，不做趋势判断——同一技能在插件市场那条路上的安装不在这个数里。

你自己验的那一条

上面所有结论你都能自己复核。唯一一条只有你能验：把本文的例子换成你自己场景里的例子——打开你正在改的那个文件，用 /show-me 用调用树讲一下 XXX 的执行顺序 问一次，看它给你的树是不是"刚好说清要害的最小视图"。如果它给了你一张大而全的东西，说明那个刹车在你这里没有生效——那正是本文要你留意的地方。

99一句话总结