Agent skill to perform web search using DDGS

web-search.md

name	web-search
description	Search the web using DuckDuckGo (ddgs), then fetch each result's full page content using the built-in web fetch tool before answering.
allowed-tools	Bash, WebFetch

Search the web for: $ARGUMENTS

How to Run

Step 1: Search

Use uvx ddgs to get search results:

uvx ddgs text -q "QUERY" -m 5

Options:

• -q — search query (required)
• -m — max results (use 5 for fetch-heavy workflows)
• -r — region, e.g. us-en, cn-zh (default: us-en)
• -s — safesearch: on, moderate, off (default: moderate)
• -t — timelimit: d (day), w (week), m (month), y (year)
• -b — backend: google, brave, bing, duckduckgo, auto (default: auto)

---

Step 2: Fetch Each Result

Parse the JSON output from Step 1. For each result, use the built-in WebFetch tool to retrieve the full page content at the href (text search) or url (news search) field.

Fetch all results before proceeding. If a fetch fails or times out, fall back to the body snippet from the search result.

---

Step 3: Synthesize Answer

After fetching all pages:

1. Ground claims in the fetched page content — not just the ddgs snippets.
2. Cite sources by linking to each page's URL.
3. Reconcile conflicts when sources disagree.
4. Note any pages that failed to fetch and relied on snippet fallback.

---

Search Types

Text Search (default)

uvx ddgs text -q "QUERY" -m 5

Output schema:

[{ "title": "...", "href": "https://...", "body": "snippet..." }]

News Search

uvx ddgs news -q "QUERY" -m 5 -t w

Output schema:

[{ "date": "...", "title": "...", "body": "...", "url": "https://...", "source": "..." }]

Image / Video Search

No fetching needed — present results directly from ddgs output.

uvx ddgs images -q "QUERY" -m 10
uvx ddgs videos -q "QUERY" -m 10

---

Error Handling

• If uvx is not found: curl -LsSf https://astral.sh/uv/install.sh | sh
• If results are empty: retry with a rephrased query or drop -t filters.
• If a backend fails: switch to -b google or -b brave.
• Rate limit errors: wait ~5 seconds, then retry.
• If WebFetch fails for a URL: log the error and use the ddgs body snippet as fallback.

---

Tips

• Use 3–5 results (-m 5) when fetching — more results = more fetch time.
• For code/docs, add site:github.com or site:docs.python.org to the query.
• For recent news, use news search with -t d or -t w.
• Use search operators: "exact phrase", -exclude, site:domain.com, filetype:pdf.