Issue Station
Sign In
Tools hereToolbox

hermes - ✅(Solved) Fix [Bug] Skills 系统五大架构缺陷 — 缺乏新陈代谢与质量控制 [2 pull requests]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…

Fix Action

Fix / Workaround

临时修复： 将 creation_nudge_interval 调为 0 可缓解此问题，但属于 workaround，无法从根本上解决 Skill 质量控制问题。

PR fix notes

PR #1: fix(skills): consume related_skills in skill activation flow

Description (problem / solution / changelog)

Summary

This PR makes related_skills actionable in the runtime flow instead of returning it as passive metadata only.

What changed

  • skill_view() now classifies declared related skills into:
    • related_skills_available
    • related_skills_missing
  • Skill activation message injection now consumes those fields and adds:
    • a load hint for available related skills (skill_view(name="..."))
    • visibility for declared-but-missing related skills
  • Added regression tests for both behaviors.

Why

related_skills was parsed and returned but not consumed downstream. This PR wires the field into the activation prompt path so it can influence real skill-loading behavior.

Tests

I ran targeted tests for the affected areas:

  • python -m pytest -o addopts="" tests/tools/test_skills_tool.py::TestSkillView -q
  • python -m pytest -o addopts="" tests/agent/test_skill_commands.py::TestBuildSkillInvocationMessage -q

Note: scripts/run_tests.sh was attempted first but failed in this Windows/WSL shell due to shell/line-ending incompatibility; the fallback invocation above was used.

Related issue

  • NousResearch/hermes-agent#13265

Changed files

  • agent/skill_commands.py (modified, +21/-0)
  • tests/agent/test_skill_commands.py (modified, +16/-0)
  • tests/tools/test_skills_tool.py (modified, +14/-0)
  • tools/skills_tool.py (modified, +9/-0)

PR #13343: fix(skills): consume related_skills in skill activation flow

Description (problem / solution / changelog)

What does this PR do?

This PR fixes issue #13265 (problem 3) by making related_skills actionable in runtime flow instead of passive metadata.

Before:

  • skill_view() parsed and returned related_skills, but downstream activation flow did not consume it.
  • Declared relationships between skills had no practical effect.

After:

  • skill_view() now classifies declared related skills into:
    • related_skills_available
    • related_skills_missing
  • Skill activation message construction now consumes these fields and:
    • adds explicit load hints for available related skills (skill_view(name="..."))
    • surfaces declared-but-missing related skills for maintainability/diagnostics

This is a low-risk, non-breaking fix that closes the metadata-to-runtime gap without changing core agent loop behavior.

Related Issue

Fixes #13265

Type of Change

  • 🐛 Bug fix (non-breaking change that fixes an issue)
  • ✨ New feature (non-breaking change that adds functionality)
  • 🔒 Security fix
  • 📝 Documentation update
  • ✅ Tests (adding or improving test coverage)
  • ♻️ Refactor (no behavior change)
  • 🎯 New skill (bundled or hub)

Changes Made

  • Added related-skill availability split in skill_view():
    • tools/skills_tool.py
    • New output fields: related_skills_available, related_skills_missing
  • Consumed related-skill signals in activation prompt construction:
    • agent/skill_commands.py
    • Added actionable load hints for available related skills
    • Added visibility for missing declared related skills
  • Added regression tests:
    • tests/tools/test_skills_tool.py
      • test_view_related_skills_split_by_availability
    • tests/agent/test_skill_commands.py
      • test_includes_related_skill_hints

How to Test

  1. Run targeted new tests:
    • python -m pytest -o addopts="" tests/tools/test_skills_tool.py::TestSkillView::test_view_related_skills_split_by_availability -q
    • python -m pytest -o addopts="" tests/agent/test_skill_commands.py::TestBuildSkillInvocationMessage::test_includes_related_skill_hints -q
  2. Run affected test classes:
    • python -m pytest -o addopts="" tests/tools/test_skills_tool.py::TestSkillView tests/agent/test_skill_commands.py::TestBuildSkillInvocationMessage -q
  3. Manual verification:
    • Create a skill with related_skills: [reuse-helper, missing-helper] where only reuse-helper exists.
    • Confirm skill_view("test-skill") returns:
      • related_skills_available == ["reuse-helper"]
      • related_skills_missing == ["missing-helper"]
    • Confirm invocation message includes:
      • skill_view(name="reuse-helper")
      • missing-related-skill notice for missing-helper

Checklist

Code

  • I've read the Contributing Guide
  • My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
  • I searched for existing PRs to make sure this isn't a duplicate
  • My PR contains only changes related to this fix/feature (no unrelated commits)
  • I've run pytest tests/ -q and all tests pass
  • I've added tests for my changes (required for bug fixes, strongly encouraged for features)
  • I've tested on my platform: Windows 11

Documentation & Housekeeping

  • I've updated relevant documentation (README, docs/, docstrings) — or N/A (N/A)
  • I've updated cli-config.yaml.example if I added/changed config keys — or N/A (N/A)
  • I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — or N/A (N/A)
  • I've considered cross-platform impact (Windows, macOS) per the compatibility guide — or N/A
  • I've updated tool descriptions/schemas if I changed tool behavior — or N/A (N/A)

Screenshots / Logs

  • Targeted and affected-scope tests pass locally:
    • tests/tools/test_skills_tool.py::TestSkillView
    • tests/agent/test_skill_commands.py::TestBuildSkillInvocationMessage
  • Note on full-suite status in this environment:
    • scripts/run_tests.sh is not executable here due to shell/line-ending compatibility in this Windows/WSL setup.
    • python -m pytest -o addopts="" tests/ -q was attempted, but full collection fails in this local environment due to missing platform-specific dependencies/modules (acp, fire, pwd, fcntl, etc.) and tool availability differences.
    • CI should be used as the authoritative full-suite result.

