本文用场景解释 Hermes Agent 的 skills 是如何“进化”的。重点回答五个问题：

1. 模型为什么知道要创建或更新 skill？
2. skill_manage、skills_list、skill_view 分别负责什么？
3. 一个经验如何从一次任务沉淀成 SKILL.md？
4. 模型如何选中要加载的 skill？
5. skill 库越来越多时，Hermes 如何治理和合并？

写法按“用户说 → 模型看到提示词/工具描述 → 模型判断 → 调用工具 → 写入或复用 skill”展开。提示词和 tool description 会在用到的场景附近给出英文原文和中文对照。

1. 一句话总览

memory 负责保存事实：用户是谁、环境是什么、偏好是什么。
skills 负责保存方法：这类任务以后应该怎么做。

运行上可以理解为：

用户提出任务
  ↓
模型完成任务时遇到复杂流程、踩坑、修复路径或用户纠正
  ↓
模型判断这个经验是否以后还会复用
  ↓
如果是一次性状态：不写 skill
如果是可复用流程：调用 skill_manage(create)
如果已有 skill 但缺步骤：调用 skill_manage(patch)
如果细节太长：调用 skill_manage(write_file) 放进 references/templates/scripts
下次遇到类似任务：先看 system prompt 的 skills index，再通过 skill_view 或 /skill-name 加载
后台 review 和 curator 继续补漏、合并、归档

一个通俗区分：

用户偏好“文档要场景化” → memory。
“写这类文档的步骤、结构、检查清单” → skill。

2. 模型为什么知道要创建或更新 skill

先看一个场景。

用户：这次我们已经把 memory 文档写到 V6 了。以后再写这种实现分析文档，要按场景讲，prompt 和 tool description 放在用到的地方，最后做关键字检查。

模型为什么会知道这不只是普通对话，而是一个可以沉淀为 skill 的 workflow？

因为它在本次 LLM 请求里同时看到两类信息：

1. system prompt 里的 SKILLS_GUIDANCE。
2. tools schema 里的 SKILL_MANAGE_SCHEMA.description。

代码不是用正则判断“用户说以后，所以创建 skill”。真正判断的是 LLM。

2.1 用到的 system prompt：SKILLS_GUIDANCE

当 skill_manage 工具在 valid_tool_names 中时，run_agent.py 会把 SKILLS_GUIDANCE 加入 system prompt。

英文原文：

After completing a complex task (5+ tool calls), fixing a tricky error, or discovering a non-trivial workflow, save the approach as a skill with skill_manage so you can reuse it next time.
When using a skill and finding it outdated, incomplete, or wrong, patch it immediately with skill_manage(action='patch') — don't wait to be asked. Skills that aren't maintained become liabilities.

中文对照：

完成复杂任务（5 次以上 tool calls）、修复棘手错误，或发现非平凡 workflow 后，请用 skill_manage 把方法保存为 skill，这样下次可以复用。
当使用某个 skill 时，如果发现它过时、不完整或错误，请立即用 skill_manage(action='patch') 修补，不要等用户要求。没有维护的 skills 会变成负担。

这段提示词告诉模型：

复杂任务完成后，要考虑沉淀流程。
修复 tricky error 后，要考虑沉淀修复路径。
发现非平凡 workflow 后，要保存为 skill。
使用 skill 时发现问题，要立即 patch。

所以模型看到用户说：

以后再写这种实现分析文档，要按场景讲，prompt 和 tool description 放在用到的地方，最后做关键字检查。

会判断：

这是“如何完成这类文档任务”的流程经验。
它不是单个用户事实，而是可复用方法。
如果本轮任务足够复杂，就适合保存为 skill。

2.2 用到的工具描述：SKILL_MANAGE_SCHEMA.description

同一次请求里，模型还会看到 skill_manage 工具 schema。description 会告诉模型什么时候 create、什么时候 patch、什么时候跳过。

英文原文：

Manage skills (create, update, delete). Skills are your procedural memory — reusable approaches for recurring task types. New skills go to ~/.hermes/skills/; existing skills can be modified wherever they live.

Actions: create (full SKILL.md + optional category), patch (old_string/new_string — preferred for fixes), edit (full SKILL.md rewrite — major overhauls only), delete, write_file, remove_file.

On delete, pass `absorbed_into=<umbrella>` when you're merging this skill's content into another one, or `absorbed_into=""` when you're pruning it with no forwarding target. This lets the curator tell consolidation from pruning without guessing, so downstream consumers (cron jobs that reference the old skill name, etc.) get updated correctly. The target you name in `absorbed_into` must already exist — create/patch the umbrella first, then delete.

Create when: complex task succeeded (5+ calls), errors overcome, user-corrected approach worked, non-trivial workflow discovered, or user asks you to remember a procedure.
Update when: instructions stale/wrong, OS-specific failures, missing steps or pitfalls found during use. If you used a skill and hit issues not covered by it, patch it immediately.

After difficult/iterative tasks, offer to save as a skill. Skip for simple one-offs. Confirm with user before creating/deleting.

Good skills: trigger conditions, numbered steps with exact commands, pitfalls section, verification steps. Use skill_view() to see format examples.

Pinned skills are protected from deletion only — skill_manage(action='delete') will refuse with a message pointing the user to `hermes curator unpin <name>`. Patches and edits go through on pinned skills so you can still improve them as pitfalls come up; pin only guards against irrecoverable loss.

中文对照：

管理 skills（创建、更新、删除）。Skills 是你的程序性记忆：用于反复出现任务类型的可复用方法。新 skills 会写到 ~/.hermes/skills/；已有 skills 可以在其所在位置被修改。

动作：create（完整 SKILL.md + 可选 category）、patch（old_string/new_string，修复时优先使用）、edit（完整重写 SKILL.md，仅用于大改）、delete、write_file、remove_file。

删除时，如果是把这个 skill 的内容合并进另一个 umbrella skill，请传 `absorbed_into=<umbrella>`；如果是无转发目标地裁剪，请传 `absorbed_into=""`。这能让 curator 不靠猜测地区分“合并”和“裁剪”，从而让下游消费者（例如引用旧 skill 名称的 cron jobs）被正确更新。`absorbed_into` 指向的目标必须已经存在；要先创建或修补 umbrella，再删除旧 skill。

创建时机：复杂任务成功（5 次以上 calls）、克服错误、用户纠正后的方法奏效、发现非平凡 workflow，或用户要求记住某个流程。
更新时机：说明过时或错误、出现 OS 特定失败、使用中发现缺步骤或缺坑点。如果你使用了某个 skill，并遇到它没覆盖的问题，应立即 patch。

困难或迭代型任务后，主动提出保存为 skill。简单一次性任务跳过。创建或删除前需要用户确认。

好的 skills 包含：触发条件、带精确命令的编号步骤、pitfalls 小节、验证步骤。使用 skill_view() 查看格式示例。

