Issue Station
Sign In
Tools hereToolbox

hermes - ✅(Solved) Fix [Bug]: System prompt skills index uses directory names instead of frontmatter names, breaking skill routing [1 pull requests, 1 participants]

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…
GitHub stats
NousResearch/hermes-agent#11777•Fetched 2026-04-18 05:58:52
View on GitHub
Comments
0
Participants
1
Timeline
4
Reactions
0
Author
ivoloivolo
Participants
ivoloivolo
Timeline (top)
referenced ×2closed ×1cross-referenced ×1

Root Cause

_build_snapshot_entry() stores both skill_name (directory name) and frontmatter_name, but build_skills_system_prompt() always uses skill_name for the index display (lines ~655, ~680, ~735).

Similarly, skill_view() in tools/skills_tool.py only resolves by directory name (found_skill_md.parent.name == name), so even if the index showed the frontmatter name, skill_view("north-eval") would fail.

Additionally, the trigger field from frontmatter is never surfaced in the index, losing valuable routing hints.

Fix Action

Fix / Workaround

I have a working patch for both files — happy to submit a PR if wanted.

PR fix notes

PR #11853: fix(skills): use frontmatter name in skills index instead of directory name

Description (problem / solution / changelog)

Problem

build_skills_system_prompt() shows skills in the system prompt using their directory name (skill_name) instead of their declared frontmatter name field (frontmatter_name). Any skill where the directory name differs from its frontmatter name appears under the wrong name in the system prompt, causing LLM routing failures.

Example:

  • Directory: skills/north/review/SKILL.md
  • Frontmatter: name: north-eval
  • System prompt showed: review ❌
  • Should show: north-eval ✅

Closes #11777

Root Cause

_build_snapshot_entry() correctly stores both skill_name (directory) and frontmatter_name (declared) in the snapshot entry. But all three code paths that build skills_by_category tuples used the wrong variable:

  • Line 657 (snapshot/warm path): (skill_name, ...)
  • Line 682 (cold filesystem scan): (skill_name, ...)
  • Line 736 (external dirs): (skill_name, ...)

Fix

Switch all three tuple appends to use frontmatter_name. Also fix the external-dir dedup set (seen_skill_names) to track frontmatter_name for consistency — since the local-skill tuples now use frontmatter_name, the dedup check against that set must use the same key.

Reproduction & Verification

Reproduced against docker.io/nousresearch/hermes-agent:latest (v0.8.0) with a skill at skills/north/review/SKILL.md declaring name: north-eval:

Before fix:

<available_skills>
  north:
    - review: Daily portfolio evaluation and rebalancing check
</available_skills>

After fix:

<available_skills>
  north:
    - north-eval: Daily portfolio evaluation and rebalancing check
</available_skills>

Both cold path (fresh filesystem scan) and warm path (snapshot cache) verified correct.

🤖 Generated with Claude Code

Changed files

  • agent/prompt_builder.py (modified, +7/-6)

Code Example

name: north-eval
description: Daily portfolio evaluation...
trigger: When asked to "north eval", "run the daily eval"...

---

north:
    - review: Daily portfolio evaluation...
RAW_BUFFERClick to expand / collapse

Bug Description

The <available_skills> block injected into the system prompt by build_skills_system_prompt() in agent/prompt_builder.py displays directory names instead of frontmatter name fields. This causes the LLM to fail routing when the directory name differs from the skill's declared name.

Example

Given a skill at skills/north/review/SKILL.md with frontmatter:

name: north-eval
description: Daily portfolio evaluation...
trigger: When asked to "north eval", "run the daily eval"...

The system prompt shows:

  north:
    - review: Daily portfolio evaluation...

When a user says "north eval", the LLM sees "review" and can't match it. It either asks for clarification or hallucinates a skill name like "north-portfolio-valuecheck".

Root Cause

_build_snapshot_entry() stores both skill_name (directory name) and frontmatter_name, but build_skills_system_prompt() always uses skill_name for the index display (lines ~655, ~680, ~735).

Similarly, skill_view() in tools/skills_tool.py only resolves by directory name (found_skill_md.parent.name == name), so even if the index showed the frontmatter name, skill_view("north-eval") would fail.

Additionally, the trigger field from frontmatter is never surfaced in the index, losing valuable routing hints.

Related Issues

  • #5433 — same root cause (directory vs frontmatter name mismatch), different symptom (builtin/local classification)
  • #7669 — closed as dup of #5433
  • #8110 — external skills excluded from Telegram commands

Suggested Fix

  1. prompt_builder.py: Use frontmatter_name instead of skill_name when building index tuples. Include trigger field in the index.
  2. skills_tool.py: Add a frontmatter-name fallback search in skill_view() after the directory-name search.

I have a working patch for both files — happy to submit a PR if wanted.

Impact

Any skill where the SKILL.md name field differs from the parent directory name will be misrepresented in the system prompt, causing routing failures for LLM-driven skill selection (especially in gateway/Slack/Telegram where users type natural language, not slash commands).

extent analysis

TL;DR

Use frontmatter_name instead of skill_name in build_skills_system_prompt() and add a frontmatter-name fallback search in skill_view() to fix the directory name and frontmatter name field mismatch.

Guidance

  • Update prompt_builder.py to use frontmatter_name when building index tuples and include the trigger field in the index to provide valuable routing hints.
  • Modify skills_tool.py to add a frontmatter-name fallback search in skill_view() after the directory-name search to ensure correct skill resolution.
  • Verify the fix by checking the system prompt for correct display of skill names and testing LLM-driven skill selection with skills having different directory and frontmatter names.
  • Consider submitting a PR with the working patch for both files to ensure the changes are reviewed and integrated into the codebase.

Example

No code snippet is provided as the issue already includes a clear description of the necessary changes.

Notes

The suggested fix assumes that the frontmatter_name and trigger fields are correctly populated in the skill's frontmatter. Additionally, the fix may not address other potential issues related to skill resolution or routing.

Recommendation

Apply the suggested workaround by updating prompt_builder.py and skills_tool.py as described, as it directly addresses the root cause of the issue and provides a clear solution.

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…
#api#ssr#installation#API versioning#request timeout

Still need to ship something?

×6

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

Back to top recommendations

TRENDING