NousResearch/hermes-agent · error · ValueError

Unknown skill(s): {missing_display}

Error message

Unknown skill(s): {missing_display}

What it means

Raised by skill preloading when the caller requested a set of skills and NONE of them resolve to installed skills. This is a deliberate hard-fail (the comment notes it applies to Kanban workers) so a fully misconfigured worker fails loudly instead of running blind. If at least one requested skill loaded, the code only logs a warning and continues.

Source

Thrown at cli.py:7482

            return
        skills_prompt, loaded_skills, missing_skills = result
        if missing_skills:
            missing_display = ", ".join(missing_skills)
            # If at least one skill loaded, degrade gracefully: skip the
            # unknown ones and continue. A typo'd skill name should not crash
            # the worker (which auto-blocks the Kanban task after retries).
            # Only when EVERY requested skill is missing do we hard-fail, so a
            # fully-misconfigured worker fails loudly instead of running blind.
            if loaded_skills:
                logger.warning(
                    "Unknown skill(s) requested, skipping: %s. "
                    "Continuing with: %s. "
                    "List available skills with `hermes skills list`.",
                    missing_display,
                    ", ".join(loaded_skills),
                )
            else:
                raise ValueError(f"Unknown skill(s): {missing_display}")
        if skills_prompt:
            self.system_prompt = "\n\n".join(
                part for part in (self.system_prompt, skills_prompt) if part
            ).strip()
            self.preloaded_skills = loaded_skills

    def show_banner(self):
        """Display the welcome banner in Claude Code style."""
        self.console.clear()
        ctx_len = None
        if hasattr(self, 'agent') and self.agent and hasattr(self.agent, 'context_compressor'):
            ctx_len = self.agent.context_compressor.context_length
        
        # Auto-compact for narrow terminals — the full banner with caduceus
        # + tool list needs ~80 columns minimum to render without wrapping.
        term_width = shutil.get_terminal_size().columns
        use_compact = self.compact or term_width < 80
        

View on GitHub (pinned to c896c09c42)

Solutions

1. Run `hermes skills list` and compare against the requested names
2. Fix typos / use the exact skill directory name
3. If the skill is in optional-skills, install it: `hermes skills install official/<category>/<skill>`
4. If a curator archive ate it, restore with `hermes curator restore <skill>`

Example fix

# before
cli --skills reserch-daily  # ValueError: Unknown skill(s): reserch-daily

# after
hermes skills list            # discover exact name 'research-daily'
cli --skills research-daily

from pathlib import Path
from hermes_constants import get_hermes_home

def known_skills(requested: list[str]) -> set[str]:
    installed = {p.name for p in (get_hermes_home() / "skills").iterdir() if p.is_dir()}
    return set(requested) & installed

try:
    cli.preload_skills(skills=["research-daily"])
except ValueError as e:
    if str(e).startswith("Unknown skill(s)"):
        missing = [s for s in e.args[0].split(": ", 1)[1].split(", ")]
        raise SystemExit(f"Install or fix: {missing}; see `hermes skills list`") from e
    raise

When it happens

Trigger: Starting the CLI (or a Kanban worker spawn) with a skills list where every name is unknown: e.g. `hermes --skills reserch-daily,report-writer` where neither exists under the skills directories, or a kanban task assigning skills that were never installed/renamed.

Common situations: Typo in a skill name, referencing a skill that lives in optional-skills but was never installed via `hermes skills install`, a skill renamed or archived by the curator, or a profile whose HERMES_HOME lacks the skill the task expects.

Related errors

• SSH remote mode is selected but no host is configured.
• Could not create directory: ${error.message}
• ${res.message || 'Archive failed'}
• The 'claude' CLI is not installed. Install it with: npm inst
• No LLM provider configured for task={task} provider={resolve

AI-assisted analysis of NousResearch/hermes-agent@c896c09c42 (2026-08-14). Data as JSON: /api/errors/993d7a3711490dc5. Report an issue: GitHub.