Pinned skills 只防删除。skill_manage(action='delete') 会拒绝，并提示用户运行 `hermes curator unpin <name>`。Pinned skills 仍然允许 patch 和 edit，这样踩坑时仍能改进；pin 只防止不可恢复的丢失。

这段 description 和 SKILLS_GUIDANCE 共同告诉模型：

复杂任务成功后，可以 create。
修复已有 skill 的小问题，优先 patch。
大改才 edit。
长细节不要都塞进 SKILL.md，可以 write_file。
简单一次性任务不要存。
创建/删除前要确认用户意图。

2.3 用到的参数描述：SKILL_MANAGE_SCHEMA.parameters

模型还会看到参数级 description。

英文原文和中文对照：

action: The action to perform.
action：要执行的动作。

name: Skill name (lowercase, hyphens/underscores, max 64 chars). Must match an existing skill for patch/edit/delete/write_file/remove_file.
name：skill 名称。小写，可用连字符或下划线，最长 64 字符。patch/edit/delete/write_file/remove_file 时必须匹配已有 skill。

content: Full SKILL.md content (YAML frontmatter + markdown body). Required for 'create' and 'edit'. For 'edit', read the skill first with skill_view() and provide the complete updated text.
content：完整 SKILL.md 内容，包括 YAML frontmatter 和 Markdown body。create 和 edit 必填。edit 前要先用 skill_view() 读取 skill，并提供完整更新后的文本。

old_string: Text to find in the file (required for 'patch'). Must be unique unless replace_all=true. Include enough surrounding context to ensure uniqueness.
old_string：patch 时要查找的文本，必填。除非 replace_all=true，否则必须唯一。要包含足够上下文来保证唯一性。

new_string: Replacement text (required for 'patch'). Can be empty string to delete the matched text.
new_string：patch 的替换文本，必填。可以为空字符串，用于删除匹配文本。

replace_all: For 'patch': replace all occurrences instead of requiring a unique match (default: false).
replace_all：patch 时替换所有匹配，而不是要求唯一匹配。默认 false。

category: Optional category/domain for organizing the skill (e.g., 'devops', 'data-science', 'mlops'). Creates a subdirectory grouping. Only used with 'create'.
category：可选 category/domain，用于组织 skill，例如 devops、data-science、mlops。会创建子目录分组。仅 create 使用。

file_path: Path to a supporting file within the skill directory. For 'write_file'/'remove_file': required, must be under references/, templates/, scripts/, or assets/. For 'patch': optional, defaults to SKILL.md if omitted.
file_path：skill 目录内 supporting file 的路径。write_file/remove_file 必填，且必须位于 references/、templates/、scripts/ 或 assets/ 下。patch 时可选，不填则默认 patch SKILL.md。

file_content: Content for the file. Required for 'write_file'.
file_content：文件内容。write_file 必填。

absorbed_into: For 'delete' only — declares intent so the curator can tell consolidation from pruning without guessing. Pass the umbrella skill name when this skill's content was merged into another (the target must already exist). Pass an empty string when the skill is truly stale and being pruned with no forwarding target. Omitting the arg on delete is supported for backward compatibility but downstream tooling (e.g. cron-job skill reference rewriting) will have to guess at intent.
absorbed_into：仅 delete 使用，用于声明删除意图，让 curator 不靠猜测地区分合并和裁剪。如果这个 skill 的内容已合并进另一个 umbrella skill，传 umbrella skill 名称（目标必须已存在）。如果这个 skill 确实过时并且无转发目标，传空字符串。delete 时省略该参数仍兼容旧行为，但下游工具（例如 cron-job skill 引用改写）就只能猜测意图。

3. 场景：复杂任务成功后创建 skill

看一个普通对话。

用户：帮我写一篇 Hermes memory 系统实现分析文档。要按场景讲，涉及到的 prompt 和 tool description 都要给英文原文和中文对照。

助手：经过多轮修改，完成了 V5/V6 文档，并验证了关键 prompt、tool schema、Markdown 代码块和版本字样。

用户：这个写法以后可以复用。

模型根据 SKILLS_GUIDANCE 和 SKILL_MANAGE_SCHEMA.description 判断：

这是复杂任务，经历了多轮修改。
产出了一套稳定写法：场景化、prompt 就地展开、中英文对照、最后静态检查。
这不是“用户是谁”的事实，而是“如何写这类文档”的流程。
应该创建 skill。

可能的 tool call：

{
  "action": "create",
  "name": "implementation-analysis-docs",
  "category": "writing",
  "content": "---\nname: implementation-analysis-docs\ndescription: Write implementation analysis documents for developer readers using scenario-first explanations, inline prompts/tool descriptions, and verification checks.\n---\n\n# Implementation Analysis Docs\n\nUse this skill when writing a developer-facing implementation analysis document for an agent/tooling system.\n\n## Steps\n\n1. Start from concrete user-facing scenarios, not source-file order.\n2. For each behavior, explain what the model sees: system prompt, tool description, parameters, and runtime state.\n3. Put complete prompt/tool description excerpts next to the scenario where they are used.\n4. Include English originals and Chinese explanations when the user asks for bilingual prompt analysis.\n5. End with a full flow replay and verification checklist.\n\n## Pitfalls\n\n- Do not turn the article into a source-code tour.\n- Do not collect all prompts in a detached appendix when the user wants scenario-first reading.\n- Do not save one-off task status as a skill.\n\n## Verification\n\n- Check Markdown fences are balanced.\n- Search for accidental version-comparison words when the article should be standalone.\n- Search for required prompt/schema names."
}

写入位置：

~/.hermes/skills/writing/implementation-analysis-docs/SKILL.md

注意：前台 skill_manage(create) 的 description 里写了“Confirm with user before creating/deleting”。所以如果用户没有明确说“可以复用/保存为 skill”，模型更稳妥的做法是先问是否保存，或者在后台 review 中由 review agent 处理。

4. 场景：使用 skill 时发现过时，立即 patch

另一个场景：

用户：用 implementation-analysis-docs 这个 skill 继续写 skills 进化机制文章。

助手加载 skill 后，文章初稿把所有 prompt 放到了文末。

用户：不要把 prompt 汇总到文末，用到的时候就给原文和中文对照。

模型根据 SKILLS_GUIDANCE 判断：

我使用了一个 skill。
用户指出 skill 产出的写法不符合预期。
这说明 skill 的说明不完整。
应该立即 patch，而不是只在当前回答里改一次。

tool call：

{
  "action": "patch",
  "name": "implementation-analysis-docs",
  "old_string": "Include English originals and Chinese explanations when the user asks for bilingual prompt analysis.",
  "new_string": "Include English originals and Chinese explanations when the user asks for bilingual prompt analysis. Place each prompt or tool description beside the scenario where it is used, not in a detached appendix."
}

