Summary

Merges PR #723 by @kshitijk4poor — rebased onto current main with conflict resolution and minor fixes.

When a skill declares required_environment_variables in its YAML frontmatter, missing env vars trigger a secure TUI prompt (identical to the sudo password widget) when the skill is loaded. Secrets flow directly to ~/.hermes/.env, never entering LLM context.

Key Changes

Core feature (tools/skills_tool.py):

• New required_environment_variables frontmatter field
• SkillReadinessStatus enum (AVAILABLE, SETUP_NEEDED, UNSUPPORTED)
• _capture_required_environment_variables() — orchestrates secure prompting
• set_secret_capture_callback() — callback pattern (same as sudo)
• Env var name validation via regex, newline stripping
• Remote backend handling: conservative setup_needed=True for docker/ssh/modal/etc.
• Gateway surface detection: never collects secrets in-band

CLI integration (cli.py, hermes_cli/callbacks.py):

• prompt_for_secret() — 120s TUI prompt with masked input (🔑 icon)
• Non-TUI fallback via getpass.getpass()
• Dynamic panel widget sizing using _panel_box_width() (improved over original PR)
• Key bindings: Enter submits, Ctrl-C/Escape cancels

Skill slash commands (agent/skill_commands.py):

• build_skill_invocation_message() now routes through skill_view() for env setup
• Setup status notes added to skill invocation messages

Config (hermes_cli/config.py):

• save_env_value_secure() — writes to .env with 0o600 permissions
• Env var name validation, newline stripping, os.environ update

12 skills updated with prerequisites:
gif-search, himalaya, notion, apple-notes/reminders/imessage, codebase-inspection, mcporter, songsee, blogwatcher, duckduckgo-search, openhue

Security: Secrets never enter LLM context. The callback result contains only metadata (stored_as, skipped, validated) — never the secret value.

Merge Details

Original PR #723 was 264 commits behind main with 7 merge conflicts. All conflicts resolved:

• CONTRIBUTING.md — kept both conditional activation + setup metadata sections
• cli.py — merged command_running state + secret state, hint height, honcho flush
• skills/research/duckduckgo-search/SKILL.md — kept both fallback_for_toolsets + prerequisites
• tests/agent/test_prompt_builder.py — updated imports for renamed function
• tests/test_run_agent.py — kept current call_llm mock (not stale get_text_auxiliary_client)
• tools/skills_tool.py — preserved disabled skill filtering + platform check ordering
• website/docs/user-guide/features/skills.md — kept both conditional activation + secure setup sections

Minor Fix

• Secret display widget now uses _panel_box_width() for dynamic sizing instead of hardcoded width (matches sudo/approval widget pattern)

Test Plan

• 3424 tests pass (6 pre-existing failures unrelated to this PR)
• ~48 new tests covering: skip/cancel, timeout, gateway fallback, legacy prerequisites, 5 remote backends (ssh/docker/modal/singularity/daytona), security (no stdout leak, file perms, redaction, payload sanitization)

Closes #688

Co-authored-by: kshitijk4poor kshitijk4poor@users.noreply.github.com