kshitij f210510276 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

2026-03-08 13:19:32 +05:30

3.3 KiB

Raw Blame History

name

description

version

author

license

metadata

prerequisites

duckduckgo-search

Free web search via DuckDuckGo when Firecrawl is unavailable. No API key needed. Use ddgs CLI or Python library to find URLs, then web_extract for content.

1.1.0

gamedevCloudy

MIT

hermes

DuckDuckGo Search (Firecrawl Fallback)

Free web search using DuckDuckGo. No API key required.

When to Use This

Use this skill ONLY when the web_search tool is not available (i.e., FIRECRAWL_API_KEY is not set). If web_search works, prefer it — it returns richer results with built-in content extraction.

Signs you need this fallback:

web_search tool is not listed in your available tools
web_search returns an error about missing FIRECRAWL_API_KEY

Setup

# Install the ddgs package (one-time)
pip install ddgs

Web Search (Primary Use Case)

Via Terminal (ddgs CLI)

# Basic search — returns titles, URLs, and snippets
ddgs text -k "python async programming" -m 5

# With region filter
ddgs text -k "best restaurants" -m 5 -r us-en

# Recent results only (d=day, w=week, m=month, y=year)
ddgs text -k "latest AI news" -m 5 -t w

# JSON output for parsing
ddgs text -k "fastapi tutorial" -m 5 -o json

Via Python (in execute_code)

from hermes_tools import terminal

# Search and get results
result = terminal("ddgs text -k 'python web framework comparison' -m 5")
print(result["output"])

CLI Flags

Flag	Description	Example
`-k`	Keywords (query) — required	`-k "search terms"`
`-m`	Max results	`-m 5`
`-r`	Region	`-r us-en`
`-t`	Time limit	`-t w` (week)
`-s`	Safe search	`-s off`
`-o`	Output format	`-o json`

Other Search Types

# Image search
ddgs images -k "landscape photography" -m 10

# News search
ddgs news -k "artificial intelligence" -m 5

# Video search
ddgs videos -k "python tutorial" -m 5

Workflow: Search → Extract

DuckDuckGo finds URLs. To get full page content, follow up with web_extract:

Search with ddgs to find relevant URLs
Extract content using the web_extract tool (if available) or curl

# Step 1: Find URLs
ddgs text -k "fastapi tutorial" -m 3

# Step 2: Extract full content from a result URL
# (use web_extract tool if available, otherwise curl)
curl -s "https://example.com/article" | head -200

Limitations

Rate limiting: DuckDuckGo may throttle after many rapid requests. Add sleep 1 between searches if needed.
No content extraction: ddgs only returns titles, URLs, and snippets — not full page content. Use web_extract or curl for that.
Results quality: Generally good but less configurable than Firecrawl's search.
Availability: DuckDuckGo may block requests from some cloud IPs. If searches return empty, try different keywords or add a short delay.

Pitfalls

Don't confuse -k and -m: -k is for keywords (the query), -m is for max results count.
Package name: The package is ddgs (was previously duckduckgo-search). Install with pip install ddgs.
Empty results: If ddgs returns nothing, it may be rate-limited. Wait a few seconds and retry.

3.3 KiB Raw Blame History