patch 使用 old_string/new_string。实现上它会：

找到 skill
  ↓
默认 patch SKILL.md
  ↓
用 fuzzy_find_and_replace 查找 old_string
  ↓
默认要求唯一匹配
  ↓
patch 后重新校验 SKILL.md frontmatter
  ↓
原子写入
  ↓
记录 patch telemetry

这就是 skill 进化最核心的闭环：

skill 被使用
  ↓
现实任务暴露缺陷
  ↓
用户纠正或模型发现坑点
  ↓
模型 patch skill
  ↓
下次加载时直接使用修正后的流程

5. 场景：把长细节放进 references/templates/scripts

如果所有内容都写进 SKILL.md，skill 会越来越长，难以搜索和使用。Hermes 的设计是：SKILL.md 保存主流程，长细节放到 supporting files。

场景：

用户：这次我们分析 skills 进化机制时，涉及 curator prompt、skill_manage schema、skill_view schema。以后写类似文章，可以把长 prompt 放到参考文件，不要挤满主流程。

模型判断：

这是这类任务的可复用参考资料。
但内容太长，不适合全部塞进 SKILL.md。
应该在已有 skill 下新增 references 文件，并在 SKILL.md 里留一行指针。

tool call：

{
  "action": "write_file",
  "name": "implementation-analysis-docs",
  "file_path": "references/hermes-agent-prompts.md",
  "file_content": "# Hermes Agent Prompt References\n\nUse this reference when writing implementation-analysis docs for Hermes Agent internals.\n\n## Skills guidance\n\nSKILLS_GUIDANCE tells the model to save complex workflows as skills and patch outdated skills immediately.\n\n## Review prompts\n\n_BACKGROUND skill review prompts prioritize updating loaded skills, then existing umbrellas, then support files, then new class-level umbrellas."
}

再 patch SKILL.md：

{
  "action": "patch",
  "name": "implementation-analysis-docs",
  "old_string": "## Verification\n\n- Check Markdown fences are balanced.",
  "new_string": "## References\n\n- Load `references/hermes-agent-prompts.md` when the article needs Hermes-specific prompt or schema details.\n\n## Verification\n\n- Check Markdown fences are balanced."
}

目录结构会变成：

~/.hermes/skills/writing/implementation-analysis-docs/
  SKILL.md
  references/
    hermes-agent-prompts.md
  templates/
  scripts/
  assets/

supporting files 的分工：

references/：错误记录、复现步骤、provider quirks、API 摘录、领域笔记。
templates/：可复制再修改的起始文件。
scripts/：可以直接运行的验证、fixture 生成、探测脚本。
assets/：图片、二进制或其他资源。

6. 场景：模型如何选中要加载的 skill

很多人会以为模型选择 skill 完全依赖 skills_list。实际上不是。

Hermes 有一个更前置的机制：只要当前工具集合里存在 skills_list、skill_view 或 skill_manage 之一，run_agent.py 就会调用 build_skills_system_prompt()，把一个紧凑的 skills index 注入 system prompt。

这个 index 会把可用 skills 按 category 列出来：

<available_skills>
  writing:
    - implementation-analysis-docs: Write implementation analysis documents for developer readers using scenario-first explanations...
  devops:
    - docker-debugging: Debug Docker build and runtime failures...
</available_skills>

所以模型选中 skill 的第一入口通常是：

模型先读 system prompt
  ↓
看到 ## Skills (mandatory)
  ↓
扫描 <available_skills> 里的 name + description
  ↓
判断某个 skill 和当前任务匹配或部分相关
  ↓
调用 skill_view(name) 加载完整 SKILL.md

skills_list 不是唯一入口。它更像补充发现工具：当模型需要按 category 浏览、确认是否还有其他 skill，或 system prompt index 不够细时，再调用 skills_list。

6.1 用到的 system prompt：build_skills_system_prompt

英文原文：

## Skills (mandatory)
Before replying, scan the skills below. If a skill matches or is even partially relevant to your task, you MUST load it with skill_view(name) and follow its instructions. Err on the side of loading — it is always better to have context you don't need than to miss critical steps, pitfalls, or established workflows. Skills contain specialized knowledge — API endpoints, tool-specific commands, and proven workflows that outperform general-purpose approaches. Load the skill even if you think you could handle the task with basic tools like web_search or terminal. Skills also encode the user's preferred approach, conventions, and quality standards for tasks like code review, planning, and testing — load them even for tasks you already know how to do, because the skill defines how it should be done here.
Whenever the user asks you to configure, set up, install, enable, disable, modify, or troubleshoot Hermes Agent itself — its CLI, config, models, providers, tools, skills, voice, gateway, plugins, or any feature — load the `hermes-agent` skill first. It has the actual commands (e.g. `hermes config set …`, `hermes tools`, `hermes setup`) so you don't have to guess or invent workarounds.
If a skill has issues, fix it with skill_manage(action='patch').
After difficult/iterative tasks, offer to save as a skill. If a skill you loaded was missing steps, had wrong commands, or needed pitfalls you discovered, update it before finishing.

<available_skills>
{index_lines}
</available_skills>

Only proceed without loading a skill if genuinely none are relevant to the task.

中文对照：

## Skills（强制）
回复前，请扫描下面的 skills。如果某个 skill 与当前任务匹配，甚至只是部分相关，你必须用 skill_view(name) 加载它，并遵循它的说明。倾向于加载：拥有不需要的上下文，总比错过关键步骤、坑点或已建立 workflow 更好。Skills 包含专门知识，例如 API endpoints、工具特定命令，以及比通用方法更有效的已验证 workflow。即使你认为自己可以用 web_search 或 terminal 这类基础工具完成任务，也要加载 skill。Skills 还编码了用户在 code review、planning、testing 等任务上的偏好方法、约定和质量标准；即使你已经知道怎么做这类任务，也要加载它，因为 skill 定义了“在这里应该怎么做”。
每当用户要求你配置、设置、安装、启用、禁用、修改或排查 Hermes Agent 本身，例如 CLI、config、models、providers、tools、skills、voice、gateway、plugins 或任何功能时，先加载 `hermes-agent` skill。它有实际命令，例如 `hermes config set ...`、`hermes tools`、`hermes setup`，所以你不需要猜测或发明 workaround。
如果某个 skill 有问题，用 skill_manage(action='patch') 修复它。
在困难或迭代型任务后，主动提出保存为 skill。如果你加载的 skill 缺步骤、命令错误，或需要补充你发现的坑点，在结束前更新它。

<available_skills>
{index_lines}
</available_skills>

只有在确实没有任何 skill 与任务相关时，才可以不加载 skill 继续。

这段 prompt 对模型的约束很强：

不是“可以加载 skill”。
而是“匹配或部分相关就必须加载 skill_view(name)”。

6.2 选中 skill 的通俗例子

