1实现原理 · 为什么它能做到

这是一个纯展示型指令卡：SKILL.md 正文就是一张静态速查表（6 个模式 + 4 个 skill + 关闭方式 + 语言规则 + 默认模式配置），没有任何脚本、工具调用或文件写入指令。

skills/caveman-help/SKILL.md

Display this reference card when invoked. One-shot — do NOT change mode, write flag files, or persist anything. Output in caveman style.

这里在做什么：把 skill 的执行语义收缩成「把本文件内容按 caveman 风格输出」。其余全部是给人看的表格（Modes / Skills / Deactivate / Language / Configure Default Mode），没有一处要求 agent 跑命令、读文件或改状态。

「一次性、无副作用」被写进两处：SKILL.md 正文自述，以及仓库自带的 skill 行为对照表（输出契约 / 副作用两列）。

docs/technical/skills-hooks-and-plugins.md

| `caveman-help` | One-shot command card | Does not change active mode |

同一张表里对照者是 caveman-stats（读本地会话日志 + 写状态后缀）与 caveman-compress（读写所选本地文件）：caveman-help 的「副作用」列是全表最干净的一个，只声明不改模式。

卡片教的「默认模式」配置是真机制而非文档口号：宿主的 hook 代码里有一条四级解析链，env var 优先级最高，最后兜底 'full'。

src/hooks/caveman-config.js

// Resolution order for default mode: // 1. CAVEMAN_DEFAULT_MODE environment variable // 2. Repo-local config (checked-in, per-project default):

卡片只讲了前两级里的「env > 用户 config 文件 > full」，而代码实际是 env > 仓库内 .caveman/config.json 或 .caveman.json（从 cwd 向上逐级查找）> 用户 config（$XDG_CONFIG_HOME 或 ~/.config 或 %APPDATA%）> 'full'。差距见 verification.second_pass。

模式语义由同仓库的 caveman 主 skill 兑现，本卡片只是它的索引：模式会「粘住」，直到用户改或会话结束。

skills/caveman-help/SKILL.md

Mode stick until changed or session end.

与 skills/caveman/SKILL.md 的 Persistence 段一致（'Default style for this whole session, every response, until user say "stop caveman" or "normal mode"'）。卡片负责告诉用户有哪些档（lite/full/ultra + 三个 wenyan 变体），主 skill 负责执行。

卡片刻意保留用户语言：压缩的是风格，不是语言；技术术语/代码/命令/错误串原样保留。

skills/caveman-help/SKILL.md

Keep user's language by default. User write Portuguese → reply Portuguese caveman. Compress the style, not the language. Technical terms, code, commands, commit types, and exact error strings stay verbatim unless user ask for translation.

与主 skill 一致（主 skill 还额外禁止为「像 caveman」而增词）。这条对多语言团队是可用性关键：术语不被翻译，输出仍可被工具/同事直接消费。

触发面是用户显式调用（/caveman-help）加一句自然语言别名，别名同时写在 SKILL.md 的 description 与给人看的 README 里。

skills/caveman-help/README.md

Also triggers on "caveman help", "what caveman commands", "how do I use caveman".

SKILL.md frontmatter 只写 'Trigger: /caveman-help or "caveman help"'，README 扩到三条口语问法。

分发路径：本 skill 不进 Claude Code 插件镜像（plugins/caveman/skills/ 下只有 caveman / cavecrew / caveman-stats / caveman-compress），而是通过独立 hook+skill 安装路径与 `npx skills add`、以及 CLI 对 hermes/opencode 的 skill 目录清单到达各宿主。

bin/install.js

const HERMES_SKILL_DIRS = ['caveman', 'caveman-commit', 'caveman-review', 'caveman-help', 'caveman-stats', 'caveman-compress', 'cavecrew'];

CLAUDE.md 把这条分工写明（'Skills not in this table (`caveman-commit`, `caveman-review`, `caveman-help`, `caveman-stats`) are not mirrored into the Claude Code plugin distribution by CI.'）；skills/registry.json 的 preserved_skill_ids 也含 caveman-help。

2核心能力

01一屏速查：6 个模式档与其触发词（lite / full / ultra / wenyan-lite / wenyan / wenyan-ultra）

02速查兄弟 skill 与其输出契约（caveman-commit / caveman-review / caveman-compress / caveman-help 自身）

03给出关闭与恢复口令，避免用户被「粘住」的模式困住

04默认模式的两种配置方式（环境变量 CAVEMAN_DEFAULT_MODE、用户配置文件 defaultMode 字段）

05用 "off" 关掉会话启动时的自动激活，同时保留手动 /caveman

06语言保真规则：只压风格不换语言，术语/代码/命令/错误串逐字保留

07不改变会话状态（不切模式、不写 flag 文件、不落盘），纯只读问答

