Overview

Skills that wrap external services often need API keys to function. Currently, there's no way for a skill to declare its requirements, and no secure mechanism to collect credentials when they're needed.

This enhancement adds a requires.env section to skill frontmatter that declares environment variables. When the skill is loaded at runtime — either by the agent calling skill_view() or the user invoking a /skill command — the system checks for missing env vars and triggers a secure TUI prompt (identical to the sudo password widget) to collect them. Keys are written to ~/.hermes/.env, never exposed in LLM chat context or session logs.

Design

Skill Frontmatter requires.env Section

---
name: my-service-skill
description: Integrate with SomeService API
version: 1.0.0
metadata:
  hermes:
    tags: [api, integration]
    requires:
      env:
        - key: SOME_API_KEY
          prompt: "SomeService API key"
          url: "https://someservice.com/account/api-keys"
        - key: SOME_PROJECT_ID
          prompt: "SomeService project ID"
          url: "https://someservice.com/projects"
---

Runtime Trigger (Primary UX)

When a skill with requires.env is loaded and an env var is missing, the TUI shows a secure input widget — same pattern as sudo password entry:

  ╭─ 🔑 API Key Required ──────────────────────────────────────╮
  │                                                             │
  │  Skill 'my-service' requires: SOME_API_KEY                 │
  │  SomeService API key                                       │
  │  Get one at: https://someservice.com/account/api-keys      │
  │                                                             │
  │  Enter key below (hidden), or press Enter to skip          │
  ╰─────────────────────────────────────────────────────────────╯
  🔑 > ********
  ✓ Saved to ~/.hermes/.env

How it works (mirrors sudo password exactly):

1. skill_view() parses frontmatter, finds requires.env
2. Checks each key against os.environ / ~/.hermes/.env
3. If missing: sets cli._secret_state = {"key": "...", "prompt": "...", "url": "...", "response_queue": Queue()}
4. TUI renders a ConditionalContainer with masked input (same as sudo widget at cli.py:3193-3217)
5. User types key (hidden) or presses Enter to skip
6. Key written to ~/.hermes/.env, loaded into os.environ
7. skill_view() callback resolves, returns skill content

Key Behaviors

1. Secure by design — Keys use the TUI masked input widget. Never flows through LLM chat context, tool results, or session logs. Written directly to ~/.hermes/.env.

2. Skippable — User can press Enter to skip. The skill loads but the agent is told: "Note: SOME_API_KEY is not configured. This skill's functionality will be limited. The user can set it in ~/.hermes/.env or reload the skill to be prompted again."

3. One-time — Once saved to .env, subsequent skill loads find the key and skip the prompt. Persists across sessions.

4. Sequential — If multiple keys are required, prompt them one at a time.

5. Gateway fallback — For Telegram/Discord users (no TUI), display a message: "⚠️ Skill requires SOME_API_KEY. Please add it to ~/.hermes/.env on your server, then try again." No attempt to collect secrets through chat.

6. Install-time convenience — hermes skills install can also check requires.env and prompt via getpass.getpass() (CLI mode, no TUI needed). This is secondary — the runtime prompt catches anything missed.

Implementation Plan

Phase 1: Core env var prompting

• Parse requires.env from skill YAML frontmatter
• New callback: secret_input_callback(cli, key, prompt, url) in hermes_cli/callbacks.py
• New TUI widget: ConditionalContainer for _secret_state in cli.py
• Integration in skill_view(): check env vars, invoke callback if missing
• Write to ~/.hermes/.env on success

Phase 2: Install-time + doctor

• hermes skills install also prompts for missing env vars after confirmation
• hermes doctor reports installed skills with missing requirements
• hermes skills configure <name> — re-prompt for an installed skill's env vars

Phase 3: Runtime awareness

• When building the skill index for the system prompt, annotate skills with unmet requirements: "⚠️ requires SOME_API_KEY" next to the skill description
• Agent can see at a glance which skills are fully configured vs. missing keys

Existing Patterns to Build On

Use Cases

Scope Boundaries

This issue is only about env var requirements and secure prompting. MCP server auto-configuration (discovering tools, adding MCP entries to config.yaml, selective tool loading) is tracked separately in the MCP Server Management issue.

References

• hermes_cli/callbacks.py:63-101 — Sudo password callback (the pattern to follow)
• cli.py:3193-3217 — Sudo password TUI widget
• Feature: ml.ink Skill — Agent-Native Production Deployment via MCP (Freysa AI) #495 — ml.ink skill (motivating use case)
• MCP Server Management issue (companion — handles MCP-specific configuration)