From c2d8d1728545adb1d2b04f35d99ac7ea391faac3 Mon Sep 17 00:00:00 2001
From: Aayush Chaudhary <acaayush1111@gmail.com>
Date: Mon, 2 Mar 2026 09:08:59 +0530
Subject: [PATCH] feat(skills): add DuckDuckGo search skill as Firecrawl
 fallback

---
 skills/research/duckduckgo-search/SKILL.md    | 133 ++++++++++++++++++
 .../duckduckgo-search/scripts/duckduckgo.sh   |  32 +++++
 2 files changed, 165 insertions(+)
 create mode 100644 skills/research/duckduckgo-search/SKILL.md
 create mode 100755 skills/research/duckduckgo-search/scripts/duckduckgo.sh

diff --git a/skills/research/duckduckgo-search/SKILL.md b/skills/research/duckduckgo-search/SKILL.md
new file mode 100644
index 000000000..d5a787cdd
--- /dev/null
+++ b/skills/research/duckduckgo-search/SKILL.md
@@ -0,0 +1,133 @@
+---
+name: duckduckgo-search
+description: Get web search results from DuckDuckGo. Use as fallback when Firecrawl unavailable. No API key needed.
+version: 1.0.0
+author: Hermes Agent
+license: MIT
+metadata:
+  hermes:
+    tags: [Search, DuckDuckGo, Web Search, API, Free]
+    related_skills: [arxiv, ocr-and-documents]
+---
+
+# DuckDuckGo Search
+
+Fast, free web search. No API key required. Use when Firecrawl is unavailable.
+
+## Quick Reference
+
+| Action | Command |
+|--------|---------|
+| Web search | `ddgs text "python async" -k 5` |
+| Images | `ddgs images "cat"` |
+| News | `ddgs news "AI"` |
+| Videos | `ddgs videos "tutorial"` |
+| **Curl fallback** | `curl "https://api.duckduckgo.com/?q=QUERY&format=json"` |
+
+## Prerequisites
+
+### Option 1: Python Library (Recommended)
+
+```bash
+pip install ddgs
+ddgs --help
+```
+
+### Option 2: Curl Only (No Dependencies)
+
+```bash
+# Verify curl is available
+curl --version
+```
+
+No installation needed — curl is standard on all platforms.
+
+## Web Search
+
+### Library (ddgs)
+
+```bash
+# Basic search
+ddgs text "python async programming" -k 5
+
+# With region filter
+ddgs text "best restaurants Tokyo" -k 3 -r jp-jp
+
+# Safe search
+ddgs text "medical advice" -k 5 -s off
+```
+
+### Parameters
+
+| Flag | Description | Example |
+|------|-------------|---------|
+| `-k` | Max results | `-k 5` |
+| `-r` | Region | `-r us-en` |
+| `-s` | Safe search | `-s off` |
+
+### Curl Fallback
+
+```bash
+# Basic search
+curl -s "https://api.duckduckgo.com/?q=python+async&format=json&limit=5"
+
+# Parse results
+curl -s "..." | jq -r '.RelatedTopics[] | "\(.Text) - \(.FirstURL)"'
+```
+
+## Other Search Types
+
+```bash
+# Images
+ddgs images "landscape" -k 10
+
+# News
+ddgs news "artificial intelligence" -k 5
+
+# Videos  
+ddgs videos "python tutorial" -k 5
+```
+
+## Integration
+
+After finding URLs, retrieve full content with `web_extract`:
+
+```bash
+# Find with DDG, then extract
+ddgs text "fastapi tutorial" -k 3
+# Copy URL from output
+web_extract(urls=["https://fastapi.tiangolo.com/tutorial/"])
+```
+
+This is the standard pattern:
+1. **DuckDuckGo** → finds URLs
+2. **web_extract** → retrieves full content
+
+## Use Cases
+
+| Scenario | Tool | Reason |
+|----------|------|--------|
+| "Find tutorials on X" | `ddgs text` + `web_extract` | Need full content |
+| Firecrawl unavailable | `ddgs text` | Free fallback |
+| Quick image search | `ddgs images` | Find images |
+| Latest news | `ddgs news` | News results |
+
+## Error Handling
+
+```bash
+# Check if library installed
+ddgs --help 2>/dev/null || echo "Using curl fallback"
+
+# Rate limiting - add delay
+sleep 1
+
+# No results - try different query
+ddgs text "different keywords" -k 5
+```
+
+## Notes
+
+- **No API key required** — completely free
+- **Rate limit**: ~1 request/second recommended
+- **Always follow up** with `web_extract` for full content
+- Curl fallback has limited results (DDG API restrictions)
diff --git a/skills/research/duckduckgo-search/scripts/duckduckgo.sh b/skills/research/duckduckgo-search/scripts/duckduckgo.sh
new file mode 100755
index 000000000..d0844ec97
--- /dev/null
+++ b/skills/research/duckduckgo-search/scripts/duckduckgo.sh
@@ -0,0 +1,32 @@
+#!/bin/bash
+# DuckDuckGo Search Helper Script
+# Fallback for when ddgs library is unavailable
+# Usage: ./duckduckgo.sh [text|images|news|videos] <query> [limit]
+
+set -e
+
+MODE="${1:-text}"
+QUERY="$2"
+LIMIT="${3:-5}"
+
+if [ -z "$QUERY" ]; then
+    echo "Usage: $0 [text|images|news|videos] <query> [limit]"
+    echo "Examples:"
+    echo "  $0 text 'python async' 5"
+    echo "  $0 images 'cat' 10"
+    exit 1
+fi
+
+# URL encode query
+ENCODED_QUERY=$(echo "$QUERY" | sed 's/ /+/g' | sed 's/&/%26/g' | sed 's/=/%3D/g')
+
+case "$MODE" in
+    text|images|news|videos)
+        curl -s "https://api.duckduckgo.com/?q=${ENCODED_QUERY}&format=json&limit=${LIMIT}"
+        ;;
+    *)
+        echo "Unknown mode: $MODE"
+        echo "Valid modes: text, images, news, videos"
+        exit 1
+        ;;
+esac