4管控建议与判定依据

建议配套管控措施

面向 Agent

可自动加载

面向管理者

登记来源与版本

判定依据（文件路径与关键语句摘要）

SKILL.md: 纯提示词指令与规则文本，无脚本执行与外部影响

审计说明： 。纯指令型、零脚本、零网络、零凭证、零写入，且被仓库行为对照表独立记为不改变会话状态。唯一需要注意的是卡片内容会引导用户去设置环境变量/配置文件（这是使用建议，不是 skill 自身行为）。

5第二遍独立确认

[ok] 卡片属实：一次性展示、不改模式、不落盘 — SKILL.md 正文首段与 docs/technical/skills-hooks-and-plugins.md 的副作用列两处独立印证；目录内无任何可执行脚本。
[discrepancy] 默认模式配置链（卡片声称 env > config file > full） — 卡片写 'Resolution: env var > config file > `full`.'，实际代码是四级且含仓库内配置：① CAVEMAN_DEFAULT_MODE → ② 仓库内 .caveman/config.json 或 .caveman.json（从 process.cwd() 向上最多 64 级查找，拒绝符号链接）→ ③ 用户 config（$XDG_CONFIG_HOME/caveman/config.json，或 ~/.config，或 Windows %APPDATA%）→ ④ 'full'（src/hooks/caveman-config.js:15-26 与 findRepoConfigPath 注释）。卡片漏了「仓库内配置」这一层，团队若用 .caveman.json 固定项目默认档，卡片会让人误判优先级。非安全影响，属文档简化。
[ok] wenyan 档位命名一致性（卡片 vs 主 skill vs 代码） — 卡片列 wenyan-lite/wenyan/wenyan-ultra（并称 'Wenyan-Full | /caveman wenyan'）；代码 VALID_MODES 为 ['off','lite','full','ultra','wenyan-lite','wenyan','wenyan-full','wenyan-ultra',...]，卡片触发词全部落在集合内；主 skill SKILL.md 的切换串亦为 '/caveman lite|full|ultra|wenyan-lite|wenyan-full|wenyan-ultra|off'。
[ok] 外部依赖为零 — 对两个文件扫描 URL/CLI/包/网络 token 零命中；卡片末行的 'Full docs: https://github.com/JuliusBrussee/caveman' 是给人点的文档链接，不是运行时调用点。
[ok] 无脚本执行 / 无凭证读取 / 无文件写入 — skills/caveman-help 下仅两个 markdown；仓库级 shell/node 代码（bin/install.js、src/hooks/*）属于 caveman CLI 本体，不由本 skill 触发，除 SKILL.md 文字外无任何指向它们的调用指令。
[ok] 声明 'Saves ~46% input tokens'（指向 caveman-compress）是否有出处 — skills/caveman-compress/README.md 基准表平均值为 46%（Average 898 → 481，46%），卡片引用与邻居 skill 自述一致。
[ok] pin commit 与上游状态 — 本地 HEAD == origin/main == 15581d14007fd01fb3f132016741962f34936ca2（2026-09-07T08:19:43+00:00, 'chore: sync SKILL.md copies [skip ci]'）。gh 显示仓库 pushed_at 晚于该时间，故本报告结论仅对该 pin commit 有效，不跨版本推广。

6结论

零成本、零风险的可发现性入口：一个 markdown 卡片让用户在三秒内看到所有模式与命令，无脚本、无网络、无写入。

与执行层解耦：卡片只做索引，真正的模式行为在同仓库 caveman 主 skill，改卡片不会改行为，扩散风险低。

多语言友好：明确「压风格不换语言」且术语/代码/错误串逐字保留，跨语言团队不会因压缩而丢技术精度。

副作用面被独立记录并可验证：仓库自己的行为对照表为它标注「不改变 active mode」，用户可按副作用挑工具。

适合： 适合任何在用 caveman 系（模式压缩输出 token）的团队与个人：忘记 slash 命令时当速查卡、向新成员解释有哪些档位与兄弟命令、需要告诉别人如何固定默认模式或关掉自动激活时。也适合 skill 作者当「零资产 skill」的样板参考。

不适合： 不适合期望它「切换模式」的场景——它是展示卡不是开关（SKILL.md 明确 'Does not change mode'）；不适合需要精确了解配置解析链的人（应直接读 src/hooks/caveman-config.js，卡片漏了仓库内配置层）；不适用于未安装 caveman 主 skill 的环境，卡片描述的档位行为无从执行。

Install Agent-Ready

① Verified Mirror 2026-09-15

Option A · Direct DownloadDownload caveman-help.tar.gz

sha256: 742f9e1fe5d8d598…

Option B · Copy Guide for Agent

install.json

agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。

② Upstream GitHub

GitHub Repo ↗

Pinned to commit 15581d1400.