The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
feat(plugins): public names for the skills tool's discovery and lookup helpers
Teknium93fafc4d6fff
diff --git a/agent/skill_commands.py b/agent/skill_commands.pyindex 61ee7beac25..b46661c70c3 100644--- a/agent/skill_commands.py+++ b/agent/skill_commands.py@@ -595,9 +595,9 @@ def _skill_dirs_signature() -> Optional[tuple]:it cannot be computed (a root that cannot be stat'ed), which keeps the published map rather thanrescanning on every lookup. Any other error raises: the catalog scan itself takes the same signatureunguarded (``tools.skills_tool._skill_catalog``), and a swallowed bug would pin a stale map silently."""- from tools.skills_tool import _get_disabled_skill_names, _skill_search_dirs, _skills_scan_signature+ from tools.skills_tool import _get_disabled_skill_names, skill_search_dirs, _skills_scan_signaturetry:- roots, _active = _skill_search_dirs()+ roots, _active = skill_search_dirs()return _skills_scan_signature([d for _tier, d in roots], _get_disabled_skill_names())except OSError:logger.debug("Skill dir signature failed", exc_info=True)diff --git a/gateway/platforms/api_server.py b/gateway/platforms/api_server.pyindex f111dfdd018..9e8096c3233 100644--- a/gateway/platforms/api_server.py+++ b/gateway/platforms/api_server.py@@ -2875,9 +2875,9 @@ class APIServerAdapter(OpenAICompatRoutesMixin, BasePlatformAdapter):"""GET /v1/skills — deterministic JSON listing of installed skills (name, description,category), the same set ``/skills list`` shows."""try:- from tools.skills_tool import _find_all_skills, _sort_skills- skills = _sort_skills(- _find_all_skills(+ from tools.skills_tool import find_all_skills, sort_skills+ skills = sort_skills(+ find_all_skills(skip_disabled=False, include_editorial=True))diff --git a/gateway/session_local_inventory.py b/gateway/session_local_inventory.pyindex 9d34aa5d5a3..7b32f0a8814 100644--- a/gateway/session_local_inventory.py+++ b/gateway/session_local_inventory.py@@ -119,7 +119,7 @@ def _cli_skills():saved = skills_tool._SKILLS_CACHE.pop(key, None)try:with scoped_kanban_toolset_selection(["kanban"]):- found = skills_tool._find_all_skills()+ found = skills_tool.find_all_skills()finally:skills_tool._SKILLS_CACHE.pop(key, None)if saved is not None:diff --git a/hermes_cli/banner.py b/hermes_cli/banner.pyindex 52435f732f3..35cbe7369e5 100644--- a/hermes_cli/banner.py+++ b/hermes_cli/banner.py@@ -128,8 +128,8 @@ def get_available_skills() -> dict[str, list[str]]:``prefetch_banner_data()`` pays it off-thread. A failed scan yields ``{}`` and is not cached."""def _scan():- from tools.skills_tool import _find_all_skills- return _find_all_skills() # already filtered+ from tools.skills_tool import find_all_skills+ return find_all_skills() # already filtereddef _compute():all_skills = _quiet(_scan)diff --git a/hermes_cli/curator.py b/hermes_cli/curator.pyindex 96b99aae7a2..fc949df8c51 100644--- a/hermes_cli/curator.py+++ b/hermes_cli/curator.py@@ -445,7 +445,7 @@ def _cmd_purge(args) -> int:# archived_at survives a manual un-archive + re-archive. Never purge before either says so.# Key by the SKILL.md frontmatter name: older archives were flattened under the directory# name (`accelerate` for `huggingface-accelerate`), which is not the usage-record key.- rec = usage.get(skill_usage._read_skill_name(p / "SKILL.md", fallback=p.name)) or {}+ rec = usage.get(skill_usage.read_skill_name(p / "SKILL.md", fallback=p.name)) or {}archived = rec.get("state") == skill_usage.STATE_ARCHIVEDat = skill_usage._parse_iso_timestamp(rec.get("archived_at")) if archived else Nonereturn max(at.timestamp(), p.stat().st_mtime) if at else p.stat().st_mtimediff --git a/hermes_cli/gateway_plugin_commands.py b/hermes_cli/gateway_plugin_commands.pyindex b66247db760..68b7d8ae0a3 100644--- a/hermes_cli/gateway_plugin_commands.py+++ b/hermes_cli/gateway_plugin_commands.py@@ -126,8 +126,8 @@ def skill_notes(cli):if notice is not None:return [notice] if notice else []from agent.skill_commands import skill_command_collision_note- from tools.skills_tool import _find_all_skills- return list(filter(None, (skill_command_collision_note(s["name"]) for s in _find_all_skills())))+ from tools.skills_tool import find_all_skills+ return list(filter(None, (skill_command_collision_note(s["name"]) for s in find_all_skills())))def run_skill(cli, base_cmd, rest):diff --git a/hermes_cli/plugin_validate_private_imports.py b/hermes_cli/plugin_validate_private_imports.pyindex d1380e6a6a3..93f0df56a32 100644--- a/hermes_cli/plugin_validate_private_imports.py+++ b/hermes_cli/plugin_validate_private_imports.py@@ -56,6 +56,10 @@ _PUBLIC = frozenset({"hermes_cli.gateway_setup_wizard:offer_home_channel", "hermes_cli.gateway_setup_wizard:save_env_values","hermes_cli.gateway_setup_wizard:prompt_csv", "hermes_cli.setup:prompt", "hermes_cli.setup:prompt_choice","hermes_cli.setup:prompt_yes_no", "hermes_cli.cli_output",+ # plugins/index.md § Read the skill catalog+ "tools.skills_tool:find_all_skills", "tools.skills_tool:sort_skills", "tools.skills_tool:skill_search_dirs",+ "tools.skills_tool:locate_skill", "tools.skills_tool:skill_lookup_path_error",+ "tools.skills_sync:dir_hash", "tools.skill_usage:read_skill_name",})_SHOWN = 10diff --git a/hermes_cli/profiles.py b/hermes_cli/profiles.pyindex 3399685bab5..b1662b81ad7 100644--- a/hermes_cli/profiles.py+++ b/hermes_cli/profiles.py@@ -1240,7 +1240,7 @@ def _junction_target(path: str) -> Optional[str]:def _copytree_keep_junctions(src: Path, dst: Path, ignore, dirs_exist_ok: bool = False) -> None:"""``shutil.copytree(symlinks=True)`` that re-creates NTFS junctions as junctions instead oftraversing them. A ``skills/foo`` junction into a ``skills.external_dirs`` root copied as a- physical tree is a second same-named candidate and ``_locate_skill`` refuses to guess (#113471).+ physical tree is a second same-named candidate and ``locate_skill`` refuses to guess (#113471).A junction whose target is gone is skipped with a warning, never a crash."""junctions: dict[str, str] = {}diff --git a/hermes_cli/skills_config.py b/hermes_cli/skills_config.pyindex d6be502ebe7..b5a4b0a82e3 100644--- a/hermes_cli/skills_config.py+++ b/hermes_cli/skills_config.py@@ -57,8 +57,8 @@ def save_disabled_skills(config: dict, disabled: set[str], platform: Optional[stdef _list_all_skills() -> list[dict]:"""Return all installed skills (ignoring disabled state)."""try:- from tools.skills_tool import _find_all_skills- return _find_all_skills(skip_disabled=True)+ from tools.skills_tool import find_all_skills+ return find_all_skills(skip_disabled=True)except Exception:return []diff --git a/hermes_cli/slash_exec.py b/hermes_cli/slash_exec.pyindex 83bc0056c93..7060bc26c47 100644--- a/hermes_cli/slash_exec.py+++ b/hermes_cli/slash_exec.py@@ -154,9 +154,9 @@ def _exec_commands(ctx: CommandContext) -> CommandReply:entries.append(f"`{cmd}` — {desc}")# Skills kept off the menu because a built-in owns the name (agent.skill_commands guard).from agent.skill_commands import skill_command_collision_note- from tools.skills_tool import _find_all_skills+ from tools.skills_tool import find_all_skillsentries.extend(f"⚠ {note}" for note in filter(None, map(- skill_command_collision_note, sorted(s["name"] for s in _find_all_skills()))))+ skill_command_collision_note, sorted(s["name"] for s in find_all_skills()))))except Exception:passdiff --git a/hermes_cli/web_routers/skills.py b/hermes_cli/web_routers/skills.pyindex f77ef463825..c354183a3a1 100644--- a/hermes_cli/web_routers/skills.py+++ b/hermes_cli/web_routers/skills.py@@ -342,7 +342,7 @@ async def scan_skill_hub(identifier: str = "", profile: Optional[str] = None):@router.get("/api/skills")async def get_skills(profile: Optional[str] = None):- from tools.skills_tool import _find_all_skills+ from tools.skills_tool import find_all_skillsfrom hermes_cli.skills_config import get_disabled_skillsfrom tools.skill_usage import (_external_skill_names, _read_bundled_names, _read_hub_installed_names, activity_count, load_usage)@@ -351,7 +351,7 @@ async def get_skills(profile: Optional[str] = None):with _profile_scope(profile):config = load_config()disabled = get_disabled_skills(config)- skills = _find_all_skills(skip_disabled=True)+ skills = find_all_skills(skip_disabled=True)usage = load_usage()# Set-based provenance (same classification as skill_usage.provenance,# without a per-skill manifest read): hub > bundled > external > agent.diff --git a/tests/agent/test_external_skills.py b/tests/agent/test_external_skills.pyindex f83738572b1..00a4e3917b4 100644--- a/tests/agent/test_external_skills.py+++ b/tests/agent/test_external_skills.py@@ -74,8 +74,8 @@ class TestExternalSkillsInFindAll:patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}),patch("tools.skills_tool.SKILLS_DIR", local_skills),):- from tools.skills_tool import _find_all_skills- skills = _find_all_skills()+ from tools.skills_tool import find_all_skills+ skills = find_all_skills()names = [s["name"] for s in skills]assert "my-external-skill" in names@@ -94,8 +94,8 @@ class TestExternalSkillsInFindAll:patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}),patch("tools.skills_tool.SKILLS_DIR", local_skills),):- from tools.skills_tool import _find_all_skills- skills = _find_all_skills()+ from tools.skills_tool import find_all_skills+ skills = find_all_skills()matching = [s for s in skills if s["name"] == "my-external-skill"]assert len(matching) == 1assert matching[0]["description"] == "Local version"diff --git a/tests/gateway/test_api_server.py b/tests/gateway/test_api_server.pyindex 11e404bbf9a..64f601650c7 100644--- a/tests/gateway/test_api_server.py+++ b/tests/gateway/test_api_server.py@@ -985,7 +985,7 @@ class TestSkillsEndpoint:{"name": "ascii-art", "description": "ASCII art generation", "category": "creative"},]with patch(- "tools.skills_tool._find_all_skills",+ "tools.skills_tool.find_all_skills",return_value=list(fake_skills),):app = _create_app(adapter)diff --git a/tests/gateway/test_canonical_session_inventory.py b/tests/gateway/test_canonical_session_inventory.pyindex 9f93ba0922f..cc25ef0f0e1 100644--- a/tests/gateway/test_canonical_session_inventory.py+++ b/tests/gateway/test_canonical_session_inventory.py@@ -129,7 +129,7 @@ async def test_cli_surface_counts_kanban_skills_like_main_cli_without_leaking(tmfrom gateway.session_authority import initialize_session_authorityfrom gateway.session_controls import AuthorityConnectionfrom hermes_cli import banner- from tools.skills_tool import _find_all_skills+ from tools.skills_tool import find_all_skillshome = tmp_path / 'home'for name, extra in (('arxiv', ''), ('sdlc-review', 'environments:\n - kanban\n')):@@ -159,4 +159,4 @@ async def test_cli_surface_counts_kanban_skills_like_main_cli_without_leaking(tmassert sorted(cli['skills']['devops']) == ['arxiv', 'sdlc-review'], cli['skills']tui = (await call('session.create', request_id='tui', source='tui', cwd=str(repo)))['info']assert tui['skills']['devops'] == ['arxiv'], tui['skills']- assert [s['name'] for s in _find_all_skills()] == ['arxiv']+ assert [s['name'] for s in find_all_skills()] == ['arxiv']diff --git a/tests/hermes_cli/test_banner_skills.py b/tests/hermes_cli/test_banner_skills.pyindex b7be673b3f8..07d4a553687 100644--- a/tests/hermes_cli/test_banner_skills.py+++ b/tests/hermes_cli/test_banner_skills.py@@ -12,7 +12,7 @@ _MOCK_SKILLS = [@pytest.fixture(autouse=True)def _reset_skills_cache():"""get_available_skills is memoized per-process (startup perf) — reset- the cache around each test so patched _find_all_skills results are+ the cache around each test so patched find_all_skills results areactually observed."""from hermes_cli import bannerbanner._available_skills_cache = None@@ -20,8 +20,8 @@ def _reset_skills_cache():banner._available_skills_cache = Nonedef test_get_available_skills_delegates_to_find_all_skills():- """get_available_skills should call _find_all_skills (which handles filtering)."""- with patch("tools.skills_tool._find_all_skills", return_value=list(_MOCK_SKILLS)):+ """get_available_skills should call find_all_skills (which handles filtering)."""+ with patch("tools.skills_tool.find_all_skills", return_value=list(_MOCK_SKILLS)):from hermes_cli.banner import get_available_skillsresult = get_available_skills()@@ -33,7 +33,7 @@ def test_get_available_skills_delegates_to_find_all_skills():def test_get_available_skills_null_category_becomes_general():"""Skills with None category should be grouped under 'general'."""skills = [{"name": "orphan-skill", "description": "No cat", "category": None}]- with patch("tools.skills_tool._find_all_skills", return_value=skills):+ with patch("tools.skills_tool.find_all_skills", return_value=skills):from hermes_cli.banner import get_available_skillsresult = get_available_skills()diff --git a/tests/hermes_cli/test_plugin_validate_private_imports.py b/tests/hermes_cli/test_plugin_validate_private_imports.pyindex 8019e8832aa..49a0db8ef6f 100644--- a/tests/hermes_cli/test_plugin_validate_private_imports.py+++ b/tests/hermes_cli/test_plugin_validate_private_imports.py@@ -99,3 +99,30 @@ def test_platform_plugin_seams_are_public_and_exist(tmp_path):plugin = _plugin(tmp_path / "chatplat", {"adapter.py": imports})assert _private_warnings(validate_plugin_dir(plugin)) == []+++_SKILL_CATALOG_SEAMS = (+ ("tools.skills_tool", "find_all_skills"), ("tools.skills_tool", "sort_skills"),+ ("tools.skills_tool", "skill_search_dirs"), ("tools.skills_tool", "locate_skill"),+ ("tools.skills_tool", "skill_lookup_path_error"), ("tools.skills_sync", "dir_hash"),+ ("tools.skill_usage", "read_skill_name"),+)+++def test_skill_catalog_seams_are_public_and_drive_the_skills_tools(tmp_path, monkeypatch):+ """The documented skill-catalog helpers import cleanly, raise no private-import finding, and are+ the names ``skills_list`` reads, so a plugin sees exactly what the agent sees."""+ import importlib+ import json++ from tools import skills_tool++ for module, name in _SKILL_CATALOG_SEAMS:+ assert hasattr(importlib.import_module(module), name), f"{module}.{name}"+ imports = "".join(f"from {module} import {name}\n" for module, name in _SKILL_CATALOG_SEAMS)+ assert _private_warnings(validate_plugin_dir(_plugin(tmp_path / "catalog", {"view.py": imports}))) == []++ marker = {"name": "seam-probe-skill", "description": "d", "category": None}+ monkeypatch.setattr(skills_tool, "find_all_skills", lambda **_kw: [dict(marker)])+ listed = json.loads(skills_tool.skills_list())+ assert [s["name"] for s in listed["skills"] if s["name"] == "seam-probe-skill"] == ["seam-probe-skill"]diff --git a/tests/hermes_cli/test_skills_config.py b/tests/hermes_cli/test_skills_config.pyindex 1607597dd61..5048917d189 100644--- a/tests/hermes_cli/test_skills_config.py+++ b/tests/hermes_cli/test_skills_config.py@@ -135,7 +135,7 @@ class TestGetDisabledSkillNames:# ----------------------------------------------------------------------------# _find_all_skills — disabled filtering+# find_all_skills — disabled filtering# ---------------------------------------------------------------------------class TestFindAllSkillsFiltering:@@ -152,8 +152,8 @@ class TestFindAllSkillsFiltering:import agent.skill_utils as _sumonkeypatch.setattr(_st, "SKILLS_DIR", tmp_path)monkeypatch.setattr(_su, "get_external_skills_dirs", list)- from tools.skills_tool import _find_all_skills- skills = _find_all_skills()+ from tools.skills_tool import find_all_skills+ skills = find_all_skills()assert not any(s["name"] == "my-skill" for s in skills)diff --git a/tests/hermes_cli/test_skills_hub.py b/tests/hermes_cli/test_skills_hub.pyindex 76d796e78e9..89ec80ee7a6 100644--- a/tests/hermes_cli/test_skills_hub.py+++ b/tests/hermes_cli/test_skills_hub.py@@ -56,7 +56,7 @@ def three_source_env(monkeypatch, hub_env):from tools import skills_toolmonkeypatch.setattr(hub, "HubLockFile", lambda: _DummyLockFile([_HUB_ENTRY]))- monkeypatch.setattr(skills_tool, "_find_all_skills", lambda **_kwargs: list(_ALL_THREE_SKILLS))+ monkeypatch.setattr(skills_tool, "find_all_skills", lambda **_kwargs: list(_ALL_THREE_SKILLS))monkeypatch.setattr(skills_sync, "_read_manifest", lambda: dict(_BUILTIN_MANIFEST))return hub_env@@ -725,7 +725,7 @@ def test_install_by_name_resolves_to_the_skill_it_names(monkeypatch, tmp_path, iassert cli_hub.do_install(identifier, console=console, skip_confirm=True) is Trueassert "Restored built-in skill" in sink.getvalue()assert name in skills_sync._read_manifest()- assert any(skills_sync._read_skill_name(md, "") == name for md in skills_sync._iter_active_skill_mds())+ assert any(skills_sync.read_skill_name(md, "") == name for md in skills_sync._iter_active_skill_mds())assert name not in skill_usage.read_suppressed_names()assert skill_usage.load_usage()[name]["state"] == skill_usage.STATE_ACTIVE# Already active now: a no-op the user owns, not a failure (exit 0, no reinstall).diff --git a/tests/tools/test_skills_runtime_cache.py b/tests/tools/test_skills_runtime_cache.pyindex dc4dce8f0cc..7d8b1448bc5 100644--- a/tests/tools/test_skills_runtime_cache.py+++ b/tests/tools/test_skills_runtime_cache.py@@ -50,14 +50,14 @@ def test_real_python_compilation_does_not_freeze_update(skill_tree):origin = ss._read_manifest()["demo"]py_compile.compile(str(dest / "scripts/helper.py"), doraise=True)assert list((dest / "scripts/__pycache__").glob("*.pyc"))- assert ss._dir_hash(dest) == origin+ assert ss.dir_hash(dest) == originassert list_user_modified_bundled_skills() == []assert diff_bundled_skill("demo")["diffs"] == []_write(src, "scripts/helper.py", "ANSWER = 2\n")result = ss.sync_skills(quiet=True)assert result["updated"] == ["demo"]assert (dest / "scripts/helper.py").read_text() == "ANSWER = 2\n"- assert ss._read_manifest()["demo"] == ss._dir_hash(src)+ assert ss._read_manifest()["demo"] == ss.dir_hash(src)@pytest.mark.parametrize("cache_path", [@@ -70,7 +70,7 @@ def test_real_python_compilation_does_not_freeze_update(skill_tree):def test_runtime_cache_is_not_hash_or_diff_content(skill_tree, cache_path):src, dest = skill_tree_write(dest, cache_path, "generated")- assert ss._dir_hash(dest) == ss._dir_hash(src)+ assert ss.dir_hash(dest) == ss.dir_hash(src)assert cache_path not in _skill_file_list(dest)assert diff_bundled_skill("demo")["modified"] is False@@ -107,7 +107,7 @@ def test_legacy_cache_hash_migrates_only_with_matching_origin(skill_tree):assert list_user_modified_bundled_skills() == []_write(src, "scripts/helper.py", "ANSWER = 2\n")assert ss.sync_skills(quiet=True)["updated"] == ["demo"]- assert ss._read_manifest()["demo"] == ss._dir_hash(src)+ assert ss._read_manifest()["demo"] == ss.dir_hash(src)def test_legacy_hash_mismatch_never_rebaselines_user_edits(skill_tree):@@ -125,15 +125,15 @@ def test_legacy_hash_mismatch_never_rebaselines_user_edits(skill_tree):def test_clean_manifest_hash_is_backwards_compatible(skill_tree):src, dest = skill_tree- assert ss._dir_hash(src) == _legacy_hash(src)- assert ss._dir_hash(dest) == _legacy_hash(dest)+ assert ss.dir_hash(src) == _legacy_hash(src)+ assert ss.dir_hash(dest) == _legacy_hash(dest)def test_runtime_cache_does_not_hide_dotfile_edit(skill_tree):src, dest = skill_tree_write(dest, ".settings.json", "user settings")_write(dest, ".pytest_cache/v/cache/nodeids", "[]")- assert ss._dir_hash(dest) != ss._dir_hash(src)+ assert ss.dir_hash(dest) != ss.dir_hash(src)assert ".settings.json" in _skill_file_list(dest)assert [e["path"] for e in diff_bundled_skill("demo")["diffs"]] == [".settings.json"]@@ -157,5 +157,5 @@ def test_hash_filter_is_skill_relative(tmp_path):src = tmp_path / "__pycache__" / "demo"_write(src, "SKILL.md", "real skill content")_write(src, "scripts/helper.py", "ANSWER = 1\n")- assert ss._dir_hash(src) == _legacy_hash(src)+ assert ss.dir_hash(src) == _legacy_hash(src)assert set(_skill_file_list(src)) == {"SKILL.md", "scripts/helper.py"}diff --git a/tests/tools/test_skills_sync.py b/tests/tools/test_skills_sync.pyindex b22575c7487..f2e69641761 100644--- a/tests/tools/test_skills_sync.py+++ b/tests/tools/test_skills_sync.py@@ -11,10 +11,10 @@ from unittest.mock import patchfrom tools.skills_sync import (_get_bundled_dir,_read_manifest,- _read_skill_name,+ read_skill_name,_write_manifest,_discover_bundled_skills,- _dir_hash,+ dir_hash,sync_skills,)from tools.skills_sync_bundled_ops import reset_bundled_skill@@ -70,16 +70,16 @@ class TestDirHash:d.mkdir()(d / "SKILL.md").write_text("# Test")(d / "main.py").write_text("print(1)")- assert _dir_hash(dir_a) == _dir_hash(dir_b)+ assert dir_hash(dir_a) == dir_hash(dir_b)(dir_b / "SKILL.md").write_text("# Version 2")- assert _dir_hash(dir_a) != _dir_hash(dir_b)+ assert dir_hash(dir_a) != dir_hash(dir_b)empty = tmp_path / "empty"empty.mkdir()- assert isinstance(_dir_hash(empty), str) and len(_dir_hash(empty)) == 32+ assert isinstance(dir_hash(empty), str) and len(dir_hash(empty)) == 32# A nonexistent dir hashes as empty content rather than raising.- assert isinstance(_dir_hash(tmp_path / "nope"), str)+ assert isinstance(dir_hash(tmp_path / "nope"), str)class TestDiscoverBundledSkills:@@ -114,16 +114,16 @@ class TestReadSkillName:skill_md = tmp_path / "SKILL.md"skill_md.write_text("---\nname: audiocraft-audio-generation\n---\n# Skill")- assert _read_skill_name(skill_md, "audiocraft") == "audiocraft-audio-generation"+ assert read_skill_name(skill_md, "audiocraft") == "audiocraft-audio-generation"skill_md.write_text('---\nname: "serving-llms-vllm"\n---\n')- assert _read_skill_name(skill_md, "vllm") == "serving-llms-vllm"+ assert read_skill_name(skill_md, "vllm") == "serving-llms-vllm"skill_md.write_text("# Just a heading\nNo frontmatter here")- assert _read_skill_name(skill_md, "my-skill") == "my-skill"+ assert read_skill_name(skill_md, "my-skill") == "my-skill"skill_md.write_text("---\nname:\n---\n")- assert _read_skill_name(skill_md, "fallback") == "fallback"+ assert read_skill_name(skill_md, "fallback") == "fallback"def test_discover_uses_frontmatter_name(self, tmp_path):skill_dir = tmp_path / "category" / "audiocraft"@@ -303,7 +303,7 @@ class TestRenamedBundledSkillRecovery:# User's copy sits at the OLD path, byte-identical to what sync wrote.old = self._skill(skills_dir, "oldcat/moved-skill")- origin_hash = _dir_hash(old)+ origin_hash = dir_hash(old)manifest_file.parent.mkdir(parents=True, exist_ok=True)manifest_file.write_text(f"moved-skill:{origin_hash}\n")@@ -324,7 +324,7 @@ class TestRenamedBundledSkillRecovery:assert "moved-skill" in result["updated"]assert "Updated upstream" in (new / "SKILL.md").read_text()# Future syncs can now detect further upstream changes.- assert recorded == _dir_hash(bundled / "newcat" / "moved-skill")+ assert recorded == dir_hash(bundled / "newcat" / "moved-skill")def test_rename_leaves_user_modified_and_hub_owned_copies_alone(self, tmp_path):"""A user-edited copy is never moved or overwritten, and a hub-owned@@ -334,12 +334,12 @@ class TestRenamedBundledSkillRecovery:manifest_file = skills_dir / ".bundled_manifest"edited = self._skill(skills_dir, "oldcat/moved-skill")- edited_hash = _dir_hash(edited)+ edited_hash = dir_hash(edited)# User then edits their copy, so it no longer matches the origin hash.(edited / "SKILL.md").write_text("---\nname: moved-skill\n---\n# MY EDITS\n")hub = self._skill(skills_dir, "oldcat/hub-skill", name="hub-skill")- hub_hash = _dir_hash(hub)+ hub_hash = dir_hash(hub)manifest_file.parent.mkdir(parents=True, exist_ok=True)manifest_file.write_text(@@ -461,7 +461,7 @@ class TestSyncSkills:skills_dir = tmp_path / "user_skills"manifest_file = skills_dir / ".bundled_manifest"skills_dir.mkdir(parents=True)- old_hash = _dir_hash(bundled / "old-skill")+ old_hash = dir_hash(bundled / "old-skill")manifest_file.write_text(f"old-skill:{old_hash}\nremoved-skill:def456\n")with self._patches(bundled, skills_dir, manifest_file):@@ -488,7 +488,7 @@ class TestSyncSkills:user_skill = skills_dir / "old-skill"user_skill.mkdir(parents=True)(user_skill / "SKILL.md").write_text("# Old v1")- manifest_file.write_text(f"old-skill:{_dir_hash(user_skill)}\n")+ manifest_file.write_text(f"old-skill:{dir_hash(user_skill)}\n")with self._patches(bundled, skills_dir, manifest_file):def failing_copytree(src, dst, *a, **kw):@@ -623,7 +623,7 @@ class TestResetBundledSkill:# After reset, the manifest should hold the *current* bundled hashmanifest_after = _read_manifest()- expected = _dir_hash(bundled / "productivity" / "google-workspace")+ expected = dir_hash(bundled / "productivity" / "google-workspace")assert manifest_after["google-workspace"] == expected# User's copy was preserved (we didn't delete)assert dest.exists()@@ -885,7 +885,7 @@ class TestUpdateBackupRecovery:dest.mkdir(parents=True)(dest / "SKILL.md").write_text(text)with patch("tools.skills_sync.MANIFEST_FILE", manifest_file):- _write_manifest({"old-skill": _dir_hash(dest)})+ _write_manifest({"old-skill": dir_hash(dest)})return destdef test_stale_backup_does_not_poison_failed_update(self, tmp_path):diff --git a/tests/tools/test_skills_tool.py b/tests/tools/test_skills_tool.pyindex 605ca2da73c..a44afb76c17 100644--- a/tests/tools/test_skills_tool.py+++ b/tests/tools/test_skills_tool.py@@ -14,7 +14,7 @@ from tools.skills_tool import (_parse_frontmatter,_parse_tags,_get_category_from_path,- _find_all_skills,+ find_all_skills,skill_matches_platform,skills_list,skill_view,@@ -201,7 +201,7 @@ class TestGetCategoryFromPath:# ----------------------------------------------------------------------------# _find_all_skills+# find_all_skills# ---------------------------------------------------------------------------@@ -238,7 +238,7 @@ class TestFindAllSkills:encoding="utf-8",)- skills = _find_all_skills()+ skills = find_all_skills()assert {s["name"] for s in skills} == {"skill-a", "skill-b", "axolotl"}assert [s["category"] for s in skills if s["name"] == "axolotl"] == ["mlops"]@@ -257,7 +257,7 @@ class TestFindAllSkills:)with patch("tools.skills_tool.SKILLS_DIR", tmp_path):- skills = {s["name"]: s for s in _find_all_skills()}+ skills = {s["name"]: s for s in find_all_skills()}# If no description in frontmatter, the first non-header line is used.assert skills["no-desc"]["description"] == "First paragraph."@@ -272,7 +272,7 @@ class TestFindAllSkills:_make_skill(external_category.parent, "knowledge-brain", category="linked")with patch("tools.skills_tool.SKILLS_DIR", skills_root):- skills = _find_all_skills()+ skills = find_all_skills()assert [s["name"] for s in skills] == ["knowledge-brain"]assert skills[0]["category"] == "linked"@@ -579,12 +579,12 @@ class TestSkillMatchesPlatform:# ----------------------------------------------------------------------------# _find_all_skills — platform filtering integration+# find_all_skills — platform filtering integration# ---------------------------------------------------------------------------class TestFindAllSkillsPlatformFiltering:- """Test that _find_all_skills respects the platforms field."""+ """Test that find_all_skills respects the platforms field."""def test_discovery_filters_on_platform(self, tmp_path):# Host-native: a skill tagged only for a platform that is never the@@ -595,13 +595,13 @@ class TestFindAllSkillsPlatformFiltering:_make_skill(tmp_path, "cross-plat", frontmatter_extra=f"platforms: [plan9, {sys.platform}]\n")- names = {s["name"] for s in _find_all_skills()}+ names = {s["name"] for s in find_all_skills()}assert names == {"universal-skill", "cross-plat"}# ----------------------------------------------------------------------------# _find_all_skills — env-var prerequisites must not change the listing+# find_all_skills — env-var prerequisites must not change the listing# ---------------------------------------------------------------------------@@ -624,7 +624,7 @@ class TestFindAllSkillsSecureSetup:frontmatter_extra="prerequisites:\n env_vars: [MY_PRESENT_KEY]\n",)_make_skill(tmp_path, "simple-skill")- skills = _find_all_skills()+ skills = find_all_skills()assert {s["name"] for s in skills} == {"needs-key", "has-key", "simple-skill"}for skill in skills:diff --git a/tests/tools/test_skills_tool_discovery_cache.py b/tests/tools/test_skills_tool_discovery_cache.pyindex b6232efa747..83e1f08bd2e 100644--- a/tests/tools/test_skills_tool_discovery_cache.py+++ b/tests/tools/test_skills_tool_discovery_cache.py@@ -1,4 +1,4 @@-"""Regression tests for the _find_all_skills discovery cache (#58985 salvage).+"""Regression tests for the find_all_skills discovery cache (#58985 salvage).Covers the cache-signature fix layered on the cherry-picked contributorcommit: the original keyed the cache on the max mtime of only the TOP-LEVEL@@ -44,14 +44,14 @@ def test_cache_hit_serves_copies_not_cache_objects(tmp_path):"""Callers mutate the returned dicts (web_server annotatess['enabled']/s['usage']) — the cache must hand out per-call copies."""_write_skill(tmp_path, "cat-a", "skill-one")- first = st._find_all_skills()+ first = st.find_all_skills()assert [s["name"] for s in first] == ["skill-one"]# Mutate what the first caller got; the next (cached) call must be clean.first[0]["enabled"] = Falsefirst.append({"name": "junk"})- second = st._find_all_skills()+ second = st.find_all_skills()assert [s["name"] for s in second] == ["skill-one"]assert "enabled" not in second[0], "cache poisoned by caller mutation"assert second is not first@@ -62,7 +62,7 @@ def test_disabled_and_full_views_cached_separately(tmp_path, monkeypatch):_write_skill(tmp_path, "cat-a", "skill-two")monkeypatch.setattr(st, "_get_disabled_skill_names", lambda: {"skill-two"})- filtered = sorted(s["name"] for s in st._find_all_skills())- everything = sorted(s["name"] for s in st._find_all_skills(skip_disabled=True))+ filtered = sorted(s["name"] for s in st.find_all_skills())+ everything = sorted(s["name"] for s in st.find_all_skills(skip_disabled=True))assert filtered == ["skill-one"]assert everything == ["skill-one", "skill-two"]diff --git a/tools/setup_beat_tool.py b/tools/setup_beat_tool.pyindex 55c80aa3e2a..611a15b8dd0 100644--- a/tools/setup_beat_tool.py+++ b/tools/setup_beat_tool.py@@ -79,9 +79,9 @@ def _skill_resolver() -> Callable[[str], str | None]:"""A written first-task skill name -> the name skill_view loads it with here, or None. A plugin skill(``blender:blender``) resolves through the installed catalog plugin to its registered name."""from hermes_cli.plugins_activation_live import catalog_plugin_skill- from tools.skills_tool import _find_all_skills+ from tools.skills_tool import find_all_skills- bundled = {skill["name"] for skill in _find_all_skills()}+ bundled = {skill["name"] for skill in find_all_skills()}return lambda name: catalog_plugin_skill(name) if ":" in name else (name if name in bundled else None)diff --git a/tools/skill_usage.py b/tools/skill_usage.pyindex 0eab4f685fe..6e90cfb2fd8 100644--- a/tools/skill_usage.py+++ b/tools/skill_usage.py@@ -176,7 +176,7 @@ def _read_hub_installed_names() -> set[str]:except (OSError, ValueError):continueif (resolved / "SKILL.md").exists():- names.add(_read_skill_name(resolved / "SKILL.md", fallback=resolved.name))+ names.add(read_skill_name(resolved / "SKILL.md", fallback=resolved.name))return namesexcept (OSError, json.JSONDecodeError) as e:logger.debug("Failed to read hub lock file: %s", e)@@ -217,7 +217,7 @@ def _iter_skill_mds(base: Path, *, local_only: bool) -> Iterator[tuple[str, Pathexternal skill dirs mounted below the tree (curation must not touch them)."""for skill_md in base.rglob("SKILL.md"):if not (is_excluded_skill_path(skill_md) or (local_only and is_external_skill_path(skill_md))):- yield _read_skill_name(skill_md, fallback=skill_md.parent.name), skill_md+ yield read_skill_name(skill_md, fallback=skill_md.parent.name), skill_mddef _scan_local_skills(keep: Callable[[str, Path, set[str], dict[str, Any]], bool]) -> list[str]:@@ -243,7 +243,7 @@ def list_archived_skill_names() -> list[str]:return sorted({p.name for p in root.iterdir() if p.is_dir()}) if root.exists() else []-def _read_skill_name(skill_md: Path, fallback: str) -> str:+def read_skill_name(skill_md: Path, fallback: str) -> str:"""The frontmatter ``name:`` field of a SKILL.md (first 4000 chars), else *fallback*."""try:lines = [line.strip() for line in skill_md.read_text(encoding="utf-8-sig", errors="replace")[:4000].split("\n")]@@ -663,7 +663,7 @@ def restore_skill(skill_name: str) -> tuple[bool, str]:candidates = [p for p in dirs if p.name == skill_name] or sorted((p for p in dirs if p.name.startswith(prefix) and len(p.name) - len(prefix) == 14and p.name[len(prefix):].isdigit()), reverse=True) or [- p for p in dirs if (p / "SKILL.md").is_file() and _read_skill_name(p / "SKILL.md", fallback=p.name) == skill_name]+ p for p in dirs if (p / "SKILL.md").is_file() and read_skill_name(p / "SKILL.md", fallback=p.name) == skill_name]if not candidates:return False, f"skill '{skill_name}' not found in archive"if (dest := _skills_dir() / skill_name).exists():@@ -672,7 +672,7 @@ def restore_skill(skill_name: str) -> tuple[bool, str]:def _match_skill_dir(skill_mds: Iterable[Path], skill_name: str) -> Optional[Path]:- return next((p.parent for p in skill_mds if _read_skill_name(p, fallback=p.parent.name) == skill_name), None)+ return next((p.parent for p in skill_mds if read_skill_name(p, fallback=p.parent.name) == skill_name), None)def _find_skill_dir(skill_name: str) -> Optional[Path]:@@ -721,7 +721,7 @@ def _external_skill_names() -> set:continuefor skill_md in base.rglob("SKILL.md"):if not is_excluded_skill_path(skill_md):- names.add(_read_skill_name(skill_md, fallback=skill_md.parent.name))+ names.add(read_skill_name(skill_md, fallback=skill_md.parent.name))return namesdiff --git a/tools/skills_sync.py b/tools/skills_sync.pyindex 396d8898747..05c52dba249 100644--- a/tools/skills_sync.py+++ b/tools/skills_sync.py@@ -25,7 +25,7 @@ for _stream in (sys.stdout, sys.stderr):_stream.reconfigure(encoding="utf-8", errors="replace")from hermes_constants import get_bundled_skills_dir, get_hermes_home, get_optional_skills_dirfrom agent.skill_utils import ESSENTIAL_SKILLS, is_excluded_skill_path-from tools.skill_usage import _read_skill_name+from tools.skill_usage import read_skill_namefrom tools.skills_sync_optional import (_backfill_optional_provenance, _ignore_runtime_cache, _is_runtime_cache, _read_hub_install_paths,)@@ -105,7 +105,7 @@ def _build_external_skill_index() -> set[str]:external_names: set[str] = set()for ext_dir in get_external_skills_dirs():for skill_md in _iter_skill_mds(ext_dir):- external_names.update({skill_md.parent.name, _read_skill_name(skill_md, "")})+ external_names.update({skill_md.parent.name, read_skill_name(skill_md, "")})external_names.discard("")return external_names@@ -174,7 +174,7 @@ def _discover_bundled_skills(bundled_dir: Path) -> list[tuple[str, Path]]:if not bundled_dir.exists():return []return [- (_read_skill_name(md, md.parent.name), md.parent)+ (read_skill_name(md, md.parent.name), md.parent)for md in bundled_dir.rglob("SKILL.md")if not is_excluded_skill_path(md.relative_to(bundled_dir), root=bundled_dir)]@@ -184,7 +184,7 @@ def _compute_relative_dest(skill_dir: Path, bundled_dir: Path) -> Path:return _skills_dir() / skill_dir.relative_to(bundled_dir)-def _dir_hash(directory: Path, *, include_runtime_cache: bool = False) -> str:+def dir_hash(directory: Path, *, include_runtime_cache: bool = False) -> str:"""MD5 of package paths/content, excluding generated runtime state.The legacy option is only for proving an exact pre-filter origin match.@@ -208,8 +208,8 @@ def _matches_origin_hash(directory: Path, origin_hash: str, user_hash: Optional["""if not origin_hash:return False- current = _dir_hash(directory) if user_hash is None else user_hash- return current == origin_hash or _dir_hash(directory, include_runtime_cache=True) == origin_hash+ current = dir_hash(directory) if user_hash is None else user_hash+ return current == origin_hash or dir_hash(directory, include_runtime_cache=True) == origin_hashdef _move_dir(src: Path, dest: Path) -> None:@@ -232,7 +232,7 @@ def _recover_renamed_skill(st: "_SyncState", skill_name: str, dest: Path) -> Optif st.active_index is None: # by frontmatter namest.active_index = {}for md in _iter_active_skill_mds():- st.active_index.setdefault(_read_skill_name(md, md.parent.name), []).append(md.parent)+ st.active_index.setdefault(read_skill_name(md, md.parent.name), []).append(md.parent)st.hub_paths = _read_hub_install_paths()for candidate in st.active_index.get(skill_name, []):if candidate == dest or not candidate.is_dir():@@ -299,7 +299,7 @@ def _defer_to_external(st: _SyncState, skill_name: str, dest: Path, bundled_hashst.shadowed_by_external.append(skill_name)st.skipped += 1st.say(f" ⇢ {skill_name} (deferred to external_dirs, not written to local tree)")- if dest.exists() and _dir_hash(dest) == bundled_hash:+ if dest.exists() and dir_hash(dest) == bundled_hash:_rmtree_writable(dest)st.say(f" ✓ removed stale shadow of {skill_name}")st.manifest.pop(skill_name, None)@@ -312,7 +312,7 @@ def _install_new_skill(st: _SyncState, skill_name: str, skill_src: Path, dest: P# Never overwrite a same-named user skill. Baseline the manifest only when# byte-identical: a differing copy's bundled_hash reads as "user-modified" forever.st.skipped += 1- if _dir_hash(dest) == bundled_hash:+ if dir_hash(dest) == bundled_hash:st.manifest[skill_name] = bundled_hashelse:st.say(@@ -359,7 +359,7 @@ def _update_existing_skill(st: _SyncState, skill_name: str, skill_src: Path, desif origin_hash and bundled_hash == origin_hash: # bundled unchanged: skip without hashing the user copyst.skipped += 1return- user_hash = _dir_hash(dest)+ user_hash = dir_hash(dest)if not origin_hash: # v1 migration: baseline from user's copy (can't tell edit from upstream)st.manifest[skill_name] = user_hashst.skipped += 1@@ -418,7 +418,7 @@ def sync_skills(quiet: bool = False) -> dict:st.suppressed.append(skill_name)continuedest = _compute_relative_dest(skill_src, bundled_dir)- bundled_hash = _dir_hash(skill_src)+ bundled_hash = dir_hash(skill_src)# Recoveries run BEFORE classification so a missing dest isn't misread as user-deleted._recover_orphan_backup(dest)if not dest.exists() and skill_name in st.manifest and _recover_renamed_skill(st, skill_name, dest):@@ -439,7 +439,7 @@ def sync_skills(quiet: bool = False) -> dict:present = set()if removed: # curator archive is flat: directory name == skill namearchive = _skills_dir() / ".archive"- present = {_read_skill_name(md, md.parent.name) for md in _iter_active_skill_mds()} | (+ present = {read_skill_name(md, md.parent.name) for md in _iter_active_skill_mds()} | ({p.name for p in archive.iterdir() if p.is_dir()} if archive.is_dir() else set())cleaned = [name for name in removed if name not in present]for name in cleaned:diff --git a/tools/skills_sync_bundled_ops.py b/tools/skills_sync_bundled_ops.pyindex 86f888e9082..b76939aec8f 100644--- a/tools/skills_sync_bundled_ops.py+++ b/tools/skills_sync_bundled_ops.py@@ -97,8 +97,8 @@ def ensure_bundled_skill(name: str) -> dict:# SKILL.md counts as present too.skill_md = dest / "SKILL.md"active = next((md.parent for md in ss._iter_active_skill_mds()- if ss._read_skill_name(md, md.parent.name) == name), None) or (- dest if skill_md.is_file() and ss._read_skill_name(skill_md, name) == name else None)+ if ss.read_skill_name(md, md.parent.name) == name), None) or (+ dest if skill_md.is_file() and ss.read_skill_name(skill_md, name) == name else None)if active is not None or name in ss._build_external_skill_index():return {"ok": True, "action": "present", "path": active, "message": ""}try: # the hub's containment check: a symlinked category must not carry the copy out of skills/@@ -119,7 +119,7 @@ def ensure_bundled_skill(name: str) -> dict:except (OSError, ValueError) as e:return {"ok": False, "action": "not_restored", "path": dest,"message": f"Could not copy the built-in skill '{name}' to {dest}: {e}"}- manifest[name] = ss._dir_hash(src)+ manifest[name] = ss.dir_hash(src)ss._write_manifest(manifest)skill_usage._toggle_suppressed_name(name, add=False) # lift a curator prune the way restore_skill doesskill_usage.set_state(name, skill_usage.STATE_ACTIVE)diff --git a/tools/skills_sync_optional.py b/tools/skills_sync_optional.pyindex ffb62876e34..bec24f64c83 100644--- a/tools/skills_sync_optional.py+++ b/tools/skills_sync_optional.py@@ -26,7 +26,7 @@ def _content_hash(directory: Path) -> str:from tools.skills_guard import content_hashreturn content_hash(directory)except Exception:- return _ss()._dir_hash(directory)+ return _ss().dir_hash(directory)def _safe_rel_install_path(path: Path, base: Path) -> str:@@ -109,7 +109,7 @@ def _optional_skill_index() -> dict[str, tuple[str, str, Path]]:if optional_dir.exists():for skill_md, src, install_path in _iter_optional_skills(optional_dir, root_relative=True):value = (src.name, install_path, src)- index[src.name] = index[ss._read_skill_name(skill_md, src.name)] = value+ index[src.name] = index[ss.read_skill_name(skill_md, src.name)] = valuereturn index@@ -144,14 +144,14 @@ def restore_official_optional_skill(name: str, *, restore: bool = False) -> dictbackup_root = ss._skills_dir() / ".restore-backups" / f"official-optional-{timestamp}"for folder_name, install_path, src in targets if restore else []:dest = ss._skills_dir() / Path(*install_path.split("/"))- canonical_ok = dest.exists() and ss._dir_hash(dest) == ss._dir_hash(src)+ canonical_ok = dest.exists() and ss.dir_hash(dest) == ss.dir_hash(src)# Active copies by frontmatter name or folder slug (the curator may have moved the skill# into another category); ``dest`` itself is handled below.- names = {folder_name, ss._read_skill_name(src / "SKILL.md", folder_name)}+ names = {folder_name, ss.read_skill_name(src / "SKILL.md", folder_name)}for md in ss._iter_active_skill_mds(sort=True):match = md.parentif match != dest and match.exists() and (- match.name == folder_name or ss._read_skill_name(md, match.name) in names):+ match.name == folder_name or ss.read_skill_name(md, match.name) in names):backed_up.append(_move_to_restore_backup(match, backup_root))if dest.exists() and not canonical_ok:backed_up.append(_move_to_restore_backup(dest, backup_root))@@ -216,7 +216,7 @@ def _backfill_optional_provenance(quiet: bool = False) -> list[str]:if (found := _relocated_dest(src.name, installed_dir_index)) is None:continuedest, install_path = found # still requires a byte-identical hash below- if install_path in existing_paths or ss._dir_hash(dest) != ss._dir_hash(src):+ if install_path in existing_paths or ss.dir_hash(dest) != ss.dir_hash(src):continuetimestamp = datetime.now(UTC).isoformat()installed[lock_name] = {diff --git a/tools/skills_tool.py b/tools/skills_tool.pyindex 18da540d195..a6f8d186048 100644--- a/tools/skills_tool.py+++ b/tools/skills_tool.py@@ -101,7 +101,7 @@ _secret_capture_callback = None_LOOKUP_HINT = "Use a skill name or relative path within the skills directory."-def _skill_lookup_path_error(name: str) -> Optional[str]:+def skill_lookup_path_error(name: str) -> Optional[str]:"""Error if lookup *name* could escape the search roots it is joined onto. Windows drivepaths are rejected too: their ``:`` would be misread as a plugin namespace separator."""from tools.path_security import has_traversal_component@@ -216,7 +216,7 @@ def _is_skill_disabled(*names: str, platform: str | None = None) -> bool:return False-def _skill_search_dirs() -> tuple[list[tuple[int, Path]], Path]:+def skill_search_dirs() -> tuple[list[tuple[int, Path]], Path]:"""(``(tier, dir)`` roots in precedence order, active_skills_dir) — the shared``agent.skill_utils.get_skill_search_roots`` order with the live profile dir (dropped if absent)."""from agent.skill_utils import TIER_LOCAL, get_skill_search_roots@@ -235,7 +235,7 @@ def _skill_catalog(*, skip_disabled: bool = False, include_hidden: bool = False)TIER_PROJECT, is_disabled_entry, iter_project_skill_files, iter_skill_index_files, resolve_skill_catalog)cache_key = ("with_disabled" if skip_disabled else "filtered", include_hidden)disabled = set() if skip_disabled else _get_disabled_skill_names()- roots, _ = _skill_search_dirs()+ roots, _ = skill_search_dirs()signature = _skills_scan_signature([d for _t, d in roots], disabled)now = time.monotonic()cached = _SKILLS_CACHE.get(cache_key)@@ -274,7 +274,7 @@ def _skill_catalog(*, skip_disabled: bool = False, include_hidden: bool = False)return [dict(s) for s in skills]-def _find_all_skills(*, skip_disabled: bool = False) -> list[dict[str, Any]]:+def find_all_skills(*, skip_disabled: bool = False) -> list[dict[str, Any]]:"""Loadable skills (name, description, category): ``name`` is what skill_view() accepts —the declared name, or the exact relative path for a same-tier duplicate. Shadowed andunloadable copies are left out. ``skip_disabled=True`` ignores disabled state (config UI)."""@@ -282,7 +282,7 @@ def _find_all_skills(*, skip_disabled: bool = False) -> list[dict[str, Any]]:for s in _skill_catalog(skip_disabled=skip_disabled) if s["load_name"]]-def _sort_skills(skills: list[dict[str, Any]]) -> list[dict[str, Any]]:+def sort_skills(skills: list[dict[str, Any]]) -> list[dict[str, Any]]:"""Keep every skill listing path ordered the same way."""return sorted(skills, key=lambda s: (s.get("category") or "", s["name"]))@@ -291,7 +291,7 @@ def skills_list(category: str | None = None, task_id: str | None = None) -> str:"""Tier 1 listing: name + description (+ category) only; ``task_id`` is handler parity."""try:_skills_dir().mkdir(parents=True, exist_ok=True)- all_skills = _find_all_skills()+ all_skills = find_all_skills()try:from hermes_cli.plugins import discover_plugins, get_plugin_managerdiscover_plugins()@@ -307,7 +307,7 @@ def skills_list(category: str | None = None, task_id: str | None = None) -> str:"message": "No skills found in skills/ directory."})if category:all_skills = [s for s in all_skills if s.get("category") == category]- all_skills = _sort_skills(all_skills)+ all_skills = sort_skills(all_skills)categories = sorted({s.get("category") for s in all_skills if s.get("category")})return _json({"success": True, "skills": all_skills, "categories": categories,@@ -510,7 +510,7 @@ def _owning_search_dir(skill_md: Path, all_dirs) -> Optional[Path]:return max(owners, key=lambda d: len(d.parts), default=None)-def _locate_skill(name: str, local_category_name: Optional[str], roots):+def locate_skill(name: str, local_category_name: Optional[str], roots):"""Unique on-disk skill for *name* over ``(tier, dir)`` *roots*: cross-tier precedence(project > local > create_dir > external, shadowed copies logged), same-tier collision refusal,same-root identical-copy ranking, quarantine gate, not-found listing. ``(error_json, skill_dir,@@ -559,7 +559,7 @@ def _locate_skill(name: str, local_category_name: Optional[str], roots):hint="Inspect the skill in the repo checkout, or untrust the repo with ""`hermes skills untrust`."), None, Noneif not skill_md or not skill_md.exists():- available = [s["name"] for s in _sort_skills(_find_all_skills())[:20]]+ available = [s["name"] for s in sort_skills(find_all_skills())[:20]]return _fail(f"Skill '{name}' not found.", available_skills=available,hint="Use skills_list to see all available skills"), None, Nonereturn None, skill_dir, skill_md@@ -598,7 +598,7 @@ def skill_view(try:# Validate before the ':' dispatch so a Windows drive path (C:\skills\foo) can't be# reinterpreted as a plugin namespace.- if lookup_error := _skill_lookup_path_error(name):+ if lookup_error := skill_lookup_path_error(name):return _fail(lookup_error, hint=_LOOKUP_HINT)local_category_name: str | None = Noneif ":" in name: # plugin registry; bare names use the flat-tree scan below@@ -607,11 +607,11 @@ def skill_view(return served# The fall-through form (namespace/bare) joins onto each search dir too; re-validate it# since `bare` is not namespace-checked.- if local_category_name and (lookup_error := _skill_lookup_path_error(local_category_name)):+ if local_category_name and (lookup_error := skill_lookup_path_error(local_category_name)):return _fail(lookup_error, hint=_LOOKUP_HINT)- roots, active_skills_dir = _skill_search_dirs()+ roots, active_skills_dir = skill_search_dirs()all_dirs = [d for _t, d in roots]- error, skill_dir, skill_md = _locate_skill(name, local_category_name, roots)+ error, skill_dir, skill_md = locate_skill(name, local_category_name, roots)if error is not None:return errortry: # read once — reused for platform check and main contentdiff --git a/tui_gateway/command_discovery.py b/tui_gateway/command_discovery.pyindex 497b7c29483..033226188bb 100644--- a/tui_gateway/command_discovery.py+++ b/tui_gateway/command_discovery.py@@ -199,7 +199,7 @@ def _catalog_skills(cat: _Catalog, skills: dict[str, dict], module_loader) -> stcollision_note = getattr(sc, "skill_command_collision_note", None)if collision_note is None:return ""- names = sorted(s["name"] for s in module_loader("tools.skills_tool")._find_all_skills())+ names = sorted(s["name"] for s in module_loader("tools.skills_tool").find_all_skills())return "; ".join(filter(None, map(collision_note, names)))diff --git a/website/docs/developer-guide/plugins/index.md b/website/docs/developer-guide/plugins/index.mdindex e6c64a4f521..41e4cd28878 100644--- a/website/docs/developer-guide/plugins/index.md+++ b/website/docs/developer-guide/plugins/index.md@@ -1037,6 +1037,40 @@ skill_view("my-workflow") # → built-in version (unchanged)The old `shutil.copy2` pattern (copying a skill into `~/.hermes/skills/`) still works but creates name collision risk with built-in skills. Prefer `ctx.register_skill()` for new plugins.:::+### Read the skill catalog++A plugin that shows which skills the agent can see (a catalog view, "open this skill", drift checks+against the installed copy) should call the same helpers the `skills_list` and `skill_view` tools use,+not walk the skill directories itself. These names are public and covered by the compatibility+contract:++| Import | What it gives you |+|---|---|+| `tools.skills_tool.find_all_skills(*, skip_disabled=False)` | Loadable skills as `{"name", "description", "category"}` dicts: the cached, first-wins, platform/environment-gated walk `skills_list` uses. `name` is what `skill_view()` accepts. |+| `tools.skills_tool.sort_skills(skills)` | The one listing order (category, then name). |+| `tools.skills_tool.skill_search_dirs()` | `(roots, active_dir)`: `(tier, dir)` roots in precedence order (project, local, `create_dir`, external) and the live profile's skills dir. |+| `tools.skills_tool.skill_lookup_path_error(name)` | An error string if `name` is absolute or contains `..`, else `None`. Check it before any lookup. |+| `tools.skills_tool.locate_skill(name, category, roots)` | `(error_json, skill_dir, skill_md)` for one name over `roots`: tier precedence, same-tier collision refusal and the project-skill quarantine gate. `skill_md` is set only when `error_json` is `None`. |+| `tools.skills_sync.dir_hash(directory)` | The package hash the bundled-skill sync stores, so you can tell whether a user's copy still matches what was installed. |+| `tools.skill_usage.read_skill_name(skill_md, fallback)` | The frontmatter `name:` of a `SKILL.md`, else `fallback`. |++```python+from tools.skills_tool import find_all_skills, locate_skill, skill_lookup_path_error, skill_search_dirs, sort_skills++def list_skills():+ return sort_skills(find_all_skills())++def open_skill(name):+ if err := skill_lookup_path_error(name):+ return err+ roots, _active = skill_search_dirs()+ error, _skill_dir, skill_md = locate_skill(name, None, roots)+ return error or skill_md.read_text(encoding="utf-8")+```++Plugin-registered skills (`ctx.register_skill`) are not on disk under these roots; `find_all_skills()`+returns the on-disk catalog only.+### Ship a language packA plugin can add a UI language or override the wording of an existing one for every surface at once —