Summary

Skills can now declare runtime prerequisites (env_vars, commands) via YAML frontmatter. Skills with unmet prerequisites are automatically hidden from the system prompt so the agent never claims capabilities it can't deliver, and skill_view() returns an actionable warning about what's missing.

This is the generalized fix for the class of bugs where the agent promises a skill-based capability (GIF search, email, Notion, etc.) then fails at execution time because a CLI tool isn't installed or an API key isn't set.

Closes #658
Fixes #630

Motivation

Tools already gate themselves behind availability checks — web_search won't appear without FIRECRAWL_API_KEY, browser_navigate won't appear without agent-browser on PATH, image_generate requires FAL_KEY, etc. Each tool registers a check_fn with the registry, and registry.get_definitions() excludes tools that fail their check.

Skills had no equivalent mechanism. Every skill in ~/.hermes/skills/ was unconditionally advertised in the system prompt regardless of whether its dependencies were present. This meant the agent would promise capabilities (GIF search, email via himalaya, Notion integration) then fail with cryptic command not found errors at execution time.

This PR brings skills to parity with tools by adding the same check semantics in a format appropriate for Markdown-based skills (declarative YAML frontmatter instead of Python callbacks).

How it works

The prerequisites field

---
name: gif-search
description: Search GIFs from Tenor
prerequisites:
  env_vars: [TENOR_API_KEY]     # checked via os.getenv()
  commands: [curl, jq]          # checked via shutil.which()
---

Both sub-fields are optional. Skills without prerequisites behave exactly as before (backward compatible).

Comparison with tool availability checks

Same semantics, appropriate format for each: tools are Python code (callback), skills are Markdown files (declarative YAML).

Three layers of defense

What changed

Core implementation

• tools/skills_tool.py — check_skill_prerequisites(frontmatter) function, updated _find_all_skills() and skill_view(), updated module docstring with spec
• agent/prompt_builder.py — _skill_prerequisites_met() helper, filtering in build_skills_system_prompt()

12 bundled skills tagged with prerequisites

gif-search skill updated

• Replaced hardcoded Tenor public demo API key with ${TENOR_API_KEY} env var
• Added setup instructions for obtaining a free key

Docs

• CONTRIBUTING.md — prerequisites field added to SKILL.md format spec + dedicated "Skill prerequisites" section with guidance on when to declare them

Tests (21 new, 104 total)

• tests/tools/test_skills_tool.py — TestCheckSkillPrerequisites (9), TestFindAllSkillsPrerequisites (3), TestSkillViewPrerequisites (3)
• tests/agent/test_prompt_builder.py — TestSkillPrerequisitesMet (4), prerequisite filtering in TestBuildSkillsSystemPrompt (2)

Files changed (17)

• tools/skills_tool.py — core prerequisite checking
• agent/prompt_builder.py — prompt-level filtering
• CONTRIBUTING.md — spec docs
• 12× skills/*/SKILL.md — prerequisite declarations
• 2× tests/ — 21 new test cases

Test plan

• All 104 tests pass (83 existing + 21 new)
• Verify skill with missing env var doesn't appear in system prompt
• Verify skill_view("gif-search") shows warning when TENOR_API_KEY unset
• Verify skill appears normally when prerequisites are satisfied
• Verify skills without prerequisites field are unaffected