Hermes Agent Skill Authoring

Authoring Hermes-Agent Skills (in-repo)

Overview

There are two places a SKILL.md can live:

1. User-local: ~/.hermes/skills/<maybe-category>/<name>/SKILL.md — personal, not shared. Created via skill_manage(action='create').
2. In-repo (this skill is about this case): /home/bb/hermes-agent/skills/<category>/<name>/SKILL.md — committed, shipped with the package. Use write_file + git add. skill_manage(action='create') does NOT target this tree.

快速路径（user-local 技能维护）

本实例（~/.hermes/skills/）日常维护关注以下章节，其余（Overview 的 in-repo 创建 / Workflow / Prompt Generator / Cross-Referencing）与本实例无关，可跳过：

• 修改现有技能检查清单——高频（本实例主要场景：patch 现有技能）
• 新建技能前检查清单——低频（创建新技能时）
• Writing Quality Principles（含 Principle 9 正文形态：无时间戳）
• Pitfall 15（术语一致性） + Pitfall 8（简化而非堆叠）

When to Use

• User asks you to add a skill "in this branch / repo / commit"
• You're committing a reusable workflow that should ship with hermes-agent
• You're editing an existing skill under /home/bb/hermes-agent/skills/ (use patch for small edits, write_file for rewrites; skill_manage still works for patch on in-repo skills, but not for create)

Skill Component Model — Not Types

A common misconception is classifying skills as "Manual type," "Reference type," or "Prompt Generator type." These are not types. They are components within a single skill.

Every Hermes SKILL.md is one file that can contain any mix of three component kinds:

A single skill can contain all three. The systematic-debugging skill contains Manual components ("use search_files to trace"), Reference components (the Four Phases table), and could also contain a Prompt Generator component if it needed to produce instructions for another tool.

When to use each component:

• Manual — agent should call specific tools in a specific sequence
• Reference — agent needs structured facts to reason over (comparison tables, weights, field definitions)
• Prompt Generator — final output is text consumed by another AI system (Claude Code, Codex, etc.), not by the user directly

The decision is compositional, not categorical. Don't ask "is this a Manual or Prompt Generator skill?" Ask "which components does this skill need?"

Why This Matters

1. Prevents false dichotomies. A skill that spawns Claude Code subagents AND calls Hermes tools isn't "both types" — it's one skill with Manual + Prompt Generator components.
2. Keeps the skill flat. You don't need separate files for "manual part" and "generator part" — they coexist in the same SKILL.md, clearly separated by headings.

Required Frontmatter

Source of truth: tools/skill_manager_tool.py::_validate_frontmatter. Hard requirements:

• Starts with --- as the first bytes (no leading blank line).
• Closes with \n---\n before the body.
• Parses as a YAML mapping.
• name field present.
• description field present, ≤ 1024 chars (MAX_DESCRIPTION_LENGTH).
• Non-empty body after the closing ---.

Peer-matched shape used by every skill under skills/software-development/:

---
name: my-skill-name               # lowercase, hyphens, ≤64 chars (MAX_NAME_LENGTH)
description: Use when <trigger>. <one-line behavior>.
version: 1.2.0
author: Hermes Agent
license: MIT
metadata:
  hermes:
    tags: [short, descriptive, tags]
    related_skills: [other-skill, another-skill]
    provenance:                    # REQUIRED for agent-created skills (curator + traceability)
      created_at: "2026-08-04"
      source_session: "<session-id-or-title>"
      source_context: "<decision context, not just conclusion>"
---

version / author / license / metadata are NOT enforced by the validator, but every peer has them — omit and your skill sticks out.

⚠️ Two description limits — know which one applies:

• Validator (_validate_frontmatter): ≤ 1024 chars
• skill_manage(action='create') for user-local skills: ≤ 60 chars (one sentence, trigger first, ends with period) — the system-prompt index truncates at 57 + "...". A 105-char description was rejected twice (2026-08-04, sqlite-db-recovery). Write the short description for create; expand detail in the body.
• Provenance is mandatory for agent-created skills — the curator uses metadata.hermes.provenance as the marker to manage the skill lifecycle. Without it the skill lands in the unmanaged bucket (26 skills as of 2026-08-04) and is never stale-tracked or archived. Include created_at / source_session / source_context (decision context with contradictions, not just the conclusion).