Changed files

  • agent/skill_commands.py (modified, +21/-0)
  • tests/agent/test_skill_commands.py (modified, +16/-0)
  • tests/tools/test_skills_tool.py (modified, +14/-0)
  • tools/skills_tool.py (modified, +9/-0)
RAW_BUFFERClick to expand / collapse

问题描述

Hermes Agent 的 Skills 系统存在以下五个已确认的架构缺陷，严重影响系统长期可用性：

1. _create_skill() 缺乏内容有效性校验

位置： tools/skill_manager_tool.py _create_skill() 函数（约第616-789行）

问题： 创建 Skill 时仅检查名称唯一性，对内容质量无任何校验机制。任何对话片段都可以被固化 为 Skill，包括低价值、一次性、错误或重复的经验。

影响： 长期使用后 Skill 库存质量良莠不齐，无法区分高价值和低价值经验。

2. 完全没有 Skill 新陈代谢机制

位置： tools/skill_manager_tool.py _delete_skill() 函数

问题： Skills 只进不出。没有任何基于使用频率、创建时间或内容陈旧度的自动清理逻辑。无效或过时的 Skill 永远驻留在 ~/.hermes/skills/ 目录中。

影响： Skill 数量随时间无限增长，检索效率下降，系统噪声增加。

3. related_skills 字段为死代码

位置： tools/skills_tool.py 第1169-1170行

问题： related_skills 字段在 skill_view 返回的 JSON 中被解析和填充，但没有任何消费者代码引用这个字段。即使用户填写了关联 Skill 信息，也完全不会影响 Skill 的组合或检索行为。

影响： 文档字段与实际功能脱节，对用户造成误导。

4. 冲突检测仅基于精确名称匹配，无语义去重

位置： tools/skill_manager_tool.py _find_skill() 函数（第324-330行）

问题： 新建 Skill 时只检查名称是否完全相同，对语义重叠（如 proxy-toggle vs proxy-toggle-v2）或功能高度相似的 Skill 没有检测机制。

影响： 容易产生重复 Skill，增加维护负担。

5. creation_nudge_interval 机械定时器导致 Skill 质量失控

位置： run_agent.py 第11719行 _should_review_skills / prompt_builder.py 第797行

问题： creation_nudge_interval（默认15轮）使用机械定时器触发 Skill 创建提醒，无视任务复杂度，每隔固定轮数就强制推送创建提示。这与系统提示词中 "After difficult/iterative tasks, offer to save as a skill." 的质量过滤逻辑冲突。

临时修复： 将 creation_nudge_interval 调为 0 可缓解此问题，但属于 workaround，无法从根本上解决 Skill 质量控制问题。

影响： 在默认配置下，即使用户未进行复杂任务，系统也会定期提示创建 Skill，导致低质量 Skill 大面积产生。

期望行为

  1. Skill 创建应具备内容质量门槛（有效性、必要性、去重检查）
  2. 应提供 Skill 生命周期管理（自动清理过时/低使用率 Skill）
  3. related_skills 应有实际消费逻辑（检索增强、组合推荐）
  4. 冲突检测应扩展至语义层面
  5. creation_nudge_interval 的触发逻辑应考虑任务复杂度，而非纯定时器

环境信息

  • 版本： nousresearch/hermes-agent latest
  • 配置文件： ~/.hermes/config.yaml
  • 相关源码： /tmp/hermes-agent/（源代码克隆）

本 Issue 由 Hermes Agent 社区用户提交，基于 B站视频 BV1K8dZB5EcY「Hermes似乎真是个半成品！」分析后，经源代码核查确认。

extent analysis

TL;DR

To address the five confirmed architectural defects in the Hermes Agent's Skills system, implement content validity checks, introduce a Skill lifecycle management mechanism, utilize the related_skills field, enhance conflict detection, and modify the creation_nudge_interval logic to consider task complexity.

Guidance

  1. Implement content validity checks: Modify the _create_skill() function in tools/skill_manager_tool.py to validate the quality and necessity of the Skill content before creation.
  2. Introduce Skill lifecycle management: Develop an automatic cleaning mechanism based on usage frequency, creation time, or content freshness to remove outdated or low-value Skills from the ~/.hermes/skills/ directory.
  3. Utilize the related_skills field: Update the skills_tool.py to consume the related_skills field, enhancing Skill retrieval and combination logic.
  4. Enhance conflict detection: Modify the _find_skill() function to detect semantic overlaps and functional similarities between Skills, preventing duplicates.
  5. Modify creation_nudge_interval logic: Update the run_agent.py and prompt_builder.py to consider task complexity when triggering Skill creation reminders, rather than relying solely on a mechanical timer.

Example

# Example of enhanced conflict detection in _find_skill() function
def _find_skill(skill_name):
    # Existing code for exact name matching
    # ...
    # Additional logic for semantic overlap detection
    similar_skills = [skill for skill in skills if similarity(skill_name, skill.name) > 0.5]
    if similar_skills:
        # Handle similar Skills, e.g., prompt user to review and merge
        pass

Notes

The provided guidance focuses on addressing the five confirmed architectural defects. However, a comprehensive solution may require additional changes and testing to ensure the overall system's stability and performance.

Recommendation

Apply the proposed workarounds and modifications to address the identified defects, as they provide a foundation for improving the Skills system's quality and functionality.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#task chaining#parallel task#integration issue#index setup#retrieval issue

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

hermes - ✅(Solved) Fix [Bug] Skills 系统五大架构缺陷 — 缺乏新陈代谢与质量控制 [2 pull requests]