用户说：

用户：继续写一篇 Hermes session_search 的实现分析文档。

模型在 system prompt 的 <available_skills> 里看到：

writing:
  - implementation-analysis-docs: Write implementation analysis documents for developer readers using scenario-first explanations, inline prompts/tool descriptions, and verification checks.

模型判断：

用户要写实现分析文档。
这个 skill 的 description 正好覆盖“implementation analysis documents”。
根据 ## Skills (mandatory)，它部分相关也必须加载。

因此直接调用：

{
  "name": "implementation-analysis-docs"
}

也就是说，这条路径不需要先调用 skills_list。skills_list 只在模型需要进一步浏览 skill landscape 时才必要。

6.3 用户显式 /skill-name 时不靠模型选择

还有一种路径：用户直接输入 slash skill。

用户：/implementation-analysis-docs 继续写 session_search 文档

这时不是模型先判断要不要加载。Hermes runtime 会解析 /implementation-analysis-docs，找到对应 skill，并调用 build_skill_invocation_message() 生成一段注入内容。

用到的 activation note 英文原文：

[IMPORTANT: The user has invoked the "{skill_name}" skill, indicating they want you to follow its instructions. The full skill content is loaded below.]

中文对照：

[重要：用户已经调用了 "{skill_name}" skill，这表示用户希望你遵循它的说明。完整 skill 内容已加载在下面。]

这条路径会把下面内容放进当前上下文：

完整 SKILL.md 内容
Skill directory 绝对路径
supporting files 列表
如何用 skill_view(name, file_path) 读取 linked files
如何直接运行 scripts 的提示

所以 /skill-name 是用户显式指定，runtime 直接注入，不需要模型通过 skills_list 或 system prompt index 选择。

7. 场景：下一次任务如何复用 skill

skill 不是自动塞满 system prompt。Hermes 采用按需加载。

有三种常见路径：

模型根据 system prompt 的 <available_skills> 发现候选 skill。
模型调用 skill_view 加载完整 SKILL.md 或 supporting file。
模型需要补充浏览时，调用 skills_list。
用户显式输入 /skill-name 时，runtime 直接注入 skill。

7.1 用到的工具描述：SKILLS_LIST_SCHEMA.description

英文原文：

List available skills (name + description). Use skill_view(name) to load full content.

中文对照：

列出可用 skills（名称 + 描述）。使用 skill_view(name) 加载完整内容。

参数描述：

category: Optional category filter to narrow results
category：可选 category 过滤器，用来缩小结果范围。

skills_list 只返回轻量元数据，避免模型一上来加载大量 SKILL.md。它不是唯一选择入口；system prompt 的 <available_skills> 已经给了模型一份紧凑索引。

7.2 用到的工具描述：SKILL_VIEW_SCHEMA.description

英文原文：

Skills allow for loading information about specific tasks and workflows, as well as scripts and templates. Load a skill's full content or access its linked files (references, templates, scripts). First call returns SKILL.md content plus a 'linked_files' dict showing available references/templates/scripts. To access those, call again with file_path parameter.

中文对照：

Skills 用来加载特定任务和 workflow 的信息，也可以加载 scripts 和 templates。可以加载某个 skill 的完整内容，或访问它的 linked files（references、templates、scripts）。第一次调用返回 SKILL.md 内容，并带上 `linked_files` 字典，展示可用的 references/templates/scripts。要访问这些文件，需要再次带 file_path 参数调用。

参数描述：

name: The skill name (use skills_list to see available skills). For plugin-provided skills, use the qualified form 'plugin:skill' (e.g. 'superpowers:writing-plans').
name：skill 名称。可用 skills_list 查看可用 skills。插件提供的 skills 使用限定形式 `plugin:skill`，例如 `superpowers:writing-plans`。

file_path: OPTIONAL: Path to a linked file within the skill (e.g., 'references/api.md', 'templates/config.yaml', 'scripts/validate.py'). Omit to get the main SKILL.md content.
file_path：可选。skill 内 linked file 的路径，例如 `references/api.md`、`templates/config.yaml`、`scripts/validate.py`。省略时获取主 SKILL.md 内容。

7.3 复用链路例子

用户说：

用户：继续写一篇 Hermes session_search 的实现分析文档。

模型通常会先从 system prompt 的 <available_skills> 看到候选 skill。如果它还想确认 writing 类别下还有没有其他候选，可能再查：

{
  "category": "writing"
}

发现：

implementation-analysis-docs: Write implementation analysis documents for developer readers using scenario-first explanations...

然后加载：

{
  "name": "implementation-analysis-docs"
}

如果 linked_files 里出现：

references/hermes-agent-prompts.md

模型还可以继续加载：

{
  "name": "implementation-analysis-docs",
  "file_path": "references/hermes-agent-prompts.md"
}

如果用户直接输入 /implementation-analysis-docs，Hermes 会通过 slash command 加载 skill，把 SKILL.md 内容格式化成一段 skill invocation message。这个消息会包含：

skill 内容
Skill directory 绝对路径
supporting files 列表
如何用 skill_view 读取 linked file
如何运行 scripts 的提示

所以 skill 的复用不是“模型凭记忆想起”，而是明确加载文件内容，让当前 LLM 请求看到这套流程。

8. 场景：后台 review 补漏并推动进化

有时主 Agent 忙着完成任务，没有主动创建或 patch skill。Hermes 会在长任务后触发后台 review。

触发逻辑可以概括为：

每个 tool loop iteration 后计数
  ↓
如果 skill_manage 一直没被用
  ↓
计数达到 creation_nudge_interval
  ↓
默认 creation_nudge_interval = 10
  ↓
本轮结束后 spawn background review
  ↓
后台 review 根据对话判断是否更新 skill library

后台 review 发生在最终回答之后，不阻塞用户当前任务。

8.1 用到的后台提示词：_SKILL_REVIEW_PROMPT

英文原文：

Review the conversation above and update the skill library. Be ACTIVE — most sessions produce at least one skill update, even if small. A pass that does nothing is a missed learning opportunity, not a neutral outcome.

Target shape of the library: CLASS-LEVEL skills, each with a rich SKILL.md and a `references/` directory for session-specific detail. Not a long flat list of narrow one-session-one-skill entries. This shapes HOW you update, not WHETHER you update.

Signals to look for (any one of these warrants action):
  • User corrected your style, tone, format, legibility, or verbosity. Frustration signals like 'stop doing X', 'this is too verbose', 'don't format like this', 'why are you explaining', 'just give me the answer', 'you always do Y and I hate it', or an explicit 'remember this' are FIRST-CLASS skill signals, not just memory signals. Update the relevant skill(s) to embed the preference so the next session starts already knowing.
  • User corrected your workflow, approach, or sequence of steps. Encode the correction as a pitfall or explicit step in the skill that governs that class of task.
  • Non-trivial technique, fix, workaround, debugging path, or tool-usage pattern emerged that a future session would benefit from. Capture it.
  • A skill that got loaded or consulted this session turned out to be wrong, missing a step, or outdated. Patch it NOW.