Size Limits

• Description: ≤ 1024 chars (enforced).
• Full SKILL.md: ≤ 100,000 chars (enforced as MAX_SKILL_CONTENT_CHARS, ~36k tokens).
• Peer skills in software-development/ sit at 8-14k chars. Aim for that range. If you're pushing past 20k, split into references/*.md and reference them from SKILL.md.

Writing Quality Principles

A skill exists to make the agent's process more predictable. Predictability does not mean identical output every run; it means the agent reliably follows the same useful discipline.

Use these quality checks when writing or editing any skill:

1. Optimize for process predictability. Ask: what behavior should change when this skill loads? If a line does not change behavior, cut it.

2. Choose the right context load. A model-invoked Hermes skill pays for its description every turn. Keep descriptions focused on trigger classes and the skill's distinctive behavior. Put details in the body or linked references.

   负向边界：描述不承载具体规范条目（如"正文无时间戳"）——那是正文内容，加载后自然可见；把规范条目塞进描述 = 变相承认"加载后不看正文"，触发点（描述）与执行点（正文/[base] 锚定）职责必须分离。

3. Use an information hierarchy. Put always-needed steps in SKILL.md; put branch-specific or bulky reference material in references/, templates/, or scripts/ and point to it only when needed.

4. End steps with completion criteria. Each ordered step should say how the agent knows it is done. Good criteria are checkable and, when it matters, exhaustive: "every modified file accounted for" beats "summarize changes."

5. Co-locate rules with the concept they govern. Avoid scattering one idea across the file. Keep definition, caveats, examples, and verification near each other.

6. Use strong leading words. Prefer compact concepts the model already knows — e.g. "tight loop," "tracer bullet," "root cause," "regression test" — over long repeated explanations. A good leading word saves tokens and anchors behavior.

7. Prune duplication and no-ops. Keep each meaning in one source of truth. Sentence by sentence, ask whether the sentence changes agent behavior versus the default. If not, delete it rather than polishing it.

8. Watch for premature completion. If agents tend to rush a step, first sharpen that step's completion criterion. Split the sequence only when later steps distract from doing the current step well.

9. Body shape: readable lesson, not audit trail. Write "what pattern + why it is dangerous + how to tell" — a lesson a reader can apply. Audit traces (session IDs, message IDs, timestamps) belong in frontmatter provenance or references/, never in the body — IDs are meaningless to non-participants and corrode readability (2026-08-05: Pitfall 3 曾用 会话ID/消息ID 表达复发实证，可读性差，证据链已归位 provenance/references)。

Common quality failures:

• Premature completion — the skill lets the agent move on before the work is genuinely done.
• Duplication — the same rule appears in multiple places and drifts.
• Sediment — stale lines remain because adding felt safer than deleting.
• Sprawl — too much always-visible material; push branch-specific reference behind pointers.
• No-op prose — generic advice the agent would already follow without the skill.

Peer-Matched Structure

Every in-repo skill follows roughly:

# <Title>

## Overview
One or two paragraphs: what and why.

## When to Use
- Bulleted triggers
- "Don't use for:" counter-triggers

## <Topic sections specific to the skill>
- Quick-reference tables are common
- Code blocks with exact commands
- Hermes-specific recipes (tests via scripts/run_tests.sh, ui-tui paths, etc.)

## Common Pitfalls
Numbered list of mistakes and their fixes.

## Verification Checklist
- [ ] Checkbox list of post-action verifications

## 反面案例写作规范（何时写错误案例）

> 技能正文的两种内容形态：**正确流程**（步骤化引导）与**反面案例**（错误路径预警）。本节给出判断准则——不是所有错误都值得写，也不是只写正确流程就够。

### 判断树：这个错误要不要写进技能

