Skip to content

The agent that grows with you

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.py
index 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 than
rescanning on every lookup. Any other error raises: the catalog scan itself takes the same signature
unguarded (``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_signature
try:
- 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.py
index 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.py
index 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.py
index 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 filtered
def _compute():
all_skills = _quiet(_scan)
diff --git a/hermes_cli/curator.py b/hermes_cli/curator.py
index 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_ARCHIVED
at = skill_usage._parse_iso_timestamp(rec.get("archived_at")) if archived else None
return max(at.timestamp(), p.stat().st_mtime) if at else p.stat().st_mtime
diff --git a/hermes_cli/gateway_plugin_commands.py b/hermes_cli/gateway_plugin_commands.py
index 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.py
index 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 = 10
diff --git a/hermes_cli/profiles.py b/hermes_cli/profiles.py
index 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 of
traversing 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.py
index 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[st
def _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.py
index 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_skills
entries.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:
pass
diff --git a/hermes_cli/web_routers/skills.py b/hermes_cli/web_routers/skills.py
index 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_skills
from hermes_cli.skills_config import get_disabled_skills
from 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.py
index 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) == 1
assert matching[0]["description"] == "Local version"
diff --git a/tests/gateway/test_api_server.py b/tests/gateway/test_api_server.py
index 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.py
index 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(tm
from gateway.session_authority import initialize_session_authority
from gateway.session_controls import AuthorityConnection
from hermes_cli import banner
- from tools.skills_tool import _find_all_skills
+ from tools.skills_tool import find_all_skills
home = 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(tm
assert 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.py
index 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 are
actually observed."""
from hermes_cli import banner
banner._available_skills_cache = None
@@ -20,8 +20,8 @@ def _reset_skills_cache():
banner._available_skills_cache = None
def 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_skills
result = 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_skills
result = get_available_skills()
diff --git a/tests/hermes_cli/test_plugin_validate_private_imports.py b/tests/hermes_cli/test_plugin_validate_private_imports.py
index 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.py
index 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 _su
monkeypatch.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.py
index 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_tool
monkeypatch.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, i
assert cli_hub.do_install(identifier, console=console, skip_confirm=True) is True
assert "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.py
index 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) == origin
assert 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.py
index 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 patch
from 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 hash
manifest_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 dest
def 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.py
index 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.py
index 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 contributor
commit: 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 annotates
s['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"] = False
first.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.py
index 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.py
index 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):
continue
if (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 names
except (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, Path
external 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_md
def _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) == 14
and 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:
continue
for 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 names
diff --git a/tools/skills_sync.py b/tools/skills_sync.py
index 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_dir
from 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_name
from 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_hash
def _move_dir(src: Path, dest: Path) -> None:
@@ -232,7 +232,7 @@ def _recover_renamed_skill(st: "_SyncState", skill_name: str, dest: Path) -> Opt
if st.active_index is None: # by frontmatter name
st.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_hash
st.shadowed_by_external.append(skill_name)
st.skipped += 1
st.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_hash
else:
st.say(
@@ -359,7 +359,7 @@ def _update_existing_skill(st: _SyncState, skill_name: str, skill_src: Path, des
if origin_hash and bundled_hash == origin_hash: # bundled unchanged: skip without hashing the user copy
st.skipped += 1
return
- 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_hash
st.skipped += 1
@@ -418,7 +418,7 @@ def sync_skills(quiet: bool = False) -> dict:
st.suppressed.append(skill_name)
continue
dest = _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 name
archive = _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.py
index 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 does
skill_usage.set_state(name, skill_usage.STATE_ACTIVE)
diff --git a/tools/skills_sync_optional.py b/tools/skills_sync_optional.py
index 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_hash
return 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)] = value
return index
@@ -144,14 +144,14 @@ def restore_official_optional_skill(name: str, *, restore: bool = False) -> dict
backup_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.parent
if 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:
continue
dest, 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):
continue
timestamp = datetime.now(UTC).isoformat()
installed[lock_name] = {
diff --git a/tools/skills_tool.py b/tools/skills_tool.py
index 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 drive
paths 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 and
unloadable 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_manager
discover_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, None
if 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, None
return 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 = None
if ":" 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 error
try: # read once — reused for platform check and main content
diff --git a/tui_gateway/command_discovery.py b/tui_gateway/command_discovery.py
index 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) -> st
collision_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.md
index 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 pack
A plugin can add a UI language or override the wording of an existing one for every surface at once —