skills_tool.py 42 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789
  1. #!/usr/bin/env python3
  2. """Skills Tool — list and view skill documents (progressive disclosure). A skill is a directory
  3. holding SKILL.md (YAML frontmatter + instructions) plus optional references/, templates/, assets/,
  4. scripts/. `skills_list` returns name/description only; `skill_view` returns full content and
  5. linked files. Sibling modules (skills_tool_setup / _plugin / _dedup) re-export here."""
  6. import contextvars
  7. import json
  8. import logging
  9. import os
  10. import time
  11. from contextlib import contextmanager, suppress
  12. from pathlib import Path, PurePosixPath, PureWindowsPath
  13. from typing import Any, Dict, List, Optional, Tuple
  14. from hermes_constants import get_hermes_home
  15. from tools.registry import registry, tool_error
  16. from hermes_cli.config import cfg_get
  17. from agent.skill_utils import (
  18. EXCLUDED_SKILL_DIRS as _EXCLUDED_SKILL_DIRS, is_skill_support_path as _is_skill_support_path)
  19. from tools.skills_tool_setup import (
  20. SkillReadinessStatus, _build_setup_note, _capture_required_environment_variables,
  21. _get_required_environment_variables, _is_env_var_persisted, _is_remote_env_backend)
  22. from tools.skills_tool_plugin import (
  23. MAX_DESCRIPTION_LENGTH, MAX_NAME_LENGTH, _INJECTION_PATTERNS, _fail, _json,
  24. _mark_background_review_read, _preprocess_skill, _read_skill_text, _safe_frontmatter,
  25. _serve_plugin_skill, _serve_skill_file, _truncate_description)
  26. from tools.skills_tool_dedup import dedup_skill_view, reset_skill_view_dedup
  27. from tools.skill_provenance import is_background_review
  28. logger = logging.getLogger(__name__)
  29. # Per-session discovery cache: {cache_key: (signature, timestamp, skills_list)}. Signature =
  30. # every catalog directory's mtime and child-dir names, walked like the catalog itself (an install
  31. # under an existing category such as ``mlops/training/`` moves only that dir's mtime) + the disabled
  32. # set (config-only change, no mtime) + platform; the TTL bounds staleness from in-place SKILL.md
  33. # edits, which no directory signature can see.
  34. _SKILLS_CACHE: dict = {}
  35. _SKILLS_CACHE_TTL_SECONDS = 30.0
  36. # Deepest directory the signature descends to below a root (a skill sits at <cat>/<sub>/<skill>/).
  37. _SIGNATURE_MAX_DEPTH = 6
  38. def clear_skills_cache() -> None:
  39. """Drop the scanned catalog so the next listing re-scans (explicit reloads must not wait out the TTL)."""
  40. _SKILLS_CACHE.clear()
  41. def _dir_tree_signature(root, sig, depth=_SIGNATURE_MAX_DEPTH) -> None:
  42. """Append ``(dir, mtime_ns, child dir names)`` for *root* and the dirs below it the catalog walks
  43. (``iter_skill_index_files``: no excluded dirs, no support dirs of a skill), depth-bounded. The child
  44. names, not only mtimes: an install and an uninstall inside one coarse mtime tick (1-2 s on some
  45. filesystems) leave every mtime equal, and the change must still show. ~1 ms for 170 dirs."""
  46. from agent.skill_utils import EXCLUDED_SKILL_DIRS, SKILL_SUPPORT_DIRS
  47. try:
  48. mtime = os.stat(root).st_mtime_ns
  49. with os.scandir(root) as it:
  50. entries = list(it)
  51. except OSError:
  52. return
  53. names, is_skill = [], False
  54. for entry in entries:
  55. with suppress(OSError):
  56. if entry.is_dir():
  57. names.append(entry.name)
  58. elif entry.name == "SKILL.md":
  59. is_skill = True
  60. names.sort()
  61. sig.append((str(root), mtime, tuple(names)))
  62. if depth <= 0:
  63. return
  64. for name in names:
  65. if name not in EXCLUDED_SKILL_DIRS and not (is_skill and name in SKILL_SUPPORT_DIRS):
  66. _dir_tree_signature(os.path.join(root, name), sig, depth - 1)
  67. def _skills_scan_signature(dirs_to_scan, disabled) -> tuple:
  68. """Stat-based change signature over every directory the catalog walks; platform is read via
  69. ``agent.skill_utils.sys`` so test patches are honored."""
  70. from agent import skill_utils as _skill_utils
  71. platform = getattr(getattr(_skill_utils, "sys", None), "platform", "")
  72. sig: list = []
  73. for d in dirs_to_scan:
  74. _dir_tree_signature(str(d), sig)
  75. return (tuple(sig), frozenset(disabled), platform)
  76. HERMES_HOME = get_hermes_home() # all skills live in ~/.hermes/skills/ (seeded from bundled)
  77. SKILLS_DIR = HERMES_HOME / "skills"
  78. _SKILLS_DIR_AT_IMPORT = SKILLS_DIR
  79. def _skills_dir() -> Path:
  80. """Active profile's skills dir at call time: the patched ``SKILLS_DIR`` when a patcher changed
  81. it, else live profile-scoped HERMES_HOME (long-lived runtimes may import before profile set)."""
  82. configured = Path(SKILLS_DIR)
  83. return configured if configured != _SKILLS_DIR_AT_IMPORT else get_hermes_home() / "skills"
  84. _secret_capture_callback = None
  85. _LOOKUP_HINT = "Use a skill name or relative path within the skills directory."
  86. def skill_lookup_path_error(name: str) -> Optional[str]:
  87. """Error if lookup *name* could escape the search roots it is joined onto. Windows drive
  88. paths are rejected too: their ``:`` would be misread as a plugin namespace separator."""
  89. from tools.path_security import has_traversal_component
  90. if not isinstance(name, str):
  91. return "Skill name must be a string."
  92. win = PureWindowsPath(candidate := name.strip())
  93. if PurePosixPath(candidate).is_absolute() or win.is_absolute() or win.drive:
  94. return "Skill name must be a relative path within the skills directory."
  95. if has_traversal_component(candidate):
  96. return "Skill name cannot contain '..' path traversal components."
  97. return None
  98. def load_env() -> dict[str, str]:
  99. """Snapshot of HERMES_HOME/.env for the post-skill secret-capture diff (same tokenizer that
  100. installs the profile scope, so a captured value never differs from the served one). A frozen-policy
  101. worker never opens the profile ``.env``: ``hermes_cli.config.load_env`` owns that short-circuit."""
  102. from agent.safe_worker_policy import worker_config_snapshot
  103. if worker_config_snapshot() is not None:
  104. return {}
  105. from agent.secret_scope import load_env_file
  106. return load_env_file(get_hermes_home() / ".env")
  107. def set_secret_capture_callback(callback) -> None:
  108. global _secret_capture_callback
  109. _secret_capture_callback = callback
  110. # A turn-scoped capture callback (the session owner binds one per local-viewer turn): it wins over the
  111. # process-global slot and over the gateway-surface "unsupported" hint, because that turn's viewer can
  112. # answer. A ContextVar, so tool worker threads started with ``propagate_context_to_thread`` inherit it.
  113. _turn_secret_capture = contextvars.ContextVar("turn_secret_capture", default=None)
  114. @contextmanager
  115. def bind_turn_secret_capture(callback):
  116. token = _turn_secret_capture.set(callback)
  117. try:
  118. yield
  119. finally:
  120. _turn_secret_capture.reset(token)
  121. def _skill_utils_delegate(attr: str):
  122. """Lazy call-time delegate to ``agent.skill_utils.<attr>`` (re-export; patches honored)."""
  123. def _delegate(*args):
  124. from agent import skill_utils
  125. return getattr(skill_utils, attr)(*args)
  126. _delegate.__name__ = _delegate.__qualname__ = attr
  127. return _delegate
  128. skill_matches_platform = _skill_utils_delegate("skill_matches_platform")
  129. # Offer-time relevance gate (kanban/docker/s6), NOT hard compatibility; explicit loads bypass it.
  130. skill_matches_environment = _skill_utils_delegate("skill_matches_environment")
  131. skill_matches_apps = _skill_utils_delegate("skill_matches_apps")
  132. _parse_frontmatter = _skill_utils_delegate("parse_frontmatter")
  133. _get_disabled_skill_names = _skill_utils_delegate("get_disabled_skill_names")
  134. def check_skills_requirements() -> bool:
  135. return True # always available: the directory is created on first use
  136. def _get_category_from_path(skill_path: Path) -> Optional[str]:
  137. """``~/.hermes/skills/mlops/axolotl/SKILL.md`` -> ``"mlops"``; active profile dir first
  138. (respects test monkeypatching), then skills.external_dirs."""
  139. dirs_to_check = [_skills_dir()]
  140. with suppress(Exception):
  141. from agent.skill_utils import get_external_skills_dirs
  142. dirs_to_check.extend(get_external_skills_dirs())
  143. for skills_dir in dirs_to_check:
  144. with suppress(ValueError):
  145. if len(parts := skill_path.relative_to(skills_dir).parts) >= 3:
  146. return parts[0]
  147. return None
  148. def _parse_tags(tags_value) -> list[str]:
  149. """Tags from frontmatter: a parsed list, "[a, b]", or "a, b"."""
  150. if not tags_value:
  151. return []
  152. if isinstance(tags_value, list):
  153. return [str(t).strip() for t in tags_value if t]
  154. tags_value = str(tags_value).strip()
  155. if tags_value.startswith("[") and tags_value.endswith("]"):
  156. tags_value = tags_value[1:-1]
  157. return [t.strip().strip("\"'") for t in tags_value.split(",") if t.strip()]
  158. def _is_skill_disabled(*names: str, platform: str | None = None) -> bool:
  159. """Any of *names* disabled in config (one config load)? Platform precedence: explicit arg,
  160. ``HERMES_PLATFORM``, session ``HERMES_SESSION_PLATFORM``. A globally-disabled skill stays disabled on every platform
  161. (keep in sync with agent.skill_utils.get_disabled_skill_names)."""
  162. try:
  163. from hermes_cli.config import load_config
  164. skills_cfg = load_config().get("skills", {})
  165. resolved_platform = platform or os.getenv("HERMES_PLATFORM")
  166. if not resolved_platform:
  167. with suppress(Exception):
  168. from gateway.session_context import get_session_env
  169. resolved_platform = get_session_env("HERMES_SESSION_PLATFORM") or ""
  170. platform_disabled = None
  171. if resolved_platform:
  172. platform_disabled = cfg_get(skills_cfg, "platform_disabled", resolved_platform)
  173. disabled = skills_cfg.get("disabled", [])
  174. return any((platform_disabled is not None and n in platform_disabled) or n in disabled for n in names)
  175. except Exception:
  176. return False
  177. def skill_search_dirs() -> tuple[list[tuple[int, Path]], Path]:
  178. """(``(tier, dir)`` roots in precedence order, active_skills_dir) — the shared
  179. ``agent.skill_utils.get_skill_search_roots`` order with the live profile dir (dropped if absent)."""
  180. from agent.skill_utils import TIER_LOCAL, get_skill_search_roots
  181. active_skills_dir = _skills_dir()
  182. roots = [(t, d) for t, d in get_skill_search_roots(active_skills_dir)
  183. if t != TIER_LOCAL or d.exists()]
  184. return roots, active_skills_dir
  185. def _skill_catalog(*, skip_disabled: bool = False, include_hidden: bool = False) -> list[dict[str, Any]]:
  186. """Every scanned skill resolved by ``agent.skill_utils.resolve_skill_catalog`` (status /
  187. load_name / tier / path), visible ones only unless *include_hidden*; cached per session.
  188. Resolution runs over ALL files first — skill_view ignores platform/disabled gates when
  189. collecting candidates, so it asks for hidden rows too."""
  190. from agent.skill_utils import (
  191. TIER_PROJECT, is_disabled_entry, iter_project_skill_files, iter_skill_index_files, resolve_skill_catalog)
  192. cache_key = ("with_disabled" if skip_disabled else "filtered", include_hidden)
  193. disabled = set() if skip_disabled else _get_disabled_skill_names()
  194. roots, _ = skill_search_dirs()
  195. signature = _skills_scan_signature([d for _t, d in roots], disabled)
  196. now = time.monotonic()
  197. cached = _SKILLS_CACHE.get(cache_key)
  198. if cached is not None and cached[0] == signature and (now - cached[1]) < _SKILLS_CACHE_TTL_SECONDS:
  199. # Shallow copies: callers mutate the returned dicts (web_server annotates
  200. # s["enabled"]/s["usage"]); handing out cached objects would poison the cache.
  201. return [dict(s) for s in cached[2]]
  202. scanned = []
  203. for tier, scan_dir in roots: # project dirs go through the quarantine chokepoint
  204. _iter = iter_project_skill_files if tier == TIER_PROJECT else lambda d: iter_skill_index_files(d, "SKILL.md")
  205. for skill_md in _iter(scan_dir):
  206. if any(part in _EXCLUDED_SKILL_DIRS for part in skill_md.parts):
  207. continue
  208. try:
  209. frontmatter, body = _parse_frontmatter(_read_skill_text(skill_md)[:4000])
  210. description = frontmatter.get("description", "")
  211. if not description: # first non-heading body line (a null value stays null)
  212. description = next((ln for ln in map(str.strip, body.strip().split("\n"))
  213. if ln and not ln.startswith("#")), description)
  214. scanned.append({
  215. "name": frontmatter.get("name", skill_md.parent.name)[:MAX_NAME_LENGTH],
  216. "description": _truncate_description(description),
  217. "category": _get_category_from_path(skill_md), "tier": tier, "root": scan_dir,
  218. "path": skill_md, "visible": bool(skill_matches_platform(frontmatter)
  219. and skill_matches_environment(frontmatter)
  220. and skill_matches_apps(frontmatter))})
  221. except (UnicodeDecodeError, PermissionError) as e:
  222. logger.debug("Failed to read skill file %s: %s", skill_md, e)
  223. except Exception as e:
  224. logger.debug("Skipping skill at %s: failed to parse: %s", skill_md, e, exc_info=True)
  225. skills = [s for s in resolve_skill_catalog(scanned)
  226. if (s.pop("visible") or include_hidden) and not is_disabled_entry(s, disabled)]
  227. # Keyed by the signature computed BEFORE the scan: a write racing the scan changes the
  228. # signature, so the next call re-scans instead of serving a torn result.
  229. _SKILLS_CACHE[cache_key] = (signature, now, skills)
  230. return [dict(s) for s in skills]
  231. def find_all_skills(*, skip_disabled: bool = False) -> list[dict[str, Any]]:
  232. """Loadable skills (name, description, category): ``name`` is what skill_view() accepts —
  233. the declared name, or the exact relative path for a same-tier duplicate. Shadowed and
  234. unloadable copies are left out. ``skip_disabled=True`` ignores disabled state (config UI)."""
  235. return [{"name": s["load_name"], "description": s["description"], "category": s["category"]}
  236. for s in _skill_catalog(skip_disabled=skip_disabled) if s["load_name"]]
  237. def sort_skills(skills: list[dict[str, Any]]) -> list[dict[str, Any]]:
  238. """Keep every skill listing path ordered the same way."""
  239. return sorted(skills, key=lambda s: (s.get("category") or "", s["name"]))
  240. def skills_list(category: str | None = None, task_id: str | None = None) -> str:
  241. """Tier 1 listing: name + description (+ category) only; ``task_id`` is handler parity."""
  242. try:
  243. _skills_dir().mkdir(parents=True, exist_ok=True)
  244. all_skills = find_all_skills()
  245. try:
  246. from hermes_cli.plugins import discover_plugins, get_plugin_manager
  247. from agent.runtime_context import current
  248. if current() is not None:
  249. raise LookupError("Embedded skills are admitted by Yaoyao")
  250. discover_plugins()
  251. for plugin_skill in get_plugin_manager().list_plugin_skill_metadata():
  252. frontmatter = plugin_skill.pop("frontmatter", {})
  253. if not skill_matches_platform(frontmatter) or _is_skill_disabled(plugin_skill["name"]):
  254. continue
  255. all_skills.append(plugin_skill)
  256. except Exception:
  257. logger.debug("Plugin skill listing failed", exc_info=True)
  258. if not all_skills:
  259. return _json({"success": True, "skills": [], "categories": [],
  260. "message": "No skills found in skills/ directory."})
  261. if category:
  262. all_skills = [s for s in all_skills if s.get("category") == category]
  263. all_skills = sort_skills(all_skills)
  264. categories = sorted({s.get("category") for s in all_skills if s.get("category")})
  265. return _json({
  266. "success": True, "skills": all_skills, "categories": categories,
  267. "count": len(all_skills),
  268. "hint": "Use skill_view(name) to see full content, tags, and linked files"})
  269. except Exception as e:
  270. return tool_error(str(e), success=False)
  271. def _legacy_portable_skill_name(pm, namespace, bare):
  272. """Portable plugin skills were named ``agent-plugin-<slug>-<sha8>:<skill>`` before they took the
  273. plugin's own name; prompts and cron jobs saved since then may still carry that form. Resolved
  274. through what that exact plugin registered, so a skill it lost to a name clash is not found."""
  275. if not namespace.startswith("agent-plugin-"):
  276. return None
  277. keys = {key for key, loaded in pm._plugins.items()
  278. if loaded.manifest.portable and loaded.manifest.data_namespace == namespace}
  279. return next((qualified for qualified, entry in pm._plugin_skills.items()
  280. if entry.get("plugin_key") in keys and entry.get("bare_name") == bare), None)
  281. def _resolve_plugin_skill(name, file_path, task_id, preprocess):
  282. """``plugin:skill`` dispatch: ``(result_json, None)`` when answered, else ``(None,
  283. local_category_name)`` to fall through to the flat-tree scan — categorized local skills also use
  284. ``category:skill`` in config/gateway prompts, so the on-disk ``category/skill`` form returns."""
  285. from agent.skill_utils import is_valid_namespace, parse_qualified_name
  286. from hermes_cli.plugins import discover_plugins, get_plugin_manager
  287. namespace, bare = parse_qualified_name(name)
  288. if namespace == "plugin" and ":" in bare:
  289. # The skills index lists plugin skills under a "plugin" heading, and models write that
  290. # heading as a prefix ("plugin:agent-plugin-blender-5a80e4ba:blender"). A bare skill name
  291. # never holds a colon, so the remainder is the real qualified name.
  292. name = bare
  293. namespace, bare = parse_qualified_name(name)
  294. if not is_valid_namespace(namespace):
  295. return _fail(f"Invalid namespace '{namespace}' in '{name}'. Namespaces must match [a-zA-Z0-9_-]+."), None
  296. discover_plugins() # idempotent
  297. pm = get_plugin_manager()
  298. if legacy := _legacy_portable_skill_name(pm, namespace, bare):
  299. name = legacy
  300. namespace = legacy.partition(":")[0]
  301. active_memory_provider = None
  302. try:
  303. from plugins.memory import _get_active_memory_provider, _prune_inactive_memory_provider_skills
  304. active_memory_provider = _get_active_memory_provider()
  305. _prune_inactive_memory_provider_skills(active_memory_provider)
  306. except Exception as exc:
  307. logger.debug("Failed pruning inactive memory-provider skills: %s", exc)
  308. plugin_skill_md = pm.find_plugin_skill(name)
  309. # Memory providers load through plugins.memory, not the general PluginManager: load the
  310. # namespaced provider once so its collector can forward its skills into the registry.
  311. if plugin_skill_md is None and namespace == active_memory_provider:
  312. try:
  313. from plugins.memory import load_memory_provider
  314. load_memory_provider(namespace)
  315. plugin_skill_md = pm.find_plugin_skill(name)
  316. except Exception as exc:
  317. logger.debug("Failed lazy memory-provider skill load for %s: %s", namespace, exc)
  318. if plugin_skill_md is not None and not plugin_skill_md.exists():
  319. pm.remove_plugin_skill(name) # stale registry entry — file deleted out of band
  320. return _fail(
  321. f"Skill '{name}' file no longer exists at {plugin_skill_md}. The registry entry "
  322. f"has been cleaned up — try again after the plugin is reloaded."), None
  323. if plugin_skill_md is not None:
  324. return _serve_plugin_skill(
  325. plugin_skill_md, namespace, bare, file_path=file_path, preprocess=preprocess, session_id=task_id), None
  326. if available := pm.list_plugin_skills(namespace): # plugin exists but this specific skill is missing
  327. return _fail(
  328. f"Skill '{bare}' not found in plugin '{namespace}'.",
  329. available_skills=[f"{namespace}:{s}" for s in available],
  330. hint=f"The '{namespace}' plugin provides {len(available)} skill(s)."), None
  331. return None, (f"{namespace}/{bare}" if bare else None) # plugin not found → local scan
  332. def _under_any(path: Path, dirs) -> bool:
  333. """True when ``path`` (resolved where possible) lives under one of ``dirs``."""
  334. resolved = path
  335. with suppress(Exception):
  336. resolved = path.resolve()
  337. return any(resolved.is_relative_to(d) for d in dirs)
  338. def _is_package_owned_markdown(path: Path, search_root: Path) -> bool:
  339. """True when a legacy Markdown candidate belongs to an ancestor directory skill."""
  340. try:
  341. relative = path.relative_to(search_root)
  342. except ValueError:
  343. return False
  344. return any(
  345. (search_root.joinpath(*relative.parts[:depth]) / "SKILL.md").is_file()
  346. for depth in range(1, len(relative.parts))
  347. )
  348. def _collect_skill_candidates(name, local_category_name, all_dirs):
  349. """ALL (skill_dir, skill_md) candidates across every dir and lookup strategy (direct path,
  350. recursive by dir / frontmatter name, legacy flat <name>.md), deduped by resolved path.
  351. Every copy is returned so the caller resolves them via ``agent.skill_utils.pick_skill_candidate``
  352. (cross-tier precedence; a same-tier tie of different skills is refused, never guessed)."""
  353. from agent.skill_utils import iter_skill_index_files
  354. candidates: list[tuple[Optional[Path], Path]] = []
  355. seen_md: set = set()
  356. def _record(sd: Optional[Path], smd: Path) -> None:
  357. key = smd
  358. with suppress(Exception):
  359. key = smd.resolve()
  360. if key not in seen_md:
  361. seen_md.add(key)
  362. candidates.append((sd, smd))
  363. def _record_direct(direct_path: Path, search_root: Path) -> None: # "mlops/axolotl" / "axolotl" or its flat .md sibling
  364. flat = direct_path.with_suffix(".md")
  365. if not _is_skill_support_path(direct_path) and direct_path.is_dir() and (direct_path / "SKILL.md").exists():
  366. _record(direct_path, direct_path / "SKILL.md")
  367. elif (flat.exists() and not _is_skill_support_path(flat)
  368. and not _is_package_owned_markdown(flat, search_root)):
  369. _record(None, flat)
  370. for search_dir in all_dirs:
  371. for direct in filter(None, (name, local_category_name)): # "p:x" with no plugin p → "p/x"
  372. _record_direct(search_dir / direct, search_dir)
  373. # Recursive by directory name plus frontmatter `name:` — skills_list()
  374. # exposes the frontmatter name, so skill_view(name) must accept it too.
  375. for found_skill_md in iter_skill_index_files(search_dir, "SKILL.md"):
  376. if (found_skill_md.parent.name == name
  377. or _safe_frontmatter(found_skill_md).get("name") == name):
  378. _record(found_skill_md.parent, found_skill_md)
  379. # Legacy flat <name>.md anywhere under the dir. Markdown owned by an ancestor
  380. # directory skill loads through file_path and must not shadow a real skill.
  381. for found_md in search_dir.rglob(f"{name}.md"):
  382. if (found_md.name != "SKILL.md" and not _is_skill_support_path(found_md)
  383. and not _is_package_owned_markdown(found_md, search_dir)):
  384. _record(None, found_md)
  385. return candidates
  386. # (support dir, globs, recursive, files only) — order is the linked_files key order.
  387. _LINKED_FILE_SPECS = (
  388. ("references", ["*.md"], False, False),
  389. ("templates", ["*.md", "*.py", "*.yaml", "*.yml", "*.json", "*.tex", "*.sh"], True, False),
  390. ("assets", ["*"], True, True),
  391. ("scripts", ["*.py", "*.sh", "*.bash", "*.js", "*.ts", "*.rb"], False, False))
  392. def _skill_linked_files(skill_dir: Optional[Path]) -> dict:
  393. """references/templates/assets/scripts of a directory skill (empty groups dropped)."""
  394. files: dict = {}
  395. for sub, globs, recursive, files_only in _LINKED_FILE_SPECS if skill_dir else ():
  396. base = skill_dir / sub
  397. found = [
  398. f.relative_to(skill_dir).as_posix() for g in globs if base.exists()
  399. for f in (base.rglob(g) if recursive else base.glob(g))
  400. if not files_only or f.is_file()]
  401. if found:
  402. files[sub] = found
  403. return files
  404. def _skill_readiness(frontmatter: dict[str, Any], skill_name: str) -> tuple[dict, dict]:
  405. """Resolve required env vars / credential files (prompting for secrets where the surface
  406. allows) and register what's available for sandboxes. Returns ``(fields, extras)``: fields go
  407. before the readiness extras in the skill_view result — key order is tool output."""
  408. required_env_vars = _get_required_environment_variables(frontmatter)
  409. from tools.terminal_scope import terminal_env
  410. backend = str(terminal_env("TERMINAL_ENV", "local")).strip().lower() or "local"
  411. env_snapshot = load_env()
  412. missing_required_env_vars = [
  413. e for e in required_env_vars
  414. if not e.get("optional") and not _is_env_var_persisted(e["name"], env_snapshot)]
  415. capture_result = _capture_required_environment_variables(skill_name, missing_required_env_vars)
  416. if missing_required_env_vars: # re-read: a successful capture persisted into .env
  417. env_snapshot = load_env()
  418. still_missing = set(capture_result["missing_names"])
  419. remaining = [
  420. e["name"] for e in required_env_vars if not e.get("optional")
  421. and (e["name"] in still_missing or not _is_env_var_persisted(e["name"], env_snapshot))]
  422. setup_needed = bool(remaining)
  423. # Only vars actually set pass through to sandboxed execution (execute_code, terminal).
  424. if available_env_names := [e["name"] for e in required_env_vars if e["name"] not in remaining]:
  425. try:
  426. from tools.env_passthrough import register_env_passthrough
  427. register_env_passthrough(available_env_names)
  428. except Exception:
  429. logger.debug("Could not register env passthrough for skill %s", skill_name, exc_info=True)
  430. # Credential files for remote sandboxes: existing host files are registered,
  431. # missing ones flag setup_needed.
  432. required_cred_files_raw = frontmatter.get("required_credential_files", [])
  433. missing_cred_files: list = []
  434. if isinstance(required_cred_files_raw, list) and required_cred_files_raw:
  435. try:
  436. from tools.credential_files import register_credential_files
  437. missing_cred_files = register_credential_files(required_cred_files_raw)
  438. setup_needed = setup_needed or bool(missing_cred_files)
  439. except Exception:
  440. logger.debug("Could not register credential files for skill %s", skill_name, exc_info=True)
  441. status = SkillReadinessStatus.SETUP_NEEDED if setup_needed else SkillReadinessStatus.AVAILABLE
  442. fields = {
  443. "required_environment_variables": required_env_vars, "required_commands": [],
  444. "missing_required_environment_variables": remaining,
  445. "missing_credential_files": missing_cred_files, "missing_required_commands": [],
  446. "setup_needed": setup_needed, "setup_skipped": capture_result["setup_skipped"],
  447. "readiness_status": status.value}
  448. extras: dict = {}
  449. if setup_help := next((e["help"] for e in required_env_vars if e.get("help")), None):
  450. extras["setup_help"] = setup_help
  451. if capture_result["gateway_setup_hint"]:
  452. extras["gateway_setup_hint"] = capture_result["gateway_setup_hint"]
  453. missing_items = [f"env ${n}" for n in remaining] + [f"file {p}" for p in missing_cred_files]
  454. if setup_needed and (setup_note := _build_setup_note(status, missing_items, setup_help)):
  455. if _is_remote_env_backend(backend):
  456. setup_note = f"{setup_note} {backend.upper()}-backed skills need these requirements available inside the remote environment as well."
  457. extras["setup_note"] = setup_note
  458. return fields, extras
  459. def _owning_search_dir(skill_md: Path, all_dirs) -> Optional[Path]:
  460. """Most specific search dir containing *skill_md*, compared lexically: a symlinked entry
  461. belongs to the root that exposes it, not to the root its target lives in."""
  462. owners = [Path(d) for d in all_dirs if skill_md.is_relative_to(d)]
  463. return max(owners, key=lambda d: len(d.parts), default=None)
  464. def locate_skill(name: str, local_category_name: Optional[str], roots):
  465. """Unique on-disk skill for *name* over ``(tier, dir)`` *roots*: cross-tier precedence
  466. (project > local > create_dir > external, shadowed copies logged), same-tier collision refusal,
  467. same-root identical-copy ranking, quarantine gate, not-found listing. ``(error_json, skill_dir,
  468. skill_md)``; skill_md set iff no error."""
  469. from agent.skill_utils import AMBIGUOUS_SKILL_PREFIX, TIER_PROJECT, pick_skill_candidate, skill_candidate_rank
  470. all_dirs = [d for _t, d in roots]
  471. if not all_dirs:
  472. return _fail(
  473. "Skills directory does not exist yet. It will be created on first install."), None, None
  474. candidates = _collect_skill_candidates(name, local_category_name, all_dirs)
  475. tier_of = {d: t for t, d in roots}
  476. if len(candidates) > 1:
  477. owned = [(c, _owning_search_dir(c[1], all_dirs)) for c in candidates]
  478. won, contenders = pick_skill_candidate([
  479. (tier_of[root], str(root), skill_candidate_rank(c[1], root), c[1]) for c, root in owned])
  480. if won is not None:
  481. if dropped := [str(smd) for i, (_sd, smd) in enumerate(candidates) if i != won]:
  482. logger.info("Skill '%s' resolved to %s by precedence (project > local > create_dir > "
  483. "external_dirs, then identical same-root copies); not loaded: %s",
  484. name, candidates[won][1], "; ".join(dropped))
  485. candidates = [candidates[won]]
  486. else:
  487. candidates = [candidates[i] for i in contenders]
  488. if len(candidates) > 1:
  489. paths = [str(smd) for _, smd in candidates]
  490. # A root-level copy's path IS the bare name, so it can't disambiguate itself.
  491. load_names = sorted({_owned_relative(sd, smd, all_dirs) for sd, smd in candidates} - {name})
  492. logger.warning("Skill name collision for '%s': %d candidates — %s", name, len(candidates), "; ".join(paths))
  493. return _fail(
  494. f"{AMBIGUOUS_SKILL_PREFIX}'{name}': "
  495. + (f"use one of {', '.join(load_names)}. " if load_names else "")
  496. + f"{len(candidates)} different skills share this name in the same skills directory tier; "
  497. "refusing to guess.",
  498. matches=paths, load_names=load_names,
  499. hint="Pass the exact relative path instead of the bare name, or rename one of the "
  500. "colliding skills so each name is unique."), None, None
  501. skill_dir, skill_md = candidates[0] if candidates else (None, None)
  502. # Quarantine gate: a project-tier skill with a dangerous scan verdict must not
  503. # load even by explicit name (same chokepoint the index and skills_list use).
  504. if skill_md is not None and tier_of.get(_owning_search_dir(skill_md, all_dirs)) == TIER_PROJECT:
  505. from agent.skill_utils import is_quarantined_project_skill
  506. if is_quarantined_project_skill(skill_md):
  507. return _fail(
  508. f"Project skill '{name}' is quarantined: the security scan flagged its content as "
  509. "dangerous. It will not load until the repo's skill content changes and passes a re-scan.",
  510. hint="Inspect the skill in the repo checkout, or untrust the repo with "
  511. "`hermes skills untrust`."), None, None
  512. if not skill_md or not skill_md.exists():
  513. available = [s["name"] for s in sort_skills(find_all_skills())[:20]]
  514. return _fail(f"Skill '{name}' not found.", available_skills=available,
  515. hint="Use skills_list to see all available skills"), None, None
  516. return None, skill_dir, skill_md
  517. def _owned_relative(skill_dir: Optional[Path], skill_md: Path, all_dirs) -> str:
  518. """Exact load path of a candidate: its skill dir (or flat ``.md`` stem) relative to its root."""
  519. root = _owning_search_dir(skill_md, all_dirs)
  520. target = skill_dir if skill_dir is not None else skill_md.with_suffix("")
  521. return target.relative_to(root).as_posix() if root is not None else str(target)
  522. def _log_security_warnings(name: str, skill_md: Path, content: str, all_dirs, active_skills_dir):
  523. """Warn (never block) when loaded from outside the trusted dirs (project + local + external)
  524. and/or when common prompt-injection patterns appear. The check is on the RESOLVED path:
  525. every candidate is built as ``<search_dir>/...`` so a lexical test can never fire, and a
  526. SKILL.md symlinked to a file outside every root is exactly what this guards against."""
  527. trusted_dirs = [active_skills_dir.resolve()]
  528. with suppress(Exception):
  529. trusted_dirs.extend(d.resolve() for d in all_dirs)
  530. warnings = []
  531. if not _under_any(skill_md, trusted_dirs):
  532. warnings.append(f"skill file is outside the trusted skills directory (~/.hermes/skills/): {skill_md}")
  533. if any(p in content.lower() for p in _INJECTION_PATTERNS):
  534. warnings.append("skill content contains patterns that may indicate prompt injection")
  535. if warnings:
  536. logger.warning("Skill security warning for '%s': %s", name, "; ".join(warnings))
  537. def skill_view(
  538. name: str, file_path: str | None = None, task_id: str | None = None, preprocess: bool = True) -> str:
  539. """View a skill (SKILL.md) or a file within its directory, as JSON. ``name`` is a skill name
  540. or path ("axolotl", "03-fine-tuning/axolotl"); "<plugin>:<skill>" resolves plugin-provided
  541. skills. ``preprocess`` applies the configured SKILL.md template / inline shell rendering;
  542. slash/preload callers render the message themselves."""
  543. try:
  544. # Validate before the ':' dispatch so a Windows drive path (C:\skills\foo) can't be
  545. # reinterpreted as a plugin namespace.
  546. if lookup_error := skill_lookup_path_error(name):
  547. return _fail(lookup_error, hint=_LOOKUP_HINT)
  548. local_category_name: str | None = None
  549. if ":" in name: # plugin registry; bare names use the flat-tree scan below
  550. served, local_category_name = _resolve_plugin_skill(name, file_path, task_id, preprocess)
  551. if served is not None:
  552. return served
  553. # The fall-through form (namespace/bare) joins onto each search dir too; re-validate it
  554. # since `bare` is not namespace-checked.
  555. if local_category_name and (lookup_error := skill_lookup_path_error(local_category_name)):
  556. return _fail(lookup_error, hint=_LOOKUP_HINT)
  557. roots, active_skills_dir = skill_search_dirs()
  558. all_dirs = [d for _t, d in roots]
  559. error, skill_dir, skill_md = locate_skill(name, local_category_name, roots)
  560. if error is not None:
  561. return error
  562. try: # read once — reused for platform check and main content
  563. content = _read_skill_text(skill_md)
  564. except Exception as e:
  565. return _fail(f"Failed to read skill '{name}': {e}")
  566. _log_security_warnings(name, skill_md, content, all_dirs, active_skills_dir)
  567. frontmatter = _safe_frontmatter(content=content)
  568. if not skill_matches_platform(frontmatter):
  569. return _fail(f"Skill '{name}' is not supported on this platform.", readiness_status=SkillReadinessStatus.UNSUPPORTED.value)
  570. resolved_name = frontmatter.get("name", skill_md.parent.name)
  571. # Disabled by declared name, or by the exact path that IS this copy's load name (a same-tier
  572. # duplicate's row) — whatever alias reached it; an unrelated copy at that path elsewhere is not.
  573. rel = _owned_relative(skill_dir, skill_md, all_dirs)
  574. if _is_skill_disabled(resolved_name, rel) and (_is_skill_disabled(resolved_name) or any(
  575. e["path"] == skill_md and e["load_name"] == rel for e in _skill_catalog(skip_disabled=True, include_hidden=True))):
  576. return _fail(f"Skill '{resolved_name}' is disabled. Enable it with `hermes skills` or inspect the files directly on disk.")
  577. if file_path and skill_dir:
  578. return _serve_skill_file(
  579. skill_dir, file_path, name, list_available=True, mark_read=True,
  580. hint="Use a relative path within the skill directory")
  581. # tags/related_skills: metadata.hermes.* (agentskills.io) first, then top-level.
  582. metadata = frontmatter.get("metadata")
  583. hermes_meta = (metadata.get("hermes", {}) or {}) if isinstance(metadata, dict) else {}
  584. tags, related_skills = (
  585. _parse_tags(hermes_meta.get(k) or frontmatter.get(k, "")) for k in ("tags", "related_skills"))
  586. linked_files = _skill_linked_files(skill_dir)
  587. try:
  588. rel_path = str(skill_md.relative_to(active_skills_dir))
  589. except ValueError: # external skill — relative to its own parent dir
  590. rel_path = str(skill_md.relative_to(skill_md.parent.parent)) if skill_md.parent.parent else skill_md.name
  591. skill_name = frontmatter.get("name", skill_md.stem if not skill_dir else skill_dir.name)
  592. readiness, readiness_extras = _skill_readiness(frontmatter, skill_name)
  593. rendered_content = content if not preprocess else _preprocess_skill(
  594. content, skill_dir, task_id, "Could not preprocess skill content for %s", skill_name)
  595. # ── pm tool deps (`deps: [ffmpeg]` frontmatter) ──────────────
  596. # Loading the skill IS the activation moment: ensure each declared
  597. # pm package now so the skill's commands work when the model runs
  598. # them. Failure never blocks the skill content — the note carries
  599. # the remedy.
  600. deps_note = None
  601. declared_deps = frontmatter.get("deps") or []
  602. if isinstance(declared_deps, str):
  603. declared_deps = [declared_deps]
  604. if isinstance(declared_deps, list) and declared_deps:
  605. failed_deps = []
  606. for dep in [str(d).strip() for d in declared_deps if str(d).strip()]:
  607. try:
  608. import pm
  609. pm.ensure(dep)
  610. except Exception as exc:
  611. failed_deps.append(f"{dep}: {exc}")
  612. if failed_deps:
  613. deps_note = (
  614. "Tool dependencies could not be installed — "
  615. + "; ".join(failed_deps)
  616. + ". Run `hermes pm install "
  617. + " ".join(str(d) for d in declared_deps)
  618. + "` and reload."
  619. )
  620. result = {
  621. "success": True, "name": skill_name, "description": frontmatter.get("description", ""),
  622. "tags": tags, "related_skills": related_skills, "content": rendered_content,
  623. "path": rel_path, "skill_dir": str(skill_dir) if skill_dir else None,
  624. "linked_files": linked_files if linked_files else None,
  625. "usage_hint": "To view linked files, call skill_view(name, file_path) where file_path is e.g. 'references/api.md' or 'assets/config.yaml'" if linked_files else None,
  626. **readiness,
  627. **readiness_extras}
  628. if deps_note:
  629. result["deps_note"] = deps_note
  630. _mark_background_review_read(skill_md)
  631. if frontmatter.get("compatibility"): # agentskills.io optional fields
  632. result["compatibility"] = frontmatter["compatibility"]
  633. if isinstance(metadata, dict):
  634. result["metadata"] = metadata
  635. return _json(result)
  636. except Exception as e:
  637. return tool_error(str(e), success=False)
  638. SKILLS_LIST_SCHEMA = {
  639. "name": "skills_list",
  640. "description": "List available skills (name + description). Use skill_view(name) to load full content.",
  641. "parameters": {
  642. "type": "object",
  643. "properties": {
  644. "category": {
  645. "type": "string",
  646. "description": "Optional category filter to narrow results",
  647. }
  648. },
  649. "required": [],
  650. },
  651. }
  652. SKILL_VIEW_SCHEMA = {
  653. "name": "skill_view",
  654. "description": "Load a skill's SKILL.md, or one of its linked references, templates or scripts. The first call returns SKILL.md plus a 'linked_files' dict; call again with file_path to read one.",
  655. "parameters": {
  656. "type": "object",
  657. "properties": {
  658. "name": {
  659. "type": "string",
  660. "description": "The skill name (use skills_list to see available skills). For plugin-provided skills, use the qualified form 'plugin:skill'.",
  661. },
  662. "file_path": {
  663. "type": "string",
  664. "description": "OPTIONAL: Path to a linked file within the skill (e.g., 'references/api.md', 'templates/config.yaml', 'scripts/validate.py'). Omit to get the main SKILL.md content.",
  665. },
  666. },
  667. "required": ["name"],
  668. },
  669. }
  670. registry.register(
  671. name="skills_list", toolset="skills", schema=SKILLS_LIST_SCHEMA,
  672. handler=lambda args, **kw: skills_list(category=args.get("category"), task_id=kw.get("task_id")),
  673. check_fn=check_skills_requirements, emoji="📚")
  674. def _skill_view_with_bump(args, **kw):
  675. """Invoke skill_view, then bump view_count/use on success (best-effort). Repeat-view dedup
  676. mirrors read_file's unchanged-stub: a result byte-identical to one already served for the
  677. same skill file in this session returns a short stub (cache cleared on context compression)."""
  678. name = args.get("name", "")
  679. task_id = kw.get("task_id")
  680. # The background-review fork shares the parent's task_id (prefix-cache parity). A stub there
  681. # (a) skips the read-mark its read-before-write guard requires and (b) lets it patch from a
  682. # possibly-pruned transcript copy (#95976). No dedup in the fork; None also keeps its views
  683. # out of the parent's bucket.
  684. dedup_task_id = None if is_background_review() else task_id
  685. result = skill_view(name, file_path=args.get("file_path"), task_id=task_id)
  686. with suppress(Exception):
  687. parsed = json.loads(result)
  688. if isinstance(parsed, dict) and parsed.get("success"):
  689. if (stub := dedup_skill_view(dedup_task_id, name, args.get("file_path"), parsed, result)) is not None:
  690. return stub
  691. if resolved := parsed.get("name") or name: # qualified forms return the canonical name
  692. from tools.skill_usage import bump_use, bump_view
  693. bump_view(str(resolved))
  694. # Viewing is actively loading the skill to act on it — that counts as use
  695. # (the curator's stale timer keys off last_used_at).
  696. bump_use(str(resolved), task_id=kw.get("task_id"), session_id=kw.get("session_id"))
  697. return result
  698. registry.register(
  699. name="skill_view", toolset="skills", schema=SKILL_VIEW_SCHEMA, handler=_skill_view_with_bump,
  700. check_fn=check_skills_requirements, emoji="📚")