① 错误是否"静默失败"（无报错/无日志/结果悄悄不对）？ ├─ 是 → 必须写！用户无法自发现，只能靠文档预警 └─ 否 → 看 ② ② 错误路径是否比正确路径"看起来更自然"？ ├─ 是 → 必须写！（读者大概率自然走错） └─ 否 → 看 ③ ③ 错误后果是否严重（崩溃/数据丢失/全站不可用）？ ├─ 是 → 必须写（代价高，值得预警） └─ 否 → 看 ④ ④ 报错信息是否明确且自解释（用户能自己定位）？ ├─ 是 → 可不写或简写（报错会引导） └─ 否 → 值得写（报错含糊，需要文档补全诊断链）

### 什么时候"只要正确流程"（不需要反面案例）

| 条件 | 说明 | 示例 |
|---|---|---|
| 路径唯一、无歧义 | 只有一种做法，不会自然走错 | "启动命令 `dsh web`" |
| 错误立即响亮报错且自解释 | 报错信息本身就告诉改什么 | 配置 schema 校验失败 |
| 代价低、可轻松回滚 | 踩了也无所谓 | 可逆的临时配置 |
| 空间受限 | 系统提示注入、CLI 帮助、摘要 | 技能 frontmatter description |
| 一次性失误（非机制性） | 打字错误——不是系统设计坑 | 不需要沉淀 |

### 反面案例的三条写作纪律

1. **必须标注"这是错的"**（❌/⚠️/加粗"不要"）——不能让错误写法看起来像选项之一。实证教训：dsh-client-ui-plugin-dev 曾把错误写法当"正确方式"在教（"目录形式，不能写 index.js"——实际相反），导致读者照做后整站黑屏。
2. **给出机制解释**（为什么错），不只给结论——否则无法迁移到变体场景（如"exports 白名单拦截 package.json 子路径"解释了为什么 require.resolve 失败）。
3. **标注实证来源与时效**（"2026-08-14 黑屏实证"）——错误案例可能随版本修复而过时，留实证标记便于审查。

### 错误案例的呈现形式

- **对比表**（错误写法 vs 正确写法 + 各自结果）——多选项场景首选（dsh 插件挂载三方案表：目录=崩溃/文件=跳过/包名=正解）
- **内联警告**（步骤旁 ⚠️）——单一关键坑
- **排障章节**（症状→原因→修复）——已发生且诊断链长的错误

## Prompt Generator Component Pattern

When a skill needs a **Prompt Generator component** — rules for producing text consumed by another AI system — the architecture differs from pure Manual/Reference components.

> **Full field-level reference:** [references/prompt-generator-field-guide.md](references/prompt-generator-field-guide.md) — input tables, decision-tree templates, assembly rules, pitfalls.

### Two-Layer Design Pattern

For domains involving another AI system (e.g. codebase review sent to Claude Code), create **two skills**:

