hermes-agent/hermes_cli/subcommands/learn.py
teknium1 34df600e65
feat(skills): /learn — distill a verified skill from directories of source material
Point Hermes at directories of source material (code, API docs, manuals,
PDFs, configs) and it distills a reusable skill: ingest + classify -> draft
SKILL.md via the main model -> sandboxed verification -> commit only when the
verification tier meets the floor.

Surfaces (all call the shared agent/skill_distill.py engine):
- CLI: `hermes learn <dirs> [--hint --category --run --min-tier --json]`
- In-session /learn slash command (CLI + TUI + every messaging platform)
- Dashboard: Skills tab 'Learn from sources' dialog + /api/skills/learn endpoint

Verification is an honest tier (executed / checked / unverified / failed),
stamped into the skill frontmatter; never claims 'tested' when only parsed.
--run executes only allowlisted read-only snippets in a throwaway temp dir,
and is admin-gated over the gateway. Zero new model tools (footprint ladder
rung 2). Synthesis uses call_llm(task='skill_distill') so it's main-model-first
and cache-safe.

13 targeted engine tests; live-tested CLI + gateway end-to-end (reached the
'executed' tier in a sandbox).
2026-06-16 06:20:40 -07:00

65 lines
2.2 KiB
Python

"""``hermes learn`` subcommand parser.
Distills a reusable skill from one or more directories of source material
(source code, API docs, instruction manuals, PDFs, configs). Backed by
``agent.skill_distill.distill_skill_from_dirs``.
Handler injected to avoid importing ``main``.
"""
from __future__ import annotations
from typing import Callable
def build_learn_parser(subparsers, *, cmd_learn: Callable) -> None:
"""Attach the ``learn`` subcommand to ``subparsers``."""
learn_parser = subparsers.add_parser(
"learn",
help="Distill a reusable skill from directories of source material",
description=(
"Point Hermes at one or more directories (source code, API docs, "
"instruction manuals, PDFs, configs). It ingests the material, "
"synthesizes a draft SKILL.md, verifies it in a sandbox, and "
"commits the skill only when verification passes."
),
)
learn_parser.add_argument(
"paths",
nargs="+",
help="One or more directories (or files) of source material",
)
learn_parser.add_argument(
"--hint",
default="",
help="Free-text steer for the distillation (e.g. 'focus on the auth flow')",
)
learn_parser.add_argument(
"--category",
default="",
help="Category folder to place the new skill under",
)
learn_parser.add_argument(
"--run",
action="store_true",
help=(
"Attempt to execute safe, read-only shell snippets from the draft "
"in a throwaway sandbox (verification can reach the 'executed' tier). "
"Off by default."
),
)
learn_parser.add_argument(
"--min-tier",
default="checked",
choices=["executed", "checked", "unverified"],
help=(
"Minimum verification tier required to commit the skill "
"(default: checked). Drafts below the floor are shown but not saved."
),
)
learn_parser.add_argument(
"--json",
action="store_true",
help="Emit the result as JSON instead of a human summary",
)
learn_parser.set_defaults(func=cmd_learn)