feat(skills): /learn — distill a verified skill from directories of source material

[teknium1]

Summary

Adds /learn — feed Hermes directories of source material (code, API docs, manuals, PDFs, configs) and it distills a verified reusable skill instead of you writing one by hand.

The flow: ingest + classify sources → assemble a token-budgeted corpus → synthesize a draft SKILL.md via the main model → verify it in a throwaway sandbox → commit the skill only when the verification tier meets the floor.

All surfaces call one shared engine (agent/skill_distill.py) — zero new model tools (footprint-ladder rung 2: CLI command + skill-producing engine).

Surfaces

• CLI subcommand: hermes learn <dir> [dir ...] [--hint --category --run --min-tier --json]
• In-session /learn slash command — works in CLI, the Ink TUI, and every messaging platform (registry-driven; TUI forwards via the slash worker → cli.process_command)
• Dashboard: Skills tab → Learn from sources dialog, backed by a new POST /api/skills/learn endpoint

Honest verification (not a boolean)

Each distilled skill is stamped with the tier it actually reached:

Tier	Meaning
executed	shell snippets ran (rc 0) in a sandbox
checked	frontmatter valid, snippets parse, commands resolve on PATH
unverified	valid skill, nothing runnable to test
failed	failed basic validation (not committed)

Default commit floor is checked. --run executes only allowlisted read-only snippets (--version, --help, ls, …) in a temp dir; destructive/network-mutating commands are never auto-run, and --run is admin-gated over the gateway.

Design notes

• Synthesis goes through call_llm(task="skill_distill") → main-model-first, cache-safe, no conversation-prompt-cache invalidation. Per-task override via auxiliary.skill_distill.*.
• Commit reuses tools.skill_manager_tool._create_skill (validation + security scan).
• Tunables under skills.distill.* in config.yaml.

Changes

• agent/skill_distill.py (new): ingest/classify, corpus, synth, sandbox verify, stamp, commit, shared renderer
• hermes_cli/subcommands/learn.py (new) + main.py wiring + commands.py registry entry
• cli.py + hermes_cli/cli_commands_mixin.py: /learn in-session handler
• gateway/run.py + gateway/slash_commands.py: gateway /learn (admin-gated --run, runs in executor)
• ui-tui/src/app/slash/commands/ops.ts: TUI /learn command
• web/src/lib/api.ts + web/src/pages/SkillsPage.tsx: dashboard dialog + API method/type
• hermes_cli/web_server.py: /api/skills/learn endpoint
• website/docs/user-guide/features/skills.md: docs
• tests/agent/test_skill_distill.py (new): 13 targeted tests

Validation

• 13/13 engine tests pass (ingest/prune, corpus priority+budget, all 4 verification tiers, unsafe-snippet guard, frontmatter stamping, orchestrator floor-gating both ways)
• All 9 touched Python files compile
• Live E2E: hermes learn against a real source dir — synthesized + committed a valid skill with the tier stamped; gateway handler live-tested through a fake messenger event and reached the executed tier by running snippets in the sandbox

Infographic

[github-actions]

🔎 Lint report: hermes/hermes-0184cf20 vs origin/main

ruff

Total: 0 on HEAD, 0 on base (➖ 0)

🆕 New issues: none

✅ Fixed issues: none

Unchanged: 0 pre-existing issues carried over.

ty (type checker)

Total: 10967 on HEAD, 10965 on base (🆕 +2)

🆕 New issues (2):

Rule	Count
unresolved-import	1
unresolved-attribute	1

First entries

tests/agent/test_skill_distill.py:14: [unresolved-import] unresolved-import: Cannot resolve imported module `pytest`
gateway/slash_commands.py:2319: [unresolved-attribute] unresolved-attribute: Object of type `Self@_handle_learn_command` has no attribute `config`

✅ Fixed issues: none

Unchanged: 5775 pre-existing issues carried over.

Diagnostics are surfaced as warnings — this check never fails the build.

[tonydwb]

Code Review Summary

Verdict: Comment (high surface area)

What was changed

New skill: /learn — distill a verified skill from directories of source material. This is a major new skill that can ingest a directory of source code/text and produce a working SKILL.md file. 1615 additions across 14 files.

Observations

This is a substantial new feature (SKILL.md generation from source material). The implementation includes:

• A new /learn CLI command
• Skill distillation logic (reading source files, analyzing patterns, generating documentation)
• Template-based output (produces .skills/SKILL.md format)

Given the complexity of the skill generation (prompt engineering, file selection, template rendering), the output quality depends heavily on the distillation prompt.

High-surface-area note

14 files, 1615 additions. As a new major skill, recommend thorough testing of edge cases:

• Empty directories
• Non-code files mixed with code
• Very large files (>10k lines)
• Binary/non-text files in source directories

The print() statements in the diff appear to be user-facing progress output (which is expected for an interactive CLI tool), not debug artifacts.

Security

No hardcoded secrets or credentials. The skill reads local files and generates documentation — no network I/O or credential handling.

---

Reviewed by Hermes Agent

[teknium1]

Superseded by #51506 (merged: e32ebc6). Reworked /learn to be open-ended and engine-free per review: instead of a directory-only distillation engine, /learn now takes anything you can describe (a dir, a URL, the workflow you just walked the agent through, pasted notes) and the live agent gathers it with its own tools and authors the SKILL.md via skill_manage. No engine, no model-tool footprint, works on any terminal backend (local/Docker/remote). Includes the dashboard Skills-page 'Learn a skill' panel.