hermes - 💡(How to fix) Fix Profile skills directory fully shadows global skills — no cascade fallback

title: "Profile skills directory fully shadows global skills — no cascade fallback" labels: ["bug", "profiles", "skills"]

Description

When using named Hermes profiles, SKILLS_DIR is set to $HERMES_HOME/skills/ where HERMES_HOME points to ~/.hermes/profiles/<name>/. The all_dirs list in skill_view() only contains this profile-specific skills directory plus any external_dirs from config. The global skills directory (~/.hermes/skills/) is not included as a fallback.

This means:

• Skills installed under the default profile (~/.hermes/skills/) are invisible to named profiles
• hermes -p <profile> skills list shows them if... actually it DOES show them if a symlink exists, but skill_view() cannot resolve them without one
• There's no cascade: global → profile override

Impact

A user who creates a named profile and later adds skills to the global directory (which is the default install location) finds those skills don't work from the named profile. The only workaround is manually symlinking the category into the profile's skills directory.

Root Cause

In tools/skills_tool.py:

HERMES_HOME = get_hermes_home()        # profile-specific for named profiles
SKILLS_DIR = HERMES_HOME / "skills"    # ~/.hermes/profiles/<name>/skills/

And in skill_view():

all_dirs = []
if SKILLS_DIR.exists():
    all_dirs.append(SKILLS_DIR)
all_dirs.extend(get_external_skills_dirs())

The global ~/.hermes/skills/ is never included in all_dirs when a profile is active.

Expected Behavior

Skills should cascade: profile-specific skills override global skills of the same name, but global skills should be visible when no profile-specific override exists.

Something like:

global_skills = Path.home() / ".hermes" / "skills"
if global_skills.exists() and global_skills.resolve() != SKILLS_DIR.resolve():
    all_dirs.append(global_skills)  # global as fallback
all_dirs.append(SKILLS_DIR)         # profile overrides

Or alternatively, document this behaviour prominently in the profiles documentation so users know to symlink categories they need.

Workaround

ln -s ~/.hermes/skills/<category> ~/.hermes/profiles/<name>/skills/<category>

Environment

• Hermes version: git main (2026-05-26)
• macOS 14.5
• Profile with cloned skills directory