Preference order — prefer the earliest action that fits, but do pick one when a signal above fired:
  1. UPDATE A CURRENTLY-LOADED SKILL. Look back through the conversation for skills the user loaded via /skill-name or you read via skill_view. If any of them covers the territory of the new learning, PATCH that one first. It is the skill that was in play, so it's the right one to extend.
  2. UPDATE AN EXISTING UMBRELLA (via skills_list + skill_view). If no loaded skill fits but an existing class-level skill does, patch it. Add a subsection, a pitfall, or broaden a trigger.
  3. ADD A SUPPORT FILE under an existing umbrella. Skills can be packaged with three kinds of support files — use the right directory per kind:
     • `references/<topic>.md` — session-specific detail (error transcripts, reproduction recipes, provider quirks) AND condensed knowledge banks: quoted research, API docs, external authoritative excerpts, or domain notes you found while working on the problem. Write it concise and for the value of the task, not as a full mirror of upstream docs.
     • `templates/<name>.<ext>` — starter files meant to be copied and modified (boilerplate configs, scaffolding, a known-good example the agent can `reproduce with modifications`).
     • `scripts/<name>.<ext>` — statically re-runnable actions the skill can invoke directly (verification scripts, fixture generators, deterministic probes, anything the agent should run rather than hand-type each time).
     Add support files via skill_manage action=write_file with file_path starting 'references/', 'templates/', or 'scripts/'. The umbrella's SKILL.md should gain a one-line pointer to any new support file so future agents know it exists.
  4. CREATE A NEW CLASS-LEVEL UMBRELLA SKILL when no existing skill covers the class. The name MUST be at the class level. The name MUST NOT be a specific PR number, error string, feature codename, library-alone name, or 'fix-X / debug-Y / audit-Z-today' session artifact. If the proposed name only makes sense for today's task, it's wrong — fall back to (1), (2), or (3).

User-preference embedding (important): when the user expressed a style/format/workflow preference, the update belongs in the SKILL.md body, not just in memory. Memory captures 'who the user is and what the current situation and state of your operations are'; skills capture 'how to do this class of task for this user'. When they complain about how you handled a task, the skill that governs that task needs to carry the lesson.

If you notice two existing skills that overlap, note it in your reply — the background curator handles consolidation at scale.

'Nothing to save.' is a real option but should NOT be the default. If the session ran smoothly with no corrections and produced no new technique, just say 'Nothing to save.' and stop. Otherwise, act.

中文对照：

审查上面的对话，并更新 skill library。要主动：大多数 session 至少会产生一个 skill 更新，哪怕很小。什么都不做通常是错过学习机会，而不是中性结果。

Skill library 的目标形态：类级别 skills，每个都有丰富的 SKILL.md 和 `references/` 目录用于保存 session 特定细节。不要做成长长一串狭窄的“一次 session 一个 skill”的条目。这决定的是如何更新，而不是是否更新。

要寻找的信号（任意一个都值得行动）：
  • 用户纠正了你的风格、语气、格式、可读性或冗长度。像 “stop doing X”、“this is too verbose”、“don't format like this”、“why are you explaining”、“just give me the answer”、“you always do Y and I hate it”，或明确的 “remember this”，都是第一类 skill 信号，不只是 memory 信号。要更新相关 skill，把偏好嵌进去，让下个 session 一开始就知道。
  • 用户纠正了你的 workflow、方法或步骤顺序。把这个纠正编码为管这类任务的 skill 里的 pitfall 或明确步骤。
  • 出现了未来 session 会受益的非平凡技巧、修复、workaround、调试路径或工具使用模式。捕获它。
  • 本 session 加载或查看过的 skill 被发现错误、缺步骤或过时。现在就 patch。

优先顺序：优先选择最早匹配的动作，但只要上面的信号出现，就要选一个动作：
  1. 更新当前已加载的 skill。回看对话里用户通过 /skill-name 加载过，或你通过 skill_view 读过的 skills。如果其中某个覆盖了新经验，优先 PATCH 它。它本来就在发挥作用，所以它是正确扩展位置。
  2. 更新已有 umbrella。通过 skills_list + skill_view 找到已有类级别 skill。如果没有已加载 skill 匹配，但已有 class-level skill 匹配，就 patch 它，添加小节、pitfall 或扩展 trigger。
  3. 在已有 umbrella 下添加 support file。Skills 可以带三类 support files，要放到正确目录：
     • `references/<topic>.md`：session 特定细节，例如错误 transcript、复现 recipe、provider quirks；也可以是压缩后的知识库，例如引用研究、API docs、外部权威摘录或领域笔记。要写得简洁并面向任务价值，不要完整镜像上游文档。
     • `templates/<name>.<ext>`：可复制并修改的 starter files，例如 boilerplate configs、scaffolding、已知可用示例。
     • `scripts/<name>.<ext>`：可静态重复运行的动作，例如验证脚本、fixture generators、deterministic probes，任何 agent 应该直接运行而不是每次手写的东西。
     用 skill_manage action=write_file 添加 support files，file_path 以 references/、templates/ 或 scripts/ 开头。umbrella 的 SKILL.md 应添加一行指针，让未来 agents 知道新 support file 存在。
  4. 当没有任何已有 skill 覆盖这个类别时，创建新的类级别 umbrella skill。名称必须是类别级别。名称不能是具体 PR 编号、错误字符串、feature codename、单独库名，或 “fix-X / debug-Y / audit-Z-today” 这种 session artifact。如果名字只适合今天的任务，就是错的，应回到 (1)、(2) 或 (3)。

用户偏好嵌入（重要）：当用户表达风格、格式或 workflow 偏好时，更新应进入 SKILL.md 正文，而不只是 memory。Memory 捕获“用户是谁，以及你当前操作的情况和状态”；skills 捕获“如何为这个用户完成这一类任务”。当用户抱怨你处理任务的方式时，管这类任务的 skill 需要承载这个经验。

如果你发现两个已有 skills 重叠，提一下；后台 curator 会规模化处理合并。

“Nothing to save.” 是真实选项，但不应该是默认。如果 session 顺利、没有纠正、没有产生新技巧，就只说 “Nothing to save.” 并停止。否则，要行动。

8.2 用到的后台联合提示词：_COMBINED_REVIEW_PROMPT

当 memory 和 skill 都有信号时，Hermes 使用 combined review prompt。这里重点看 skill 部分。

英文原文：

Review the conversation above and update two things:

**Memory**: who the user is. Did the user reveal persona, desires, preferences, personal details, or expectations about how you should behave? Save facts about the user and durable preferences with the memory tool.

