Skip to content

The agent that grows with you

fix(skills): walk the whole catalog tree for the skills scan signature

Teknium33ab01949325
diff --git a/agent/skill_commands.py b/agent/skill_commands.py
index fe1230a3376..568b50d6f81 100644
--- a/agent/skill_commands.py
+++ b/agent/skill_commands.py
@@ -559,9 +559,9 @@ def scan_skill_commands() -> dict[str, dict[str, Any]]:
def _skill_dirs_signature() -> Optional[tuple]:
- """Stat-cheap change signature of every skill root (the catalog's own: each root's mtime and its
- immediate child dirs', the disabled set and the platform). None when it cannot be computed, which
- keeps the published map rather than rescanning on every lookup."""
+ """Stat-cheap change signature of every skill root (the catalog's own: the mtime and child names of
+ every directory the catalog walks, depth-bounded, plus the disabled set and the platform). None when
+ it cannot be computed, which keeps the published map rather than rescanning on every lookup."""
try:
from tools.skills_tool import _get_disabled_skill_names, _skill_search_dirs, _skills_scan_signature
roots, _active = _skill_search_dirs()
diff --git a/tests/agent/test_skill_commands_freshness.py b/tests/agent/test_skill_commands_freshness.py
index 6eb1ad06d84..591b556a783 100644
--- a/tests/agent/test_skill_commands_freshness.py
+++ b/tests/agent/test_skill_commands_freshness.py
@@ -45,3 +45,26 @@ def test_unchanged_skills_dirs_reuse_the_published_map(tmp_path):
first = get_skill_commands()
with patch.object(sc_mod, "scan_skill_commands", side_effect=AssertionError("rescanned")):
assert get_skill_commands() is first
+
+
+def test_a_skill_installed_under_an_existing_category_subdir_is_served(tmp_path):
+ """``skills/mlops/training/<new>/SKILL.md``: the install moves only ``training``'s mtime, two
+ levels below the root, and the published map must still be rescanned (the catalog walks it)."""
+ import agent.skill_commands as sc_mod
+ import tools.skills_tool as st
+ from agent.skill_commands import get_skill_commands
+
+ with patch("tools.skills_tool.SKILLS_DIR", tmp_path), patch.object(sc_mod, "_skill_commands_by_key", {}):
+ st.clear_skills_cache()
+ training = tmp_path / "mlops" / "training"
+ _make_skill(training, "existing")
+ assert set(get_skill_commands()) == {"/existing"}
+ _make_skill(training, "new-nested")
+ assert set(get_skill_commands()) == {"/existing", "/new-nested"}
+ # A skill's own support dirs are not walked: editing references/ is not an install.
+ before = sc_mod._skill_dirs_signature()
+ (training / "existing" / "references").mkdir()
+ (training / "existing" / "references" / "deep").mkdir()
+ after = sc_mod._skill_dirs_signature()
+ assert [row for row in after[0] if "references" in row[0]] == []
+ assert before != after # the skill dir itself gained a child name
diff --git a/tools/skills_tool.py b/tools/skills_tool.py
index 0cbcb8bbf36..18da540d195 100644
--- a/tools/skills_tool.py
+++ b/tools/skills_tool.py
@@ -31,11 +31,14 @@ from tools.skill_provenance import is_background_review
logger = logging.getLogger(__name__)
# Per-session discovery cache: {cache_key: (signature, timestamp, skills_list)}. Signature =
-# per-dir max mtime of the dir and its immediate children (add/remove inside a category does
-# NOT bump the root mtime) + the disabled set (config-only change, no mtime) + platform; the
-# TTL bounds staleness from in-place SKILL.md edits, which no directory signature can see.
+# every catalog directory's mtime and child-dir names, walked like the catalog itself (an install
+# under an existing category such as ``mlops/training/`` moves only that dir's mtime) + the disabled
+# set (config-only change, no mtime) + platform; the TTL bounds staleness from in-place SKILL.md
+# edits, which no directory signature can see.
_SKILLS_CACHE: dict = {}
_SKILLS_CACHE_TTL_SECONDS = 30.0
+# Deepest directory the signature descends to below a root (a skill sits at <cat>/<sub>/<skill>/).
+_SIGNATURE_MAX_DEPTH = 6
def clear_skills_cache() -> None:
@@ -43,27 +46,42 @@ def clear_skills_cache() -> None:
_SKILLS_CACHE.clear()
+def _dir_tree_signature(root, sig, depth=_SIGNATURE_MAX_DEPTH) -> None:
+ """Append ``(dir, mtime_ns, child dir names)`` for *root* and the dirs below it the catalog walks
+ (``iter_skill_index_files``: no excluded dirs, no support dirs of a skill), depth-bounded. The child
+ names, not only mtimes: an install and an uninstall inside one coarse mtime tick (1-2 s on some
+ filesystems) leave every mtime equal, and the change must still show. ~1 ms for 170 dirs."""
+ from agent.skill_utils import EXCLUDED_SKILL_DIRS, SKILL_SUPPORT_DIRS
+ try:
+ mtime = os.stat(root).st_mtime_ns
+ with os.scandir(root) as it:
+ entries = list(it)
+ except OSError:
+ return
+ names, is_skill = [], False
+ for entry in entries:
+ with suppress(OSError):
+ if entry.is_dir():
+ names.append(entry.name)
+ elif entry.name == "SKILL.md":
+ is_skill = True
+ names.sort()
+ sig.append((str(root), mtime, tuple(names)))
+ if depth <= 0:
+ return
+ for name in names:
+ if name not in EXCLUDED_SKILL_DIRS and not (is_skill and name in SKILL_SUPPORT_DIRS):
+ _dir_tree_signature(os.path.join(root, name), sig, depth - 1)
+
+
def _skills_scan_signature(dirs_to_scan, disabled) -> tuple:
- """O(#dirs + #categories) stat-based change signature; platform is read via
+ """Stat-based change signature over every directory the catalog walks; platform is read via
``agent.skill_utils.sys`` so test patches are honored."""
from agent import skill_utils as _skill_utils
platform = getattr(getattr(_skill_utils, "sys", None), "platform", "")
- sig = []
+ sig: list = []
for d in dirs_to_scan:
- try:
- m = d.stat().st_mtime_ns
- except OSError:
- continue
- names = []
- with suppress(OSError), os.scandir(d) as it:
- for entry in it:
- with suppress(OSError):
- if entry.is_dir(follow_symlinks=False):
- m = max(m, entry.stat(follow_symlinks=False).st_mtime_ns)
- names.append(entry.name)
- # The child names, not only mtimes: an install and an uninstall inside one coarse mtime tick
- # (1-2 s on some filesystems) leave every mtime equal, and the change must still show.
- sig.append((str(d), m, tuple(sorted(names))))
+ _dir_tree_signature(str(d), sig)
return (tuple(sig), frozenset(disabled), platform)