feat: add prerequisites field to skill spec — hide skills with unmet dependencies

Skills can now declare runtime prerequisites (env vars, CLI binaries) via
YAML frontmatter. Skills with unmet prerequisites are excluded from the
system prompt so the agent never claims capabilities it can't deliver, and
skill_view() warns the agent about what's missing.

Three layers of defense:
- build_skills_system_prompt() filters out unavailable skills
- _find_all_skills() flags unmet prerequisites in metadata
- skill_view() returns prerequisites_warning with actionable details

Tagged 12 bundled skills that have hard runtime dependencies:
gif-search (TENOR_API_KEY), notion (NOTION_API_KEY), himalaya, imessage,
apple-notes, apple-reminders, openhue, duckduckgo-search, codebase-inspection,
blogwatcher, songsee, mcporter.

Closes #658
Fixes #630
This commit is contained in:
kshitij 2026-03-08 12:55:09 +05:30
parent 76545ab365
commit f210510276
17 changed files with 336 additions and 11 deletions

View file

@ -328,6 +328,11 @@ license: MIT
platforms: [macos, linux] # Optional — restrict to specific OS platforms
# Valid: macos, linux, windows
# Omit to load on all platforms (default)
prerequisites: # Optional — runtime requirements
env_vars: [MY_API_KEY] # Env vars that must be set
commands: [curl, jq] # CLI binaries that must be on PATH
# Skills with unmet prerequisites are hidden
# from the system prompt and flagged in skill_view.
metadata:
hermes:
tags: [Category, Subcategory, Keywords]
@ -366,6 +371,25 @@ platforms: [windows] # Windows only
If the field is omitted or empty, the skill loads on all platforms (backward compatible). See `skills/apple/` for examples of macOS-only skills.
### Skill prerequisites
Skills can declare runtime prerequisites via the `prerequisites` frontmatter field. Skills with unmet prerequisites are automatically hidden from the system prompt (the agent won't claim it can use them) and show a clear warning in `skill_view()` telling the agent what's missing.
```yaml
prerequisites:
env_vars: [TENOR_API_KEY] # Env vars checked via os.getenv()
commands: [curl, jq] # CLI binaries checked via shutil.which()
```
Both sub-fields are optional — declare only what applies. If the field is omitted entirely, the skill is always available (backward compatible).
**When to declare prerequisites:**
- The skill uses a CLI tool that isn't universally installed (e.g., `himalaya`, `openhue`, `ddgs`)
- The skill requires an API key in the environment (e.g., `NOTION_API_KEY`, `TENOR_API_KEY`)
- Without these, the skill's commands will fail — not just degrade gracefully
See `skills/gifs/gif-search/` and `skills/email/himalaya/` for examples.
### Skill guidelines
- **No external dependencies unless absolutely necessary.** Prefer stdlib Python, curl, and existing Hermes tools (`web_extract`, `terminal`, `read_file`).