**Skills**: how to do this class of task. Be ACTIVE — most sessions produce at least one skill update. A pass that does nothing is a missed learning opportunity, not a neutral outcome.

Target shape of the skill library: CLASS-LEVEL skills with a rich SKILL.md and a `references/` directory for session-specific detail. Not a long flat list of narrow one-session-one-skill entries.

Signals that warrant a skill update (any one is enough):
  • User corrected your style, tone, format, legibility, verbosity, or approach. Frustration is a FIRST-CLASS skill signal, not just a memory signal. 'stop doing X', 'don't format like this', 'I hate when you Y' — embed the lesson in the skill that governs that task so the next session starts fixed.
  • Non-trivial technique, fix, workaround, or debugging path emerged.
  • A skill that was loaded or consulted turned out wrong, missing, or outdated — patch it now.

Preference order for skills — pick the earliest that fits:
  1. UPDATE A CURRENTLY-LOADED SKILL. Check what skills were loaded via /skill-name or skill_view in the conversation. If one of them covers the learning, PATCH it first. It was in play; it's the right place.
  2. UPDATE AN EXISTING UMBRELLA (skills_list + skill_view to find the right one). Patch it.
  3. ADD A SUPPORT FILE under an existing umbrella via skill_manage action=write_file. Three kinds: `references/<topic>.md` for session-specific detail OR condensed knowledge banks (quoted research, API docs excerpts, domain notes) written concise and task-focused; `templates/<name>.<ext>` for starter files meant to be copied and modified; `scripts/<name>.<ext>` for statically re-runnable actions (verification, fixture generators, probes). Add a one-line pointer in SKILL.md so future agents find them.
  4. CREATE A NEW CLASS-LEVEL UMBRELLA when nothing exists. Name at the class level — NOT a PR number, error string, codename, library-alone name, or 'fix-X / debug-Y' session artifact. If the name only fits today's task, fall back to (1), (2), or (3).

User-preference embedding: when the user complains about how you handled a task, update the skill that governs that task — memory alone isn't enough. Memory says 'who the user is and what the current situation and state of your operations are'; skills say 'how to do this class of task for this user'. Both should carry user-preference lessons when relevant.

If you notice overlapping existing skills, mention it — the background curator handles consolidation.

Act on whichever of the two dimensions has real signal. If genuinely nothing stands out on either, say 'Nothing to save.' and stop — but don't reach for that conclusion as a default.

中文对照：

审查上面的对话，并更新两类内容：

**Memory**：用户是谁。用户是否透露 persona、愿望、偏好、个人细节，或对你行为方式的期望？请用 memory 工具保存关于用户和长期偏好的事实。

**Skills**：如何完成这一类任务。要主动：大多数 session 至少会产生一个 skill 更新。什么都不做通常是错过学习机会，而不是中性结果。

Skill library 的目标形态：类级别 skills，带有丰富的 SKILL.md 和 `references/` 目录用于保存 session 特定细节。不要做成长长一串狭窄的“一次 session 一个 skill”的条目。

值得更新 skill 的信号（任意一个就足够）：
  • 用户纠正了你的风格、语气、格式、可读性、冗长度或方法。用户不满是第一类 skill 信号，不只是 memory 信号。比如 “stop doing X”、“don't format like this”、“I hate when you Y”——把这个经验嵌入管这类任务的 skill，让下个 session 一开始就是修正后的状态。
  • 出现了非平凡技巧、修复、workaround 或调试路径。
  • 已加载或查看过的 skill 被发现错误、缺失或过时——现在就 patch。

Skill 优先顺序：选择最早匹配的一项：
  1. 更新当前已加载的 skill。检查对话中通过 /skill-name 或 skill_view 加载过的 skills。如果其中一个覆盖了这次学习内容，先 PATCH 它。它本来就在发挥作用，所以它是正确位置。
  2. 更新已有 umbrella。通过 skills_list + skill_view 找到合适的已有 umbrella，并 patch 它。
  3. 在已有 umbrella 下通过 skill_manage action=write_file 添加 support file。三类：`references/<topic>.md` 保存 session 特定细节或压缩知识库；`templates/<name>.<ext>` 保存可复制修改的 starter files；`scripts/<name>.<ext>` 保存可静态重复运行的动作。还要在 SKILL.md 里加一行指针，让未来 agents 找得到。
  4. 如果没有合适 skill，创建新的类级别 umbrella。名称必须是类别级别，不要用 PR 编号、错误字符串、codename 或 “fix-X / debug-Y” 这种 session artifact。如果名字只适合今天任务，就回到 (1)、(2) 或 (3)。

用户偏好嵌入：当用户抱怨你如何处理任务时，要更新管这类任务的 skill——只写 memory 不够。Memory 说明“用户是谁，以及你当前操作的情况和状态”；skills 说明“如何为这个用户完成这一类任务”。相关时，两者都应该承载用户偏好经验。

如果发现已有 skills 重叠，提一下——后台 curator 会处理合并。

根据两个维度里的真实信号行动。如果确实两边都没有值得保存的内容，就说 “Nothing to save.” 并停止——但不要默认得出这个结论。

9. 场景：skill 库越来越多，curator 如何治理

如果每次任务都创建一个很窄的 skill，skill 库会爆炸。Hermes 用 curator 做长期治理。

场景：

一段时间后，skill 库里出现：
- memory-doc-v5-fix
- memory-doc-v6-provider
- session-search-doc
- harness-analysis-doc

这些名字都很窄，很多内容其实都属于“实现分析文档写作”这个 umbrella。

curator 的目标不是简单找重复，而是把一次性 narrow skills 合并成 class-level umbrella。

9.1 用到的 curator prompt：CURATOR_REVIEW_PROMPT

英文原文：

You are running as Hermes' background skill CURATOR. This is an UMBRELLA-BUILDING consolidation pass, not a passive audit and not a duplicate-finder.

The goal of the skill collection is a LIBRARY OF CLASS-LEVEL INSTRUCTIONS AND EXPERIENTIAL KNOWLEDGE. A collection of hundreds of narrow skills where each one captures one session's specific bug is a FAILURE of the library — not a feature. An agent searching skills matches on descriptions, not on exact names; one broad umbrella skill with labeled subsections beats five narrow siblings for discoverability, not the other way around.

The right target shape is CLASS-LEVEL skills with rich SKILL.md bodies + `references/`, `templates/`, and `scripts/` subfiles for session-specific detail — not one-session-one-skill micro-entries.