Layer 1: Claude Code native skill (~/.claude/skills//SKILL.md) → Daily one-click use. Claude Code reads and executes directly. → Frontmatter: disable-model-invocation: true (user triggers via /name) → Content: self-contained pipeline instructions with shell commands → Format: Claude Code Skill format (NOT Hermes skill format)

Layer 2: Hermes Skill with Prompt Generator component (~/.hermes/skills///SKILL.md) → Advanced/custom scenarios. Hermes reads rules and generates a tailored prompt. → Content: Input spec → Decision rules → Assembly templates → Output example → Format: Hermes skill format (YAML frontmatter + markdown body)

### Prompt Generator Anatomy (Layer 2)

A Prompt Generator SKILL.md has five sections:

1. Input Collection — table of fields to ask the user

   Field	Description	Required

2. Decision Rules — branch logic based on input values

   • Mode selection (review vs review+fix vs port vs quick)
   • Scale calibration (small/medium/large)
   • Risk & cross-validation decision
   • Tool selection (what goes into the generated prompt)

3. Assembly Rules — how to construct the output prompt

   • Opening line template
   • Scale adaptation (insert phase structure per scale)
   • Constraints block (user-provided limits)
   • Output format specification
   • Verification gate (if applicable)

4. Output Template — simplified reference, pointing to the example Most content is in rules; template just says "see Section 5 example"

5. Full Example — concrete input → complete generated prompt Shows the exact text the user should paste into the target system

### Key Differences from Pure Manual Components

| Aspect | Pure Manual Components | With Prompt Generator Components |
|--------|----------------------|----------------------------------|
| **Audience of instructions** | Hermes Agent | Hermes Agent |
| **Audience of output** | The user (result of agent's work) | **Another AI system** (Claude Code etc.) |
| **Agent's role** | Execute steps, call tools, produce results | **Analyze input → apply rules → assemble text** |
| **Verification** | "Does the code work?" | "Would the target AI parse this correctly?" |
| **Content reuse** | Internal reference for agent | Rules + templates agent uses to construct output |

### When to Use Each Layer

- **Claude Code native skill** (Layer 1): Project is ready, you just need Claude Code to run the pipeline. Fastest path.
- **Hermes Prompt Generator** (Layer 2): You have special constraints (token budget, scope limits, specific model selection) and want Hermes to customize the prompt before sending to Claude Code.
- **Both**: Default case. Layer 1 handles daily use; Layer 2 handles edge cases where the standard prompt doesn't fit.

### Two-Layer Validation Protocol

When creating **both layers** (Claude Code native skill + Hermes Prompt Generator for the same domain), the inconsistency found by cross-referencing is the main failure mode. Run this protocol:

1. **Draft both layers independently.** Write the Claude Code native skill first (it's the simpler, self-contained version), then derive the Hermes Prompt Generator from it.
2. **Delegate sub-agent review.** Dispatch parallel sub-agents to review each layer for correctness, completeness, executability, and structural quality. Each sub-agent reports independently.
3. **Cross-reference findings.** The most valuable output is contradictions between the two layers — e.g. "Claude Code skill says 2 phases, Hermes Prompt Generator says 3 phases for the same mode." Fix the source of truth and propagate.
4. **Patch both layers.** Address each finding:
   - **Shell command bugs** (`find` parentheses, `grep --include` expansion) → patch the Claude Code native skill
   - **Logical contradictions** (ultracode: always vs sometimes) → patch the Hermes Prompt Generator assembly rules
   - **Input/output mismatches** → reconcile both layers
5. **Run verification.** Execute a verification script against the patch set — don't just re-read the files. Shell commands must be run, not syntax-checked.
6. **Update user.** Summarize what was fixed and what remains.

> **Why this matters:** Two independently-authored layers for the same domain inevitably drift. Without cross-validation, one layer says "2 phases" while the other says "3 phases" — and the user gets contradictory advice depending on which path they take.

### Common Mistakes

- ❌ Writing the **generated output** (the Claude Code prompt) directly in the Hermes SKILL.md as if it were instructions for Hermes. The skill should contain *rules for generating*, not the generated text itself.
- ❌ Putting "Always do X" in the assembly rules while contradicting it in the pitfalls section. If the rule has exceptions, encode them in the rule itself, not in a separate section.
- ❌ Forgetting to tell the user what system version is required (e.g. "Claude Code v2.1.154+ for ultracode:").
- ❌ Including the project path in the generated prompt — the user is already in the project directory when they run Claude Code.

## One-Shot Recipes (optional)
Named scenarios → concrete command sequences.

Not every section is mandatory, but Overview + When to Use + actionable body + pitfalls are the minimum for the skill to feel like a peer.

Directory Placement

skills/<category>/<skill-name>/SKILL.md

Categories currently in repo (confirm with ls skills/): autonomous-ai-agents, creative, data-science, devops, dogfood, email, gaming, github, leisure, mcp, media, mlops/*, note-taking, productivity, red-teaming, research, smart-home, social-media, software-development.

Pick the closest existing category. Don't invent new top-level categories casually.

新建技能前检查清单（执行点内嵌 — 2026-08-04）

任何技能创建/知识落盘前逐项走过。这是"规范折叠进执行点"的落地——不依赖"记得想起规范"，依赖流程推进。来源：session-knowledge-capture 步骤④、memory-storage-management、execution-governance、USER.md R2、rule-enforcement。

1. 查重（内容级） — skills_list 名称比对只是起点；对 description 命中的候选（"recovery"、"governance" 等）必须 skill_view 内容级对比，确认无重叠才新建；高度重叠 → patch 现有技能。只做列表比对就新建 = L1 应用失败（2026-08-04 两次实证）
2. frontmatter 四要素 + provenance — name/description（≤60 给 skill_manage create）/version/author/license/metadata.hermes.{tags, related_skills, provenance}；无 provenance → curator unmanaged（不 stale、不归档）
3. 结构 — When to Use / Pitfalls / Verification；peer 体量 8-14K（>20K 拆 references）
4. 审批门控 — 创建前给用户方案（要建什么、放哪个 category、与谁互补），等明确批准（"好"≠ 批准，execution-governance）
5. 记忆联动 — 若涉及 memory 写入：判据四问 + 85% 阈值检查（memory-storage-management）；若修改现有技能：先 .bak 快照
6. git commit — hermes-state-git 约定：cd F:/AI/Hermes/hermes && git --git-dir=../hermes-state-git/.git --work-tree=. add skills/ && commit（source session 标注）
7. 收敛检查 — 这是新规则还是折叠进现有执行点？新技能是否可避免（rule-enforcement 数量红线：执行准确率与规则数量负相关）

Workflow

1. Survey peers in the target category:

   ls skills/<category>/
   

   Read 2-3 peer SKILL.md files to match tone and structure.
2. Check validator constraints in tools/skill_manager_tool.py if unsure.
3. Draft with write_file to skills/<category>/<name>/SKILL.md.
4. Validate locally:

   import yaml, re, pathlib
   content = pathlib.Path("skills/<category>/<name>/SKILL.md").read_text()
   assert content.startswith("---")
   m = re.search(r'\n---\s*\n', content[3:])
   fm = yaml.safe_load(content[3:m.start()+3])
   assert "name" in fm and "description" in fm
   assert len(fm["description"]) <= 1024
   assert len(content) <= 100_000
   

5. Git add + commit on the active branch.
6. Note: the CURRENT session's skill loader is cached — skill_view / skills_list will not see the new skill until a new session. This is expected, not a bug.

Cross-Referencing Other Skills

metadata.hermes.related_skills unions both trees (skills/ in-repo and ~/.hermes/skills/) at load time. You CAN reference a user-local skill from an in-repo skill, but it won't resolve for other users who clone the repo fresh. Prefer referencing only in-repo skills from in-repo skills. If a frequently-referenced skill lives only in ~/.hermes/skills/, consider promoting it to the repo.

修改现有技能检查清单（执行点内嵌）

修改（patch/edit）现有技能前逐项走过——不依赖"记得加载本技能"，依赖流程推进（rule-enforcement 折叠原则）。"新建技能前检查清单"是 create 场景，本清单是修改场景。

1. 正文形态：新增内容无时间戳/会话ID/消息ID（Quality Principle 9——修订时间线查 git，正文不存日期）；"实证"字样保留，时点进 provenance
2. 术语一致性：同词异义检查（Pitfall 15）
3. 内容级查重：新增知识点先 grep 技能库（grep -ril "<关键词>" "$HERMES_HOME/skills" --include="SKILL.md"）
4. 简化而非堆叠：加规则时删旧表述（Pitfall 8）；sediment 清理
5. .bak 快照 + git commit（执行纪律）
6. 修订时间线查询：git --git-dir=../hermes-state-git/.git --work-tree=. log --follow --format='%h %ad %s' --date=short -- skills/<path>/SKILL.md

Editing Existing In-Repo Skills

• Small fix (typo, added pitfall, tightened trigger): skill_manage(action='patch', name=..., old_string=..., new_string=...) works fine on in-repo skills.
• Major rewrite: write_file the whole SKILL.md. skill_manage(action='edit') also works but requires supplying the full new content.
• Adding supporting files: write_file to skills/<category>/<name>/references/<file>.md, templates/<file>, or scripts/<file>. skill_manage(action='write_file') also works and enforces the references/templates/scripts/assets subdir allowlist.
• Always commit the edit — in-repo skills are source, not runtime state.

Common Pitfalls

1. Using skill_manage(action='create') for an in-repo skill. It writes to ~/.hermes/skills/, not the repo tree. Use write_file for in-repo creation.

2. Leading whitespace before ---. The validator checks content.startswith("---"); any leading blank line or BOM fails validation.

3. Description too generic. Peer descriptions start with "Use when ..." and describe the trigger class, not the one task. "Use when debugging X" > "Debug X".

4. Forgetting the author/license/metadata block. Not validator-enforced, but every peer has it; omitting makes the skill look half-finished.

5. Writing a skill that duplicates a peer. Before creating, ls skills/<category>/ and open 2-3 peers. Prefer extending an existing skill to creating a narrow sibling.

6. Expecting the current session to see the new skill. It won't. The skill loader is initialized at session start. Verify in a fresh session or via skill_view using the exact path.

7. Letting skills accumulate sediment. A skill should get shorter or sharper over time. When adding a rule, remove the old wording it replaces; don't layer advice forever.

8. Writing no-op prose. "Be careful," "be thorough," and "use best practices" rarely change model behavior. Replace with a checkable completion criterion or a stronger leading word.

9. Decision tree vs assembly rule contradiction (Prompt Generators). The scale calibration section says "2 phases" but the assembly template says "3 phases". The agent receives contradictory instructions. The decision tree output values MUST exactly match the assembly template's conditional branches. Always regenerate both together.

10. Violating the "链路简洁" (shortest path) principle. When a task involves another AI system (Claude Code), prefer: Claude Code native skill > Hermes-generated prompt > manual multi-step. Each extra intermediate step adds fragility. Design for the shortest chain that meets the user's need.

11. Untested shell commands in skill content. Shell commands inside code blocks (find, grep, sed) are code — they need testing. Two classic bugs that silently produce wrong results: (a) find -type f -name '*.ts' -o -name '*.js' — the -o binds more loosely than the implied -a, so the second condition is not bounded by -type f. Fix: \( -name '*.ts' -o -name '*.js' \). (b) grep --include='*.{ts,js}' — single quotes prevent shell brace expansion, so grep sees a literal filename pattern *.{ts,js}. Fix: split into separate --include='*.ts' --include='*.js'.

12. Linking to skills that don't exist in-repo. related_skills: [some-user-local-skill] works for you but breaks for other clones. Prefer only in-repo links.

13. Silent delegation failure. When delegate_task fails (model/provider incompatibility, auth issues), the agent silently falls back to executing the work itself. Always report delegation outcomes — if subagents failed and you're doing the work manually, say so. The user needs to know whether parallel execution actually happened or was a local fallback.

14. 同词异义未限定（术语一致性）. 新增/修改章节前，检查既有规范是否已使用同术语（如"合并"在 memory-storage-management 已有"精简合并"语义）——避免同词异义造成规范歧义（歧义是 rule-enforcement 四层框架的文本层缺陷形态）；术语被重新定义时必须显式限定（"信息合并" vs "精简合并"），并注明与既有语义的关系。

Verification Checklist

• File is at skills/<category>/<name>/SKILL.md (not in ~/.hermes/skills/)
• Frontmatter starts at byte 0 with ---, closes with \n---\n
• name, description, version, author, license, metadata.hermes.{tags, related_skills} all present
• Name ≤ 64 chars, lowercase + hyphens
• Description ≤ 1024 chars and starts with "Use when ..."
• Total file ≤ 100,000 chars (aim for 8-15k)
• Structure: # Title → ## Overview → ## When to Use → body → ## Common Pitfalls → ## Verification Checklist
• Each ordered step has a checkable completion criterion
• Description is trigger-focused and avoids duplicated body content
• Bulky or branch-specific reference is progressively disclosed in linked files
• If the skill uses references/, templates/, or scripts/, the SKILL.md links to them with a brief description so agents know what's available
• No-op prose and duplicated rules removed
• related_skills references resolve in-repo (or are explicitly OK to be user-local)
• git add skills/<category>/<name>/ && git commit completed on the intended branch