skill_manager_tool.py 47 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943
  1. #!/usr/bin/env python3
  2. """Skill Manager Tool — agent-managed skill creation & editing.
  3. Skills are the agent's procedural memory (narrow "how to do X"; MEMORY.md/USER.md are
  4. broad, declarative). New skills land in ~/.hermes/skills/ (or ``skills.create_dir``);
  5. existing skills (bundled, hub, user) are modified in place. Layout:
  6. ``<skills>/[category/]<skill>/SKILL.md`` + optional ``references/ templates/ scripts/ assets/``.
  7. """
  8. import contextvars as _ctxvars
  9. import hashlib
  10. import json
  11. from contextlib import ExitStack, suppress
  12. import logging
  13. import re
  14. import shutil
  15. from pathlib import Path
  16. from typing import Any, Dict, List, Optional, Tuple
  17. import hermes_yaml as yaml
  18. from hermes_constants import get_hermes_home
  19. from utils import atomic_write_text, is_truthy_value
  20. from hermes_cli.config import cfg_get
  21. from agent.skill_utils import (
  22. extract_skill_description,
  23. is_skill_description_truncated_for_prompt,
  24. parse_frontmatter as _parse_frontmatter,
  25. SKILL_PROMPT_DESC_LIMIT)
  26. from tools.skill_manager_guards import (
  27. _background_review_delete_guard, _background_review_preflight, _background_review_read_before_write_guard,
  28. _containing_skills_root, _curator_consolidation_delete_guard, _is_path_redirect, _pinned_guard,
  29. _validate_delete_target, _is_background_review, _refusal as _err)
  30. from tools.skill_manager_batch import (
  31. _PATCH_EITHER_OR, _PATCH_NEEDS_NEW_STRING, _PATCH_NEEDS_OLD_STRING, _op_shape_error, _skill_manage_batch)
  32. from tools.skills_guard import scan_skill, should_allow_install, format_scan_report
  33. logger = logging.getLogger(__name__)
  34. def _guard_agent_created_enabled() -> bool:
  35. """skills.guard_agent_created (default False): opt-in — terminal() runs the same code ungated."""
  36. try:
  37. from hermes_cli.config import load_config
  38. return is_truthy_value(cfg_get(load_config(), "skills", "guard_agent_created"), default=False)
  39. except Exception:
  40. return False
  41. def _security_scan_skill(skill_dir: Path) -> Optional[str]:
  42. """Post-write scan (opt-in); error string if blocked, else None. An "ask" verdict
  43. (dangerous findings) is surfaced as an error so the agent can retry without them."""
  44. if not _guard_agent_created_enabled():
  45. return None
  46. try:
  47. result = scan_skill(skill_dir, source="agent-created")
  48. allowed, reason = should_allow_install(result)
  49. if allowed is None:
  50. logger.warning("Agent-created skill blocked (dangerous findings): %s", reason)
  51. if allowed is not True:
  52. return f"Security scan blocked this skill ({reason}):\n{format_scan_report(result)}"
  53. except Exception as e:
  54. logger.warning("Security scan failed for %s: %s", skill_dir, e, exc_info=True)
  55. return None
  56. # All skills live in ~/.hermes/skills/ (single source of truth)
  57. HERMES_HOME = get_hermes_home()
  58. SKILLS_DIR = HERMES_HOME / "skills"
  59. _SKILLS_DIR_AT_IMPORT = SKILLS_DIR
  60. def _skills_dir() -> Path:
  61. """Active profile's skills dir at call time (multi-profile runtimes rebind per session).
  62. An explicitly patched module-level ``SKILLS_DIR`` (tests) wins over the live HERMES_HOME.
  63. Long-lived multi-profile runtimes (Dashboard/TUI/Desktop backend, cron, kanban workers) import this
  64. module once under the launch HERMES_HOME and later bind a different profile per session (#40677).
  65. """
  66. configured = Path(SKILLS_DIR)
  67. return configured if configured != _SKILLS_DIR_AT_IMPORT else get_hermes_home() / "skills"
  68. def _skill_lock_path(name: str) -> Path:
  69. """Per-skill lock file under ``<skills>/.locks/`` (same idiom as the usage ledger's
  70. ``.usage.json.lock``), never inside the skill dir so delete/recreate cannot unlink it under a
  71. waiting writer. Keyed by a digest of the basename so ``foo`` and ``category/foo`` share one
  72. lock and no name can hit a filesystem limit (callers validate the basename first)."""
  73. digest = hashlib.sha256(Path(name).name.encode("utf-8", "surrogatepass")).hexdigest()
  74. return _skills_dir() / ".locks" / f"{digest}.lock"
  75. def _skill_mutation_lock(name: str):
  76. """Exclusive lock held across one skill's whole read-modify-write; thread-re-entrant."""
  77. from tools.skill_usage import skill_file_lock
  78. return skill_file_lock(_skill_lock_path(name))
  79. def _skill_mutation_locks(names):
  80. """Every lock of an atomic batch, acquired in one stable path order (deadlock-free across batches)."""
  81. from tools.skill_usage import skill_file_lock
  82. stack = ExitStack()
  83. for lock_path in sorted({_skill_lock_path(n) for n in names}):
  84. stack.enter_context(skill_file_lock(lock_path))
  85. return stack
  86. MAX_NAME_LENGTH = 64
  87. MAX_DESCRIPTION_LENGTH = 1024
  88. MAX_SKILL_CONTENT_CHARS = 100_000 # ~36k tokens at 2.75 chars/token
  89. MAX_SKILL_FILE_BYTES = 1_048_576 # 1 MiB per supporting file
  90. VALID_NAME_RE = re.compile(r'^[a-z0-9][a-z0-9._-]*$') # filesystem-safe, URL-friendly
  91. ALLOWED_SUBDIRS = {"references", "templates", "scripts", "assets"} # for write_file/remove_file
  92. _FRONTMATTER_END_RE = re.compile(r'\n---\s*\n')
  93. _NAME_RULE = "Use lowercase letters, numbers, hyphens, dots, and underscores."
  94. # --- Validation helpers -------------------------------------------------------
  95. def _check_identifier(value: str, label: str, invalid: str) -> Optional[str]:
  96. if len(value) > MAX_NAME_LENGTH:
  97. return f"{label} exceeds {MAX_NAME_LENGTH} characters."
  98. return None if VALID_NAME_RE.match(value) else invalid
  99. def _validate_name(name: str) -> Optional[str]:
  100. if not name:
  101. return "Skill name is required."
  102. return _check_identifier(
  103. name, "Skill name", f"Invalid skill name '{name}'. {_NAME_RULE} Must start with a letter or digit.")
  104. def _validate_category(category: Optional[str]) -> Optional[str]:
  105. if category is None or (isinstance(category, str) and not category.strip()):
  106. return None
  107. if not isinstance(category, str):
  108. return "Category must be a string."
  109. category = category.strip()
  110. invalid = (f"Invalid category '{category}'. {_NAME_RULE} "
  111. "Categories must be a single directory name.")
  112. if "/" in category or "\\" in category:
  113. return invalid
  114. return _check_identifier(category, "Category", invalid)
  115. def _validate_frontmatter(content: str) -> Optional[str]:
  116. """Validate frontmatter (name + description) and a non-empty body."""
  117. if not content.strip():
  118. return "Content cannot be empty."
  119. content = content.lstrip("\ufeff") # tolerate a Windows UTF-8 BOM
  120. if not content.startswith("---"):
  121. return "SKILL.md must start with YAML frontmatter (---). See existing skills for format."
  122. end_match = _FRONTMATTER_END_RE.search(content[3:])
  123. if not end_match:
  124. return "SKILL.md frontmatter is not closed. Ensure you have a closing '---' line."
  125. try:
  126. parsed = yaml.safe_load(content[3:end_match.start() + 3])
  127. except yaml.YAMLError as e:
  128. return f"YAML frontmatter parse error: {e}"
  129. if not isinstance(parsed, dict):
  130. return "Frontmatter must be a YAML mapping (key: value pairs)."
  131. for field in ("name", "description"):
  132. if field not in parsed:
  133. return f"Frontmatter must include '{field}' field."
  134. desc = str(parsed["description"])
  135. if len(desc) > MAX_DESCRIPTION_LENGTH:
  136. return f"Description exceeds {MAX_DESCRIPTION_LENGTH} characters."
  137. if not content[end_match.end() + 3:].strip():
  138. return "SKILL.md must have content after the frontmatter (instructions, procedures, etc.)."
  139. return None
  140. def _description_budget_error(content: str, before: Optional[str] = None) -> Optional[str]:
  141. """A description written by this call (a create, or an edit/patch that changes it from the one in
  142. ``before``) must fit SKILL_PROMPT_DESC_LIMIT, the width the skill index shows. An unchanged legacy
  143. over-limit description stays editable: a body patch must not be blocked by an old frontmatter."""
  144. desc = _description_of(content) or ""
  145. if len(desc) <= SKILL_PROMPT_DESC_LIMIT or (before is not None and desc == _description_of(before)):
  146. return None
  147. return (
  148. f"Description is {len(desc)} chars; a skill description must fit the "
  149. f"{SKILL_PROMPT_DESC_LIMIT}-char skill index (one sentence, trigger first, ends with a "
  150. f"period, without repeating the category name). The index clips anything longer. "
  151. f"Move detail into the skill body.")
  152. def _validate_content_size(content: str, label: str = "SKILL.md") -> Optional[str]:
  153. if len(content) > MAX_SKILL_CONTENT_CHARS:
  154. return (
  155. f"{label} content is {len(content):,} characters (limit: {MAX_SKILL_CONTENT_CHARS:,}). "
  156. f"Consider splitting into a smaller SKILL.md with supporting files in references/ "
  157. f"or templates/.")
  158. return None
  159. def _description_of(content: Optional[str]) -> Optional[str]:
  160. """Normalized frontmatter description of a SKILL.md text; None when absent or unparseable."""
  161. with suppress(Exception):
  162. return str(_parse_frontmatter(content or "")[0]["description"]).strip().strip("'\"")
  163. return None
  164. def _description_preview(content: str) -> str:
  165. """First 120 chars of the frontmatter description; '' on any failure."""
  166. with suppress(Exception):
  167. fm_end = _FRONTMATTER_END_RE.search(content[3:])
  168. if fm_end:
  169. return str(yaml.safe_load(content[3:fm_end.start() + 3]).get("description", ""))[:120]
  170. return ""
  171. def _resolve_skill_dir(name: str, category: str | None = None) -> Path:
  172. """New-skill dir; honors ``skills.create_dir`` (e.g. a shared fleet dir)."""
  173. base = _skills_dir()
  174. try:
  175. from agent.skill_utils import get_skill_create_dir
  176. base = get_skill_create_dir() or base
  177. except Exception:
  178. logger.debug("skills.create_dir lookup failed", exc_info=True)
  179. return base / (category or "") / name
  180. def _iter_skill_dirs(root: Path):
  181. from agent.skill_utils import is_excluded_skill_path
  182. for skill_md in root.rglob("SKILL.md"):
  183. if not is_excluded_skill_path(skill_md):
  184. yield skill_md.parent
  185. def _read_frontmatter_name(skill_md: Path) -> Optional[str]:
  186. """Read a SKILL.md's frontmatter ``name:`` — the name skills_list displays.
  187. Fail-quiet on unreadable files: the fallback lookup in ``_find_skill``
  188. must never break the directory-name match, and an unreadable SKILL.md
  189. simply has no second name to offer. The value is truncated with the
  190. same ``MAX_NAME_LENGTH`` budget skills_list applies when displaying it.
  191. """
  192. try:
  193. from agent.skill_utils import parse_frontmatter
  194. content = skill_md.read_text(encoding="utf-8-sig", errors="replace")[:4000]
  195. frontmatter, _ = parse_frontmatter(content)
  196. except OSError:
  197. logger.debug("frontmatter read failed for %s", skill_md, exc_info=True)
  198. return None
  199. name = frontmatter.get("name")
  200. if isinstance(name, str):
  201. return name[:MAX_NAME_LENGTH]
  202. return None
  203. def _find_skill(name: str) -> Optional[dict[str, Any]]:
  204. """Find a skill (local skills dir, then skills.external_dirs) -> ``{"path": Path}`` | None.
  205. Accepts the bare dir name (``axolotl``; matches category-nested skills too) and the
  206. categorized relative path (``mlops/axolotl``) — the two forms skill_view resolves. The
  207. categorized form matches RELATIVE to the local root only (relative_to raises for external dirs).
  208. As a last resort the frontmatter ``name:`` is matched too, so the name ``skills list``
  209. and the dashboard display (frontmatter name wins over the directory name there)
  210. resolves everywhere instead of failing with a misleading "not found in active
  211. profile" error when the two names diverge. Directory-name matches keep priority —
  212. a frontmatter match is only considered after the whole scan found no
  213. directory/categorized match, so one skill's frontmatter cannot shadow another
  214. skill's directory. A display name held by two or more distinct skills resolves to
  215. nothing: like skill_view's same-tier collision refusal, refusing to guess beats
  216. silently mutating the wrong skill; the directory name still resolves."""
  217. from agent.skill_utils import get_all_skills_dirs
  218. local_root = None
  219. if "/" in name or "\\" in name:
  220. try:
  221. local_root = _skills_dir().resolve()
  222. except OSError:
  223. logger.debug(
  224. "skills dir resolve failed; categorized lookups fall back to the unresolved path",
  225. exc_info=True)
  226. local_root = _skills_dir()
  227. display_matches: list[Path] = []
  228. seen_display: set = set()
  229. for skills_dir in get_all_skills_dirs():
  230. if not skills_dir.exists():
  231. continue
  232. for skill_dir in _iter_skill_dirs(skills_dir):
  233. if skill_dir.name == name:
  234. return {"path": skill_dir}
  235. if local_root is not None:
  236. resolved = skill_dir.resolve()
  237. if (resolved.is_relative_to(local_root)
  238. and resolved.relative_to(local_root).as_posix() == name): # POSIX form
  239. return {"path": skill_dir}
  240. if _read_frontmatter_name(skill_dir / "SKILL.md") == name:
  241. key = skill_dir / "SKILL.md"
  242. with suppress(Exception):
  243. key = key.resolve()
  244. if key not in seen_display:
  245. seen_display.add(key)
  246. display_matches.append(skill_dir)
  247. if len(display_matches) == 1:
  248. return {"path": display_matches[0]}
  249. if display_matches:
  250. logger.warning(
  251. "Skill display name '%s' is ambiguous (%d skills claim it: %s) — refusing to guess; "
  252. "resolve it by directory name instead",
  253. name, len(display_matches), "; ".join(str(p) for p in display_matches))
  254. return None
  255. def _find_skill_in_other_profiles(name: str) -> list[tuple[str, Path]]:
  256. """``(profile, skill_dir)`` pairs for OTHER profiles holding ``name`` (so the not-found
  257. error can explain a wrong-profile mistake). Fail-quiet."""
  258. matches: list[tuple[str, Path]] = []
  259. try:
  260. from hermes_constants import get_default_hermes_root
  261. root = get_default_hermes_root()
  262. except Exception:
  263. return matches
  264. _active = _skills_dir()
  265. active_dir = _active.resolve() if _active.exists() else _active
  266. # Every profile's skills dir EXCEPT the active one (already searched). A candidate whose
  267. # path cannot be resolved is skipped (not a fatal error); is_dir() checks stay unguarded.
  268. candidates: list[tuple[str, Path]] = []
  269. with suppress(OSError, RuntimeError):
  270. if (root / "skills").resolve() != active_dir:
  271. candidates.append(("default", root / "skills"))
  272. if (root / "profiles").is_dir():
  273. with suppress(OSError):
  274. for entry in (root / "profiles").iterdir():
  275. if not entry.is_dir():
  276. continue
  277. try:
  278. if (entry / "skills").resolve() == active_dir:
  279. continue
  280. except (OSError, RuntimeError):
  281. continue
  282. candidates.append((entry.name, entry / "skills"))
  283. for profile_name, skills_dir in candidates:
  284. if not skills_dir.is_dir():
  285. continue
  286. with suppress(OSError):
  287. hit = next((d for d in _iter_skill_dirs(skills_dir) if d.name == name), None)
  288. if hit is not None:
  289. matches.append((profile_name, hit)) # one match per profile is enough
  290. return matches
  291. def _skill_not_found_error(name: str, suffix: str = "") -> str:
  292. """Not-found error naming other profiles that hold the skill, plus ``suffix``."""
  293. from agent.file_safety import _resolve_active_profile_name
  294. base = f"Skill '{name}' not found in active profile '{_resolve_active_profile_name()}'."
  295. others = _find_skill_in_other_profiles(name)
  296. if len(others) == 1:
  297. other_profile, other_path = others[0]
  298. base += (
  299. f" A skill by that name exists in profile '{other_profile}' ({other_path}). To edit "
  300. f"it, switch profiles (`hermes -p {other_profile}`) or edit the file directly "
  301. f"(file tools / terminal).")
  302. elif others:
  303. names = ", ".join(f"'{p}'" for p, _ in others)
  304. base += (
  305. f" Skills by that name exist in other profiles: {names}. Switch profiles (`hermes -p "
  306. f"<name>`) to edit there, or edit the files directly (file tools / terminal).")
  307. else:
  308. base += " Use skills_list() to see available skills."
  309. return base + suffix
  310. def _validate_file_path(file_path: str) -> Optional[str]:
  311. """Validate a write_file/remove_file path: under an allowed subdir, no escape."""
  312. from tools.path_security import has_traversal_component
  313. if not file_path:
  314. return "file_path is required."
  315. parts = Path(file_path).parts
  316. # Traversal first, so the SKILL.md exception is unreachable by a traversal-laden path.
  317. if has_traversal_component(file_path):
  318. return "Path traversal ('..') is not allowed."
  319. # SKILL.md lives at the skill root; accept 'SKILL.md' and '<skill>/SKILL.md'.
  320. if parts and parts[-1] == "SKILL.md" and len(parts) in (1, 2):
  321. return None
  322. if not parts or parts[0] not in ALLOWED_SUBDIRS:
  323. allowed = ", ".join(sorted(ALLOWED_SUBDIRS))
  324. return f"File must be under one of: {allowed}. Got: '{file_path}'"
  325. if len(parts) < 2:
  326. return f"Provide a file path, not just a directory. Example: '{parts[0]}/myfile.md'"
  327. return None
  328. def _resolve_supporting_file(skill_dir: Path, file_path: str):
  329. """Validate ``file_path`` and resolve it inside ``skill_dir``
  330. -> ``(target, None)`` | ``(None, error_dict)``."""
  331. from tools.path_security import validate_within_dir
  332. target = skill_dir / (file_path or "")
  333. err = _validate_file_path(file_path) or validate_within_dir(target, skill_dir)
  334. return (None, _err(err)) if err else (target, None)
  335. def _locate_for_write(name: str, action: str, not_found_suffix: str = ""):
  336. """Find the skill; a delete also runs the background-review delete guard -> ``(skill_dir, None)``
  337. | ``(None, error_dict)``."""
  338. existing = _find_skill(name)
  339. if not existing:
  340. return None, _err(_skill_not_found_error(name, not_found_suffix))
  341. skill_dir = existing["path"]
  342. guard = _background_review_delete_guard(name, skill_dir) if action == "delete" else None
  343. return (None, guard) if guard else (skill_dir, None)
  344. def _guarded_write(name: str, skill_dir: Path, target: Path, action: str, label: str,
  345. content: str) -> Optional[dict[str, Any]]:
  346. """Read-before-write guard (existing targets only), the description budget for the root SKILL.md
  347. (whichever action and file_path reach it), atomic write, then the security scan; a blocked scan
  348. restores the original (or unlinks a new file). Error dict or None."""
  349. original = None
  350. if target.exists():
  351. if read_guard := _background_review_read_before_write_guard(name, target, action, label):
  352. return read_guard
  353. original = target.read_text(encoding="utf-8-sig")
  354. if target == skill_dir / "SKILL.md" and (err := _description_budget_error(content, before=original)):
  355. return _err(err)
  356. from hermes_constants import mkdir_under_hermes_home
  357. mkdir_under_hermes_home(target.parent)
  358. atomic_write_text(target, content, preserve_mode=True, create_mode=0o644)
  359. scan_error = _security_scan_skill(skill_dir)
  360. if not scan_error:
  361. return None
  362. if original is not None:
  363. atomic_write_text(target, original, preserve_mode=True)
  364. else:
  365. target.unlink(missing_ok=True)
  366. return _err(scan_error)
  367. def _add_description_prompt_preview(result: dict[str, Any], content: str) -> dict[str, Any]:
  368. fm, _ = _parse_frontmatter(content)
  369. if is_skill_description_truncated_for_prompt(fm):
  370. result["system_prompt_preview"] = (
  371. f"System prompt will show: \"{extract_skill_description(fm)}\" — shorten the "
  372. f"description to {SKILL_PROMPT_DESC_LIMIT} chars so the index shows all of it.")
  373. return result
  374. def _attach_lint_findings(result: dict[str, Any], skill_md: Path, before: Optional[str] = None) -> None:
  375. """Attach ADVISORY authoring findings (hard rejects already ran in _validate_frontmatter).
  376. With ``before`` (the pre-write content) only rules the write INTRODUCED are attached, so a
  377. patch reports the line it crossed rather than re-listing the skill's standing findings."""
  378. try:
  379. from tools.skill_linter import lint_content, lint_skill # local import: optional path
  380. findings = lint_skill(skill_md)
  381. if before is not None:
  382. standing = {f.rule for f in lint_content(before, skill_dir=skill_md.parent)}
  383. findings = [f for f in findings if f.rule not in standing]
  384. except Exception:
  385. findings = None
  386. if not findings:
  387. return
  388. result["lint_warnings"] = [
  389. {"severity": f.severity, "rule": f.rule, "message": f.message} for f in findings]
  390. result["lint_hint"] = (
  391. "The write succeeded. These are advisory authoring-convention findings (not blockers) "
  392. "— fix them with skill_manage(action='patch') to match Hermes skill standards.")
  393. def _clip(text: str, n: int, ellipsis: str) -> str:
  394. return text[:n] + (ellipsis if len(text) > n else "")
  395. # --- Core actions -------------------------------------------------------------
  396. def _create_skill(name: str, content: str, category: str | None = None) -> dict[str, Any]:
  397. if err := (_validate_name(name) or _validate_category(category)
  398. or _validate_frontmatter(content) or _validate_content_size(content)):
  399. return _err(err)
  400. if existing := _find_skill(name):
  401. return _err(f"A skill named '{name}' already exists at {existing['path']}.")
  402. skill_dir = _resolve_skill_dir(name, category)
  403. from hermes_constants import mkdir_under_hermes_home
  404. mkdir_under_hermes_home(skill_dir.parent)
  405. try:
  406. skill_dir.mkdir(exist_ok=False)
  407. except FileExistsError:
  408. # mkdir raised EEXIST for a file, symlink (live or dangling) or dir alike; only an EMPTY
  409. # real directory (leftover of an earlier create whose SKILL.md write failed) may be used.
  410. # Anything else — or anything unstat-able/unlistable — is someone else's: never adopt.
  411. try:
  412. usable = (not _is_path_redirect(skill_dir) and skill_dir.is_dir()
  413. and not any(skill_dir.iterdir()))
  414. except OSError: # permissions / ACL
  415. usable = False
  416. if not usable:
  417. return _err(f"Cannot create skill '{name}': {skill_dir} already exists (not an empty "
  418. "directory, or unreadable). Choose another name, or move/remove that path and retry.")
  419. skill_md = skill_dir / "SKILL.md"
  420. if guard := _guarded_write(name, skill_dir, skill_md, "create", "SKILL.md", content):
  421. with suppress(OSError): # rmdir, not rmtree: only an empty dir goes, anything foreign stays
  422. skill_dir.rmdir()
  423. return guard
  424. root = _skills_dir() # display relative under the profile dir; absolute under skills.create_dir
  425. display = skill_dir.relative_to(root) if skill_dir.is_relative_to(root) else skill_dir
  426. result = {
  427. "success": True, "message": f"Skill '{name}' created.", "path": str(display),
  428. "skill_md": str(skill_md), "_change": {"description": _description_preview(content)},
  429. **({"category": category} if category else {}),
  430. "hint": "To add reference files, templates, or scripts, use "
  431. f"skill_manage(action='write_file', name='{name}', file_path='references/example.md', "
  432. "file_content='...')"}
  433. _attach_lint_findings(_add_description_prompt_preview(result, content), skill_md)
  434. return result
  435. def _edit_skill(name: str, content: str) -> dict[str, Any]:
  436. """Replace the SKILL.md of any existing skill (full rewrite)."""
  437. if err := _validate_frontmatter(content) or _validate_content_size(content):
  438. return _err(err)
  439. skill_dir, guard = _locate_for_write(name, "edit")
  440. # SKILL.md always exists here (_find_skill requires it), so a blocked scan restores it.
  441. if guard := guard or _guarded_write(name, skill_dir, skill_dir / "SKILL.md", "edit", "SKILL.md", content):
  442. return guard
  443. result = {
  444. "success": True, "message": f"Skill '{name}' updated (full rewrite).",
  445. "path": str(skill_dir), "_change": {"description": _description_preview(content)}}
  446. return _add_description_prompt_preview(result, content)
  447. def _patch_skill(name: str, old_string: str, new_string: str, file_path: str | None = None,
  448. replace_all: bool = False) -> dict[str, Any]:
  449. """Targeted find-and-replace in SKILL.md (default) or a supporting file; unique match unless replace_all."""
  450. if not old_string:
  451. return _err(_PATCH_NEEDS_OLD_STRING)
  452. if new_string is None:
  453. return _err(_PATCH_NEEDS_NEW_STRING)
  454. # No old_string == new_string guard here: fuzzy_find_and_replace rejects that with a
  455. # richer error (file_preview) this layer cannot produce.
  456. skill_dir, guard = _locate_for_write(name, "patch")
  457. if guard:
  458. return guard
  459. target_label = file_path or "SKILL.md"
  460. if file_path:
  461. target, err = _resolve_supporting_file(skill_dir, file_path)
  462. if err:
  463. return err
  464. else:
  465. target = skill_dir / "SKILL.md"
  466. if not target.exists():
  467. return _err(f"File not found: {target.relative_to(skill_dir)}")
  468. if read_guard := _background_review_read_before_write_guard(name, target, "patch", target_label):
  469. return read_guard
  470. content = target.read_text(encoding="utf-8-sig")
  471. # Use the same fuzzy matching engine as the file patch tool.
  472. from tools.fuzzy_match import fuzzy_find_and_replace
  473. correction_notes = []
  474. new_content, match_count, _strategy, match_error = fuzzy_find_and_replace(
  475. content, old_string, new_string, replace_all, correction_notes=correction_notes)
  476. if match_error:
  477. with suppress(Exception):
  478. from tools.fuzzy_match import format_no_match_hint
  479. match_error += format_no_match_hint(match_error, match_count, old_string, content)
  480. return _err(match_error) | {"file_preview": _clip(content, 500, "...")}
  481. if err := _validate_content_size(new_content, label=target_label):
  482. return _err(err)
  483. if not file_path and (err := _validate_frontmatter(new_content)):
  484. return _err(f"Patch would break SKILL.md structure: {err}")
  485. if guard := _guarded_write(name, skill_dir, target, "patch", target_label, new_content):
  486. return guard
  487. result = {
  488. "success": True,
  489. "message": f"Patched {target_label} in skill '{name}' ({match_count} replacement{'s' if match_count > 1 else ''}).",
  490. "_change": {"old": _clip(old_string, 200, "…"), "new": _clip(new_string, 200, "…")}}
  491. if correction_notes:
  492. result["note"] = "\n".join(correction_notes)
  493. # SKILL.md grows by patches, not by creates: surface findings on the patch that crosses a line
  494. # (oversized-body, incident-log-shape) — a clean patch attaches nothing and stays quiet.
  495. if not file_path:
  496. _attach_lint_findings(result, target, before=content)
  497. return result
  498. def _delete_skill(name: str, absorbed_into: Optional[str] = None) -> dict[str, Any]:
  499. """Delete a skill. ``absorbed_into``: None = undeclared (legacy, accepted); "" = explicit prune;
  500. "<skill>" = absorbed into that umbrella, which must exist (so the model can't claim one)."""
  501. skill_dir, guard = _locate_for_write(name, "delete")
  502. if guard := guard or _curator_consolidation_delete_guard(name, absorbed_into):
  503. return guard
  504. if pinned_err := _pinned_guard(name):
  505. return _err(pinned_err)
  506. absorbed_target = absorbed_into.strip() if isinstance(absorbed_into, str) else ""
  507. if absorbed_target:
  508. if absorbed_target == name:
  509. return _err(f"absorbed_into='{absorbed_target}' cannot equal the skill being deleted.")
  510. if not _find_skill(absorbed_target):
  511. return _err(f"absorbed_into='{absorbed_target}' does not exist. "
  512. f"Create or patch the umbrella skill first, then retry the delete.")
  513. skills_root = _containing_skills_root(skill_dir)
  514. if unsafe := _validate_delete_target(skill_dir): # defense-in-depth before rmtree
  515. return _err(unsafe)
  516. # Curator consolidations must be RECOVERABLE (`hermes curator restore`): archive instead
  517. # of rmtree. Foreground deletes keep hard-delete semantics.
  518. absorbed_note = f" Content absorbed into '{absorbed_target}'." if absorbed_target else ""
  519. if _is_background_review():
  520. try:
  521. from tools.skill_usage import archive_skill
  522. ok, archive_msg = archive_skill(name)
  523. except Exception as e:
  524. return _err(f"failed to archive '{name}': {e}")
  525. if not ok:
  526. return _err(archive_msg)
  527. return {"success": True,
  528. "message": f"Skill '{name}' archived ({archive_msg}).{absorbed_note}",
  529. "_archived": True}
  530. shutil.rmtree(skill_dir)
  531. _rmdir_if_empty(skill_dir.parent, skills_root) # empty category dir, never the root
  532. return {"success": True, "message": f"Skill '{name}' deleted.{absorbed_note}"}
  533. def _rmdir_if_empty(parent: Path, stop: Path) -> None:
  534. if parent != stop and parent.exists() and not any(parent.iterdir()):
  535. parent.rmdir()
  536. def _write_file(name: str, file_path: str, file_content: str) -> dict[str, Any]:
  537. """Add or overwrite a supporting file within any skill directory."""
  538. if err := _validate_file_path(file_path):
  539. return _err(err)
  540. if not file_content and file_content != "":
  541. return _err("file_content is required.")
  542. if (content_bytes := len(file_content.encode("utf-8"))) > MAX_SKILL_FILE_BYTES:
  543. return _err(f"File content is {content_bytes:,} bytes (limit: {MAX_SKILL_FILE_BYTES:,} "
  544. f"bytes / 1 MiB). Consider splitting into smaller files.")
  545. if err := _validate_content_size(file_content, label=file_path):
  546. return _err(err)
  547. skill_dir, guard = _locate_for_write(name, "write_file", " Create it first with action='create'.")
  548. if guard:
  549. return guard
  550. target, err = _resolve_supporting_file(skill_dir, file_path)
  551. if guard := err or _guarded_write(name, skill_dir, target, "write_file", file_path, file_content):
  552. return guard
  553. result = {"success": True, "message": f"File '{file_path}' written to skill '{name}'.", "path": str(target)}
  554. # references/ is where per-session hoarding shows up; surface the sprawl finding on the write
  555. # that crosses the line so the review fork sees it in the same turn.
  556. if file_path.startswith("references/") and (skill_dir / "SKILL.md").exists():
  557. _attach_lint_findings(result, skill_dir / "SKILL.md")
  558. return result
  559. def _remove_file(name: str, file_path: str) -> dict[str, Any]:
  560. """Remove a supporting file from any skill directory."""
  561. if err := _validate_file_path(file_path):
  562. return _err(err)
  563. skill_dir, guard = _locate_for_write(name, "remove_file")
  564. if guard:
  565. return guard
  566. target, err = _resolve_supporting_file(skill_dir, file_path)
  567. if err:
  568. return err
  569. if not target.exists(): # list what IS there so the model can pick the right path
  570. available = [str(f.relative_to(skill_dir)) for subdir in ALLOWED_SUBDIRS
  571. if (skill_dir / subdir).exists() for f in (skill_dir / subdir).rglob("*") if f.is_file()]
  572. return _err(f"File '{file_path}' not found in skill '{name}'.", available_files=available or None)
  573. if read_guard := _background_review_read_before_write_guard(name, target, "remove_file", file_path):
  574. return read_guard
  575. target.unlink()
  576. _rmdir_if_empty(target.parent, skill_dir)
  577. return {"success": True, "message": f"File '{file_path}' removed from skill '{name}'."}
  578. # --- Main entry point ---------------------------------------------------------
  579. # Set while replaying an approved staged skill write so skill_manage() does not re-gate it.
  580. _skill_gate_bypass: _ctxvars.ContextVar[bool] = _ctxvars.ContextVar(
  581. "skill_gate_bypass", default=False)
  582. def _run_write_gate(build_staging):
  583. """Shared write gate: None to proceed, else a JSON tool result (blocked/staged).
  584. ``build_staging(wa) -> (payload, gist)`` runs only when staging. Fails open if
  585. write_approval cannot be imported."""
  586. try:
  587. from tools import write_approval as wa
  588. except Exception:
  589. return None # fail open
  590. decision = wa.evaluate_gate(wa.SKILLS)
  591. if decision.allow:
  592. return None
  593. if decision.blocked:
  594. return tool_error(decision.message, success=False)
  595. payload, gist = build_staging(wa)
  596. record = wa.stage_write(wa.SKILLS, payload, summary=gist, origin=wa.current_origin())
  597. return json.dumps({"success": True, "staged": True, "pending_id": record["id"],
  598. "gist": gist, "message": decision.message}, ensure_ascii=False)
  599. def _apply_skill_write_gate(action, name, **payload_kwargs):
  600. """Flat-shape gate: stage the full kwargs so approval can replay them; bypassed during replay."""
  601. if action not in _ACTION_HANDLERS or _skill_gate_bypass.get():
  602. return None
  603. def _staging(wa):
  604. payload = {"action": action, "name": name,
  605. **{k: v for k, v in payload_kwargs.items() if v is not None}}
  606. gist_kw = {k: payload_kwargs.get(k) or ""
  607. for k in ("content", "file_path", "old_string", "new_string")}
  608. return payload, wa.skill_gist(action, name, **gist_kw)
  609. return _run_write_gate(_staging)
  610. _FLAT_OP_KEYS = ("content", "category", "file_path", "file_content", "old_string", "new_string",
  611. "absorbed_into", "operations")
  612. def _skill_manage_from(payload: dict[str, Any], **extra) -> str:
  613. """Call ``skill_manage`` with the flat-shape fields (and absorbed_into/operations) of ``payload``."""
  614. return skill_manage(
  615. action=payload.get("action", ""), name=payload.get("name", ""),
  616. replace_all=payload.get("replace_all", False),
  617. **{k: payload.get(k) for k in _FLAT_OP_KEYS}, **extra)
  618. def apply_skill_pending(payload: dict[str, Any]) -> str:
  619. """Replay a staged skill write, bypassing the gate (the /skills approve handler)."""
  620. token = _skill_gate_bypass.set(True)
  621. try:
  622. return _skill_manage_from(payload)
  623. finally:
  624. _skill_gate_bypass.reset(token)
  625. def _act_patch(a):
  626. """Two shapes: old_string/new_string = targeted replacement (validated in _patch_skill so the
  627. tool and the helper give the same guidance); content alone = full rewrite (the old 'edit')."""
  628. if a["content"] and (a["old_string"] or a["new_string"] is not None):
  629. return tool_error(_PATCH_EITHER_OR, success=False)
  630. if a["content"]:
  631. return _edit_skill(a["name"], a["content"])
  632. return _patch_skill(a["name"], a["old_string"], a["new_string"], a["file_path"], a["replace_all"])
  633. # action -> handler(args dict) returning a result dict, or a tool_error JSON string for
  634. # argument-shape errors. "edit" is a legacy alias for a full rewrite (not in the schema).
  635. _ACTION_HANDLERS = {
  636. "create": lambda a: _create_skill(a["name"], a["content"], a["category"]),
  637. "edit": lambda a: _edit_skill(a["name"], a["content"]),
  638. "patch": _act_patch,
  639. "delete": lambda a: _delete_skill(a["name"], absorbed_into=a["absorbed_into"]),
  640. "write_file": lambda a: _write_file(a["name"], a["file_path"], a["file_content"]),
  641. "remove_file": lambda a: _remove_file(a["name"], a["file_path"])}
  642. def _record_success(action, name, result, *, file_path, absorbed_into, task_id,
  643. session_id, ledger_before) -> None:
  644. """Best-effort post-mutation side effects (never break the tool): ledger, prompt-cache
  645. clear, curator telemetry (which fires ``on_skill_lifecycle`` for plugins)."""
  646. with suppress(Exception):
  647. from tools import skill_ledger as _ledger
  648. _post = _find_skill(name)
  649. # delete: consolidation vs prune, and whether the recoverable archive handled it
  650. _evidence = ({"absorbed_into": absorbed_into, "archived": bool(result.get("_archived"))}
  651. if action == "delete" else {})
  652. _evidence.update({k: v for k, v in (("session_id", session_id), ("file_path", file_path)) if v})
  653. _ledger.record_mutation(
  654. action, name, before=ledger_before if ledger_before is not None else [],
  655. after_root=_post["path"] if _post else None, evidence=_evidence)
  656. with suppress(Exception):
  657. from agent.prompt_builder import clear_skills_system_prompt_cache
  658. clear_skills_system_prompt_cache(clear_snapshot=True)
  659. # Curator telemetry: only the background review fork marks a skill agent-created
  660. # (foreground creates belong to the user). A recoverable curator archive keeps its
  661. # record as STATE_ARCHIVED (`hermes curator status`/`restore`); only a hard delete forgets.
  662. with suppress(Exception):
  663. from tools.skill_usage import bump_patch, forget, record_created
  664. # During the curator consolidation pass, a verified consolidation must be RECOVERABLE: archival into
  665. # ~/.hermes/skills/.archive/ is documented as the maximum destructive action the curator may take,
  666. # and `hermes curator restore` promises the skill can be brought back. Route through the recoverable
  667. # archive primitive instead of permanent rmtree so a misjudged consolidation can be undone (#29912).
  668. # Foreground, user-directed deletes keep their existing hard-delete semantics.
  669. from tools.skill_provenance import is_background_review
  670. if action == "create":
  671. record_created(name, agent_created=is_background_review(),
  672. task_id=task_id, session_id=session_id)
  673. elif action in {"patch", "edit", "write_file", "remove_file"}:
  674. bump_patch(name, action=action, task_id=task_id, session_id=session_id)
  675. elif action == "delete" and not result.get("_archived"):
  676. forget(name)
  677. def skill_manage(
  678. action: str, name: str, content: str | None = None, category: str | None = None, file_path: str | None = None,
  679. file_content: str | None = None, old_string: str | None = None, new_string: str | None = None,
  680. replace_all: bool = False, absorbed_into: str | None = None, task_id: str | None = None,
  681. session_id: str | None = None, operations=None) -> str:
  682. """Dispatch to the action handler -> JSON string. ``operations`` (atomic batch shape,
  683. see _skill_manage_batch) overrides the flat fields."""
  684. if operations is not None:
  685. return _skill_manage_batch(
  686. operations, default_name=name or None, task_id=task_id, session_id=session_id)
  687. if (preflight := _background_review_preflight(action, name)) is not None:
  688. return json.dumps(preflight, ensure_ascii=False)
  689. # Approval gate: skills are too large to review inline, so they always stage regardless
  690. # of origin; bypassed when replaying an approved staged write.
  691. args = dict(content=content, category=category, file_path=file_path, file_content=file_content,
  692. old_string=old_string, new_string=new_string, replace_all=replace_all,
  693. absorbed_into=absorbed_into)
  694. if (gate_result := _apply_skill_write_gate(action, name, **args)) is not None:
  695. return gate_result
  696. if (shape_err := _op_shape_error(action, args)) is not None:
  697. return tool_error(shape_err, success=False)
  698. # Validate before the lock is keyed on the name, so a rejected name never touches .locks/
  699. # (create takes a bare name; the other actions also accept ``category/name``).
  700. if (name_err := _validate_name(name if action == "create" or not name else Path(name).name)) is not None:
  701. return json.dumps(_err(name_err), ensure_ascii=False)
  702. # A mutation is read-modify-write even when its action eventually delegates
  703. # to a helper: guards, ledger capture, patch matching, validation, rollback,
  704. # and the atomic replacement all belong to the same ownership window.
  705. with _skill_mutation_lock(name):
  706. # Ledger pre-capture: telemetry, not a gate — failures must NEVER block the mutation. delete
  707. # destroys the whole package (consolidation may have re-homed support files first), so
  708. # complete it from the newest curator backup or a restore is hollow.
  709. # Audit ledger (tracker #79686 P3): capture the pre-mutation state of the skill directory so every
  710. # mutation — any actor — lands in the append-only JSONL ledger with before/after blobs.
  711. _ledger_before = None
  712. with suppress(Exception):
  713. from tools import skill_ledger as _ledger
  714. _pre = _find_skill(name)
  715. _ledger_before = _ledger.capture_before(
  716. _pre["path"] if _pre else None, complete_package=(action == "delete"), skill=name)
  717. handler = _ACTION_HANDLERS.get(action, lambda a: _err(
  718. f"Unknown action '{action}'. Use: create, edit, patch, delete, write_file, remove_file"))
  719. result = handler({"name": name, **args})
  720. if isinstance(result, str):
  721. return result # tool_error JSON for argument-shape problems (patch)
  722. if result.get("success"):
  723. _record_success(
  724. action, name, result, file_path=file_path, absorbed_into=absorbed_into,
  725. task_id=task_id, session_id=session_id, ledger_before=_ledger_before)
  726. return json.dumps(result, ensure_ascii=False)
  727. # --- OpenAI Function-Calling Schema -------------------------------------------
  728. def _skill_manage_description() -> str:
  729. return (
  730. "Create, update or delete skills: your procedural memory for recurring "
  731. "tasks. The call is an operations array (a single "
  732. "edit is a list of one); it applies atomically — any failure rolls "
  733. "every touched skill back. Ops: create (full SKILL.md; lands in "
  734. "the profile's skills directory or configured skills.create_dir; must precede that skill's other "
  735. "ops), patch (targeted old_string/new_string fix — preferred; "
  736. "content alone REPLACES the whole file, read it via skill_view() "
  737. "first), write_file/remove_file (supporting files), delete (sole "
  738. "op only). Existing skills are modified wherever they live. "
  739. f"Description: max {SKILL_PROMPT_DESC_LIMIT} chars, 'Use when <trigger>. <behavior>.', never "
  740. "the category name (the index shows it). Write lessons, not logs: "
  741. "imperative rule + why, no PR numbers/dates/incident narration, one "
  742. "rule per lesson, references/ named by topic (extend before adding). "
  743. "skill_view() shows format conventions."
  744. )
  745. _NAME = {"type": "string"}
  746. _OLD_STRING = {"type": "string",
  747. "description": "Text to find (same matching semantics as the patch tool)."}
  748. _NEW_STRING = {"type": "string", "description": "Replacement; empty string deletes the match."}
  749. _FILE_PATH = {
  750. "type": "string",
  751. "description": (
  752. "Path RELATIVE to the skill's own directory, e.g. 'references/api.md' — no leading "
  753. "slash, never absolute; first segment references/, templates/, scripts/, or assets/."
  754. ),
  755. } # stated once (write_file); patch/remove_file point at it
  756. def _op_schema(action: str, props: dict, required: tuple) -> dict:
  757. """One self-contained per-action op shape. ``additionalProperties: false`` is what lets a
  758. grammar-constrained backend refuse another action's text slot outright."""
  759. return {"type": "object", "additionalProperties": False,
  760. "properties": {"name": _NAME, "action": {"type": "string", "enum": [action]}, **props},
  761. "required": ["name", "action", *required]}
  762. SKILL_MANAGE_SCHEMA = {
  763. "name": "skill_manage",
  764. # ONE advertised call shape (memory-tool pattern): the call IS an operations
  765. # array. The legacy flat shape (top-level action/name/content/...) is still
  766. # ACCEPTED for old transcripts and staged-write replay, but not advertised.
  767. "description": _skill_manage_description(),
  768. "parameters": {
  769. "type": "object",
  770. "properties": {
  771. "operations": {
  772. "type": "array",
  773. "description": (
  774. "Ordered ops; each names its target skill (lowercase, hyphens/underscores, "
  775. "max 64 chars). Each action is its own shape; another action's text slot is invalid."
  776. ),
  777. # Per-action branches, not one flat union: with one object holding content /
  778. # new_string / file_content side by side, a 27B model that just used write_file
  779. # kept emitting file_content on create and the whole batch rolled back (#112677).
  780. "items": {"anyOf": [
  781. _op_schema("create", {
  782. "content": {"type": "string",
  783. "description": "Full SKILL.md text (YAML frontmatter + markdown body)."},
  784. "category": {"type": "string",
  785. "description": "Optional category subdir (e.g. 'devops')."},
  786. }, ("content",)),
  787. _op_schema("patch", {
  788. "old_string": _OLD_STRING, "new_string": _NEW_STRING,
  789. "replace_all": {"type": "boolean",
  790. "description": "Replace all occurrences (default false)."},
  791. "file_path": {"type": "string",
  792. "description": "Optional supporting file (write_file's shape); default SKILL.md."},
  793. }, ("old_string", "new_string")),
  794. _op_schema("patch", {
  795. "content": {"type": "string",
  796. "description": "Full SKILL.md rewrite (REPLACES the whole file; last resort)."},
  797. }, ("content",)),
  798. _op_schema("write_file", {
  799. "file_path": _FILE_PATH,
  800. "file_content": {"type": "string", "description": "Full text of the supporting file."},
  801. }, ("file_path", "file_content")),
  802. _op_schema("remove_file", {
  803. "file_path": {"type": "string", "description": "Supporting file (write_file's shape)."},
  804. }, ("file_path",)),
  805. # `absorbed_into` stays in the delete shape: with additionalProperties:false a
  806. # grammar-constrained backend would otherwise strip it and the curator's
  807. # consolidation delete guard would fail-close every consolidation.
  808. _op_schema("delete", {
  809. "absorbed_into": {"type": "string",
  810. "description": "Curator consolidation only: umbrella skill "
  811. "that absorbed this one (must exist)."},
  812. }, ()),
  813. ]},
  814. },
  815. # Also accepted, never advertised: the legacy flat single-op fields.
  816. },
  817. "required": ["operations"],
  818. },
  819. }
  820. # --- Registry ---
  821. from tools.registry import registry, tool_error
  822. registry.register(
  823. name="skill_manage", toolset="skills", schema=SKILL_MANAGE_SCHEMA, emoji="📝",
  824. handler=lambda args, **kw: _skill_manage_from(
  825. args, task_id=kw.get("task_id"), session_id=kw.get("session_id")))