Hard rules — do not violate:
1. DO NOT touch bundled or hub-installed skills. The candidate list below is already filtered to agent-created skills only.
2. DO NOT delete any skill. Archiving (moving the skill's directory into ~/.hermes/skills/.archive/) is the maximum destructive action. Archives are recoverable; deletion is not.
3. DO NOT touch skills shown as pinned=yes. Skip them entirely.
4. DO NOT use usage counters as a reason to skip consolidation. The counters are new and often mostly zero. Judge overlap on CONTENT, not on use_count. 'use=0' is not evidence a skill is valuable; it's absence of evidence either way.
5. DO NOT reject consolidation on the grounds that 'each skill has a distinct trigger'. Pairwise distinctness is the wrong bar. The right bar is: 'would a human maintainer write this as N separate skills, or as one skill with N labeled subsections?' When the answer is the latter, merge.

How to work — not optional:
1. Scan the full candidate list. Identify PREFIX CLUSTERS (skills sharing a first word or domain keyword). Examples you are likely to find: hermes-config-*, hermes-dashboard-*, gateway-*, codex-*, ollama-*, anthropic-*, gemini-*, mcp-*, salvage-*, pr-*, competitor-*, python-*, security-*, etc. Expect 10-25 clusters.
2. For each cluster with 2+ members, do NOT ask 'are these pairs overlapping?' — ask 'what is the UMBRELLA CLASS these skills all serve? Would a maintainer name that class and write one skill for it?' If yes, pick (or create) the umbrella and absorb the siblings into it.
3. Three ways to consolidate — use the right one per cluster:
   a. MERGE INTO EXISTING UMBRELLA — one skill in the cluster is already broad enough to be the umbrella (example: `pr-triage-salvage` for the PR review cluster). Patch it to add a labeled section for each sibling's unique insight, then archive the siblings.
   b. CREATE A NEW UMBRELLA SKILL.md — no existing member is broad enough. Use skill_manage action=create to write a new class-level skill whose SKILL.md covers the shared workflow and has short labeled subsections. Archive the now-absorbed narrow siblings.
   c. DEMOTE TO REFERENCES/TEMPLATES/SCRIPTS — a sibling has narrow-but-valuable session-specific content. Move it into the umbrella's appropriate support directory:
      • `references/<topic>.md` for session-specific detail OR condensed knowledge banks (quoted research, API docs excerpts, domain notes, provider quirks, reproduction recipes)
      • `templates/<name>.<ext>` for starter files meant to be copied and modified
      • `scripts/<name>.<ext>` for statically re-runnable actions (verification scripts, fixture generators, probes)
      Then archive the old sibling. Use `terminal` with `mkdir -p ~/.hermes/skills/<umbrella>/references/ && mv ... <umbrella>/references/<topic>.md` (or templates/ / scripts/).
4. Also flag skills whose NAME is too narrow (contains a PR number, a feature codename, a specific error string, an 'audit' / 'diagnosis' / 'salvage' session artifact). These almost always belong as a subsection or support file under a class-level umbrella.
5. Iterate. After one consolidation round, scan the remaining set and look for the NEXT umbrella opportunity. Don't stop after 3 merges.

Your toolset:
  - skills_list, skill_view        — read the current landscape
  - skill_manage action=patch      — add sections to the umbrella
  - skill_manage action=create     — create a new umbrella SKILL.md
  - skill_manage action=write_file — add a references/, templates/, or scripts/ file under an existing skill (the skill must already exist)
  - skill_manage action=delete     — archive a skill. MUST pass `absorbed_into=<umbrella>` when you've merged its content into another skill, or `absorbed_into=""` when you're truly pruning with no forwarding target. This drives cron-job skill-reference migration — guessing from your YAML summary after the fact is fragile.
  - terminal                       — mv a sibling into the archive OR move its content into a support subfile

'keep' is a legitimate decision ONLY when the skill is already a class-level umbrella and none of the proposed merges would improve discoverability. 'This is narrow but distinct from its siblings' is NOT a reason to keep — it's a reason to move it under an umbrella as a subsection or support file.

Expected output: real umbrella-ification. Process every obvious cluster. If you end the pass with fewer than 10 archives, you stopped too early — go back and look at the clusters you left alone.

When done, write a human summary AND a structured machine-readable block so downstream tooling can distinguish consolidation from pruning. Format EXACTLY:

## Structured summary (required)
```yaml
consolidations:
  - from: <old-skill-name>
    into: <umbrella-skill-name>
    reason: <one short sentence — why merged, not just 'similar'>
prunings:
  - name: <skill-name>
    reason: <one short sentence — why archived with no merge target>
```

Every skill you moved to .archive/ MUST appear in exactly one of the two lists. If you consolidated X into umbrella Y (patched Y, wrote a references file to Y, or created Y with X's content absorbed), X goes under `consolidations` with `into: Y`. If you archived X with no absorption — truly stale, irrelevant, or obsolete — X goes under `prunings`. Leave a list empty (`consolidations: []`) if none. Do not omit the block. The block comes AFTER your human-readable summary of clusters processed, patches made, and decisions left alone.

中文对照：

你正在作为 Hermes 的后台 skill CURATOR 运行。这是一次构建 umbrella 的合并整理，不是被动审计，也不是重复项查找器。

skill collection 的目标是“类级别指令和经验知识库”。如果有数百个狭窄 skills，每个都只记录某个 session 的具体 bug，那是 skill 库的失败，不是特性。Agent 搜索 skills 时匹配 description，而不是精确名称；一个带有标记小节的宽 umbrella skill，在可发现性上胜过五个狭窄兄弟，而不是反过来。

正确目标形态是：类级别 skills，带有丰富 SKILL.md 正文，以及 `references/`、`templates/`、`scripts/` 子文件保存 session 特定细节；不要做成“一次 session 一个 skill”的 micro entries。

硬性规则，不得违反：
1. 不要触碰 bundled 或 hub-installed skills。候选列表已经过滤为仅 agent-created skills。
2. 不要删除任何 skill。最大破坏性动作是归档，也就是把 skill 目录移到 ~/.hermes/skills/.archive/。归档可恢复，删除不可恢复。
3. 不要触碰 pinned=yes 的 skills。直接跳过。
4. 不要用 usage counters 作为跳过合并的理由。这些计数很新，很多接近 0。要根据内容判断重叠，而不是 use_count。use=0 不是 skill 有价值的证据，也不是无价值的证据，只是缺少证据。
5. 不要因为“每个 skill 有不同 trigger”就拒绝合并。两两不同不是正确标准。正确标准是：“人类维护者会把它写成 N 个独立 skills，还是一个带 N 个标记小节的 skill？” 如果答案是后者，就合并。

工作方式，必须遵守：
1. 扫描完整候选列表。识别 prefix clusters，即共享首词或领域关键词的 skills。常见例子包括 hermes-config-*、hermes-dashboard-*、gateway-*、codex-*、ollama-*、anthropic-*、gemini-*、mcp-*、salvage-*、pr-*、competitor-*、python-*、security-* 等。预计会有 10-25 个 clusters。
2. 对每个有 2 个以上成员的 cluster，不要问“这些 pair 是否重叠？”；要问“这些 skills 共同服务的 umbrella class 是什么？维护者会给这个 class 命名并写一个 skill 吗？” 如果会，就选择或创建 umbrella，并吸收兄弟 skills。
3. 三种合并方式，按 cluster 选择合适的一种：
   a. 合并进已有 umbrella。cluster 中已有一个 skill 足够宽，可以作为 umbrella。patch 它，为每个兄弟的独特经验添加标记小节，然后归档兄弟 skills。
   b. 创建新的 umbrella SKILL.md。没有已有成员足够宽。用 skill_manage action=create 写一个新的 class-level skill，让 SKILL.md 覆盖共享 workflow，并包含简短标记小节。然后归档被吸收的狭窄兄弟。
   c. 降级为 REFERENCES/TEMPLATES/SCRIPTS。某个兄弟有狭窄但有价值的 session-specific 内容。把它移动到 umbrella 的合适 support directory：
      • `references/<topic>.md`：session 特定细节或压缩知识库，例如引用研究、API docs 摘录、领域笔记、provider quirks、复现 recipes。
      • `templates/<name>.<ext>`：可复制修改的 starter files。
      • `scripts/<name>.<ext>`：可静态重复运行的动作，例如验证脚本、fixture generators、probes。
      然后归档旧兄弟。使用 terminal 创建目录并移动文件到 umbrella 的 references/templates/scripts。
4. 还要标记名称过窄的 skills，例如包含 PR 编号、feature codename、具体错误字符串，或 audit/diagnosis/salvage 这类 session artifact。这些几乎都应该成为 class-level umbrella 下的小节或 support file。
5. 迭代。完成一轮合并后，扫描剩余集合，寻找下一个 umbrella 机会。不要合并 3 个就停。

你的工具集：
  - skills_list、skill_view：读取当前 skill landscape。
  - skill_manage action=patch：给 umbrella 添加小节。
  - skill_manage action=create：创建新的 umbrella SKILL.md。
  - skill_manage action=write_file：在已有 skill 下添加 references/、templates/ 或 scripts/ 文件。
  - skill_manage action=delete：归档 skill。合并进另一个 skill 时必须传 `absorbed_into=<umbrella>`；真正无转发目标裁剪时传 `absorbed_into=""`。这会驱动 cron-job skill 引用迁移；事后从 YAML summary 猜测很脆弱。
  - terminal：把兄弟 skill 移入 archive，或把内容移入 support subfile。

只有当 skill 已经是 class-level umbrella，且任何拟议合并都不会改善可发现性时，keep 才是合理决定。“这个很窄但和兄弟不同”不是 keep 的理由，而是把它移动到 umbrella 下作为小节或 support file 的理由。

预期输出：真正的 umbrella 化。处理每个明显 cluster。如果结束时少于 10 个 archive，说明停太早了，回去看留下的 clusters。

完成后，写一段人类可读 summary，并写一个结构化机器可读 block，让下游工具区分 consolidation 和 pruning。格式必须精确：

## Structured summary (required)
```yaml
consolidations:
  - from: <old-skill-name>
    into: <umbrella-skill-name>
    reason: <一句短理由，说明为什么合并，不只是“相似”>
prunings:
  - name: <skill-name>
    reason: <一句短理由，说明为什么归档且无合并目标>
```

每个移入 .archive/ 的 skill 必须且只能出现在两个列表之一。如果把 X 合并进 umbrella Y，X 放在 consolidations 下并写 into: Y。如果 X 归档时没有吸收目标，确实是 stale、irrelevant 或 obsolete，就放在 prunings 下。列表为空时写 `consolidations: []`。不要省略这个 block。这个 block 放在人类可读 summary 之后。

9.2 usage sidecar 与生命周期

Hermes 不把使用计数写进 SKILL.md，而是写到 sidecar：

~/.hermes/skills/.usage.json

它记录：

view_count：skill_view 成功读取时增加。
use_count：skill_view 被视为主动加载使用时增加。
patch_count：skill_manage patch/edit/write_file/remove_file 成功时增加。
last_used_at / last_viewed_at / last_patched_at：用于判断最近活动。
pinned：是否禁止自动归档或删除。
state：active / stale / archived。

这个设计避免把运行遥测写进用户维护的 SKILL.md，减少冲突。

生命周期大致是：

新 skill 创建
  ↓
active
  ↓
长期未使用 → stale
  ↓
更久未使用 → archived

Pinned skill 的行为：

允许 patch/edit。
拒绝 delete。
跳过 curator 自动归档。

也就是说，pin 不是“禁止进化”，而是“防止不可恢复丢失”。

10. 完整链路回放

会话 A：
用户让 Agent 写一篇 Hermes memory 系统实现分析文档。
任务经历多轮修改、prompt 补全、tool schema 补全、静态检查。
模型看到 SKILLS_GUIDANCE + SKILL_MANAGE_SCHEMA.description。
模型判断这是可复用 workflow。
模型在用户确认后调用 skill_manage(create)。
Agent 写入 ~/.hermes/skills/writing/implementation-analysis-docs/SKILL.md。

会话 B：
用户说“继续写 session_search 的实现分析文档”。
模型先扫描 system prompt 里的 <available_skills>。
模型看到 implementation-analysis-docs 的 description 与实现分析文档部分相关。
根据 ## Skills (mandatory)，模型必须加载相关 skill。
模型调用 skill_view(name="implementation-analysis-docs")。
当前 LLM 请求获得 SKILL.md 内容和 supporting files 列表。
模型按 skill 的流程写文档。
如果模型想继续浏览 writing 类别下是否还有其他候选，才需要调用 skills_list(category="writing")。

会话 C：
用户纠正：“prompt 不要集中放文末，要用到的时候给。”
模型判断当前 skill 缺少这个坑点。
模型调用 skill_manage(patch) 更新 SKILL.md。
下次再用 skill 时，这条要求已经内化进流程。

会话 D：
一次任务产生了很长的 provider prompt 参考材料。
模型不把全部内容塞进 SKILL.md。
模型调用 skill_manage(write_file)，写入 references/provider-prompts.md。
再 patch SKILL.md，加一行指针。

会话 E：
后台 review 发现本轮有新技巧但主模型没保存。
它根据 _SKILL_REVIEW_PROMPT 优先寻找当前加载 skill。
如果匹配，就 patch；否则找已有 umbrella；再不行写 support file；最后才 create 新 umbrella。

会话 F：
skill 库里出现很多一次性 narrow skills。
curator 根据 CURATOR_REVIEW_PROMPT 做 umbrella-building。
它把狭窄 skills 合并进 class-level umbrella。
旧 skill 进入 ~/.hermes/skills/.archive/，而不是直接删除。

这就是 Hermes Agent skills 的进化机制：前台模型从复杂任务中创建和修补流程，后台 review 补漏，curator 长期治理库结构，最终让“做过一次”变成“下次更会做”。