tommy-yw/runbookhermes/duckduckgo-search
Claude Code and agent skill by tommy-yw/runbookhermes
- community
Checking that the SKILL.md file is still in the repository.
Free web search via DuckDuckGo — text, news, images, videos. No API key needed. Prefer the `ddgs` CLI when installed; use the Python DDGS library only after verifying that `ddgs` is available in the current runtime.
Install
npx vskill@latest install tommy-yw/runbookhermes/duckduckgo-searchSKILL.md
The same SKILL.md was published earlier as tommy-yw/runbookhermes/duckduckgo-search.
DuckDuckGo Search
Free web search using DuckDuckGo. No API key required.
Preferred when web_search is unavailable or unsuitable (for example when FIRECRAWL_API_KEY is not set). Can also be used as a standalone search path when DuckDuckGo results are specifically desired.
Detection Flow
Check what is actually available before choosing an approach:
Decision tree:
- If
ddgsCLI is installed, preferterminal+ddgs - If
ddgsCLI is missing, do not assumeexecute_codecan importddgs - If the user wants DuckDuckGo specifically, install
ddgsfirst in the relevant environment - Otherwise fall back to built-in web/browser tools
Important runtime note:
- Terminal and
execute_codeare separate runtimes - A successful shell install does not guarantee
execute_codecan importddgs - Never assume third-party Python packages are preinstalled inside
execute_code
Installation
Install ddgs only when DuckDuckGo search is specifically needed and the runtime does not already provide it.
If a workflow depends on Python imports, verify that same runtime can import ddgs before using from ddgs import DDGS.
Method 1: CLI Search (Preferred)
Use the ddgs command via terminal when it exists. This is the preferred path because it avoids assuming the execute_code sandbox has the ddgs Python package installed.
CLI Flags
| Flag | Description | Example | |
|---|---|---|---|
-q | Query — required | -q "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 |
Method 2: Python API (Only After Verification)
Use the DDGS class in execute_code or another Python runtime only after verifying that ddgs is installed there. Do not assume execute_code includes third-party packages by default.
Safe wording:
- "Use
execute_codewithddgsafter installing or verifying the package if needed"
Avoid saying:
- "
execute_codeincludesddgs" - "DuckDuckGo search works by default in
execute_code"
Important: max_results must always be passed as a keyword argument — positional usage raises an error on all methods.
Text Search
Best for: general research, companies, documentation.
Returns: title, href, body
News Search
Best for: current events, breaking news, latest updates.
Returns: date, title, body, url, image, source
Image Search
Best for: visual references, product images, diagrams.
Returns: title, image, thumbnail, url, height, width, source
Video Search
Best for: tutorials, demos, explainers.
Returns: title, content, description, duration, provider, published, statistics, uploader
Quick Reference
| Method | Use When | Key Fields | |
|---|---|---|---|
text() | General research, companies | title, href, body | |
news() | Current events, updates | date, title, source, body, url | |
images() | Visuals, diagrams | title, image, thumbnail, url | |
videos() | Tutorials, demos | title, content, duration, provider |
Workflow: Search then Extract
DuckDuckGo returns titles, URLs, and snippets — not full page content. To get full page content, search first and then extract the most relevant URL with web_extract, browser tools, or curl.
CLI example:
Python example, only after verifying ddgs is installed in that runtime:
Then extract the best URL with web_extract or another content-retrieval tool.
Limitations
- Rate limiting: DuckDuckGo may throttle after many rapid requests. Add a short delay between searches if needed.
- No content extraction:
ddgsreturns snippets, not full page content. Useweb_extract, browser tools, or curl for the full article/page. - 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 wait a few seconds.
- Field variability: Return fields may vary between results or
ddgsversions. Use.get()for optional fields to avoidKeyError. - Separate runtimes: A successful
ddgsinstall in terminal does not automatically meanexecute_codecan import it.
Troubleshooting
| Problem | Likely Cause | What To Do | |
|---|---|---|---|
ddgs: command not found | CLI not installed in the shell environment | Install ddgs, or use built-in web/browser tools instead | |
ModuleNotFoundError: No module named 'ddgs' | Python runtime does not have the package installed | Do not use Python DDGS there until that runtime is prepared | |
| Search returns nothing | Temporary rate limiting or poor query | Wait a few seconds, retry, or adjust the query | |
CLI works but execute_code import fails | Terminal and execute_code are different runtimes | Keep using CLI, or separately prepare the Python runtime |
Pitfalls
- `max_results` is keyword-only:
ddgs.text("query", 5)raises an error. Useddgs.text("query", max_results=5). - Do not assume the CLI exists: Check
command -v ddgsbefore using it. - Do not assume `execute_code` can import `ddgs`:
from ddgs import DDGSmay fail withModuleNotFoundErrorunless that runtime was prepared separately. - Package name: The package is
ddgs(previouslyduckduckgo-search). Install withpip install ddgs. - Don't confuse `-q` and `-m` (CLI):
-qis for the query,-mis for max results count. - Empty results: If
ddgsreturns nothing, it may be rate-limited. Wait a few seconds and retry.
Validated With
Validated examples against ddgs==9.11.2 semantics. Skill guidance now treats CLI availability and Python import availability as separate concerns so the documented workflow matches actual runtime behavior.
Security
- Security scanPassed, 95 of 100Pattern checks on the skill's files.
- Model reviewPassed
Quality evaluation
- Task evaluationNot runNo evaluation yet. Run one in Skill Studio.
Source
- SKILL.md in the repositoryCheckingoptional-skills/research/duckduckgo-search/SKILL.md
Popularity
- Repository stars
- 547
- Repository forks
- 41
- 7-day trend score
- 32
Stars and forks are for the whole GitHub repository, not this skill alone. Not refreshed yet.
Works with
Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.
- Claude Code
- Cursor
- GitHub Copilot
- Windsurf
- Codex
- Gemini CLI
- Cline
- Amp
- Roo Code
- Goose
- Continue
- Kilo Code
- Junie
- Trae
- OpenHands
- Qwen Code
- AI Agent
- Tabnine Chat
- Sourcegraph Cody
- Amazon Q
- Firebase Genkit
- Sweep
- Devin
- Phind
- Mentat
- Claude Desktop
- Aider
- GPT Pilot
- Plandex
- bolt.new
- v0
- Replit Agent
- Anse
- TypingMind
- BetterChatGPT
- LibreChat
- Warp AI
- Pieces
- Fig AI
Embed badge
[](https://verified-skill.com/skills/tommy-yw/runbookhermes/duckduckgo-search)