PR #17630: feat: skill subcommand completions via metadata.hermes.ui

• Repository: NousResearch/hermes-agent
• Author: androidi
• State: open | merged: False
• Link: https://github.com/NousResearch/hermes-agent/pull/17630

Description (problem / solution / changelog)

What does this PR do?

Add support for skill-declared subcommand tab-completion without requiring a CommandDef entry in COMMAND_REGISTRY.

Motivation: Custom skills registered via /skill-name feel like second-class commands compared to built-ins like /skin or /model — no tab-completion, no display_meta, no subcommand hints. This makes skills feel disconnected from Hermes Agent itself, even when they have well-defined subcommands.

By extracting subcommand metadata from SKILL.md frontmatter, custom skills now get the same first-class autocomplete experience as built-in commands.

Skills declare their subcommands in SKILL.md frontmatter:

    metadata:
      hermes:
        ui:
          subcommands:
            list: Show all ideas in a table
            new: Create a new idea from user input
            status: Show full status of a specific idea

Descriptions are shown as display_meta in tab-completion (max 50 chars, truncated with '...' if longer). No changes to COMMAND_REGISTRY required — fully additive.

Related Issue

Fixes #17621

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

• agent/skill_commands.py: scan_skill_commands() now extracts metadata.hermes.ui.subcommands (dict {subcommand: description}) from SKILL.md frontmatter into the _skill_commands dict.
• hermes_cli/commands.py: SlashCommandCompleter.get_completions() checks _skill_commands for matching skill subcommands after static SUBCOMMANDS, yielding Completion objects with display_meta from the subcommand description.
• skills/software-development/hermes-agent-skill-authoring/SKILL.md: Documents the metadata.hermes.ui convention with examples.
• CONTRIBUTING.md: Added documentation for new subcommand parsing functionality.

How to Test

1. Register a skill with metadata.hermes.ui.subcommands — add this to any skill's SKILL.md frontmatter:

metadata:
  hermes:
    ui:
      subcommands:
        list: Show all items in a table
        find: Search by name or content

1. Restart Hermes (/reset or /restart) so the skill loader picks up the new directory

2. Type the skill command + space, then press Tab — you should see the subcommands listed with their descriptions as display_meta:

/ideas li<Tab>  →  /ideas list    Show all items in a table

1. Type a partial subcommand — completions are filtered to matching entries:

/ideas f<Tab>  →  /ideas find    Search by name or content

1. Skills without ui.subcommands yield no completions — no crash, no output
2. Descriptions over 50 chars are truncated with ... at 50 chars
3. Run the new tests:

pytest tests/agent/test_skill_ui_subcommands.py tests/hermes_cli/test_skill_subcommand_completions.py -v

Expected: 15/15 pass

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run pytest tests/ -q and all tests pass
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: Debian 13

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings) — or N/A
• [N/A] I've updated cli-config.yaml.example if I added/changed config keys — or N/A
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — or N/A
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide — or N/A
• [N/A] I've updated tool descriptions/schemas if I changed tool behavior — or N/A

Screenshots / Logs

Changed files

• CONTRIBUTING.md (modified, +17/-0)
• agent/skill_commands.py (modified, +6/-0)
• hermes_cli/commands.py (modified, +19/-0)
• skills/software-development/hermes-agent-skill-authoring/SKILL.md (modified, +4/-0)
• tests/agent/test_skill_ui_subcommands.py (added, +110/-0)
• tests/hermes_cli/test_skill_subcommand_completions.py (added, +236/-0)