hermes - 💡(How to fix) Fix feat: Allow custom subdirectories in skill linked_files discovery

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…

Error Message

The dispatcher SKILL.md says "load steps/step-1.md for Phase 1", but because steps/ isn't in ALLOWED_SUBDIRS, skill_view never lists those files in linked_files. The agent has to guess file paths from the main SKILL.md text, which is error-prone and breaks the intended routing mechanism.

Root Cause

For complex, multi-phase workflows, the recommended pattern is a dispatcher skill + sub-skills structure:

my-workflow/
├── SKILL.md          # Dispatcher: defines phases and routing
├── steps/            # Sub-skills for each phase
│   ├── step-1.md
│   ├── step-2.md
│   ├── step-3.md
│   ├── step-4.md
│   ├── step-5.md
│   └── step-6.md
├── scripts/          # Execution scripts
└── references/       # Documentation

The dispatcher SKILL.md says "load steps/step-1.md for Phase 1", but because steps/ isn't in ALLOWED_SUBDIRS, skill_view never lists those files in linked_files. The agent has to guess file paths from the main SKILL.md text, which is error-prone and breaks the intended routing mechanism.

Fix Action

Workaround

Users can manually patch ALLOWED_SUBDIRS in skill_manager_tool.py, but this breaks on upgrade.

Code Example

# Line 171
ALLOWED_SUBDIRS = {"references", "templates", "scripts", "assets"}

---

my-workflow/
├── SKILL.md          # Dispatcher: defines phases and routing
├── steps/            # Sub-skills for each phase
│   ├── step-1.md
│   ├── step-2.md
│   ├── step-3.md
│   ├── step-4.md
│   ├── step-5.md
│   └── step-6.md
├── scripts/          # Execution scripts
└── references/       # Documentation

---

metadata:
  hermes:
    subdirs: [references, scripts, steps]
RAW_BUFFERClick to expand / collapse

Problem

skill_manager_tool.py hardcodes ALLOWED_SUBDIRS to only 4 directories:

# Line 171
ALLOWED_SUBDIRS = {"references", "templates", "scripts", "assets"}

Any custom subdirectory is invisible to skill_view — it won't appear in linked_files, so agents can't discover them automatically.

Why this matters

For complex, multi-phase workflows, the recommended pattern is a dispatcher skill + sub-skills structure:

my-workflow/
├── SKILL.md          # Dispatcher: defines phases and routing
├── steps/            # Sub-skills for each phase
│   ├── step-1.md
│   ├── step-2.md
│   ├── step-3.md
│   ├── step-4.md
│   ├── step-5.md
│   └── step-6.md
├── scripts/          # Execution scripts
└── references/       # Documentation

The dispatcher SKILL.md says "load steps/step-1.md for Phase 1", but because steps/ isn't in ALLOWED_SUBDIRS, skill_view never lists those files in linked_files. The agent has to guess file paths from the main SKILL.md text, which is error-prone and breaks the intended routing mechanism.

Suggested fix

Two options:

  1. Auto-discover all subdirectories — scan the skill directory and include any subdir containing .md or .py files in linked_files, removing the hardcoded whitelist entirely.

  2. Make it configurable — allow skills to declare additional subdirs in frontmatter metadata:

metadata:
  hermes:
    subdirs: [references, scripts, steps]

Option 1 is simpler and more flexible — there's no security reason to restrict subdirectory names (these are local files, not user input).

Workaround

Users can manually patch ALLOWED_SUBDIRS in skill_manager_tool.py, but this breaks on upgrade.

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…

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 - 💡(How to fix) Fix feat: Allow custom subdirectories in skill linked_files discovery