DuckDuckGo Web Search Skill

An Agent Skill for searching web content via DuckDuckGo.

Overview

This Skill provides a command-line tool for web search using the ddgs Python package. Suitable for:

• Real-time web information needs in AI coding tools
• Fetching search results in OpenClaw workflows

Core Features

• Web Search: General web search
• News Search: Dedicated news content search
• Multiple Output Formats: Text or JSON format
• Flexible Configuration: Region, time limits, and safe search level

Installation

This project uses uv as the Python package manager.

Option 1: Run with uv (Recommended)

# Run the script directly (uv will auto-install dependencies)
uv run scripts/ddgs_search.py "Python programming"

# Or navigate to the directory first
cd skills/ddgs-search
uv run scripts/ddgs_search.py "machine learning"

Option 2: Manual Dependency Installation

# Install dependencies using uv
uv pip install ddgs

# Or use pip
pip install ddgs

Quick Start

Basic Usage

# Run with uv (recommended)
uv run scripts/ddgs_search.py "Python programming"

# Limit the number of results
uv run scripts/ddgs_search.py "machine learning" --max-results 5

# Search news
uv run scripts/ddgs_search.py "tech news" --news

# JSON output (for programmatic parsing)
uv run scripts/ddgs_search.py "API documentation" --json

# Time limit (today)
uv run scripts/ddgs_search.py "breaking news" --timelimit d

Complete Parameter Reference

Parameter	Short	Description	Default
query	-	Search keywords	Required
--max-results	-n	Maximum number of results	10
--region	-r	Region code	wt-wt
--safesearch	-s	Safe search (on/moderate/off)	moderate
--timelimit	-t	Time limit (d/w/m/y)	-
--backend	-b	Search backend (auto/html/lite)	auto
--news	-	Search news	-
--json	-j	JSON format output	-
--verbose	-v	Show detailed information	-

Region Code Examples

• wt-wt - Worldwide (default)
• us-en - United States English
• cn-zh - China Chinese
• jp-jp - Japan
• uk-en - United Kingdom

Time Limits

• d - Past day
• w - Past week
• m - Past month
• y - Past year

Usage in OpenClaw

In OpenClaw workflows, you can invoke it via the bash tool:

# Example workflow step
- name: search_web
  tool: bash
  command: cd skills/ddgs-search && uv run scripts/ddgs_search.py "{{ query }}" --json

Or using the Python tool:

# Assuming the current directory is the project root
import subprocess
import json

result = subprocess.run(
    ["uv", "run", "skills/ddgs-search/scripts/ddgs_search.py", "Python tips", "--json"],
    capture_output=True,
    text=True
)
data = json.loads(result.stdout)

Return Result Format

Web Search Results

[
  {
    "title": "Result Title",
    "href": "https://example.com/page",
    "body": "Page snippet/description..."
  }
]

News Search Results

[
  {
    "title": "News Headline",
    "href": "https://news.example.com/article",
    "body": "Article summary...",
    "date": "2024-01-15",
    "source": "News Source Name"
  }
]

Usage Examples

Example 1: Search Technical Documentation

uv run scripts/ddgs_search.py "FastAPI documentation" -n 5

Example 2: Get Latest News

uv run scripts/ddgs_search.py "artificial intelligence" --news -t d -n 3

Example 3: Chinese Search

uv run scripts/ddgs_search.py "机器学习教程" -r cn-zh -n 8

Example 4: JSON Output Processing

uv run scripts/ddgs_search.py "python tips" --json | jq '.[0].href'

FAQ

uv Not Installed

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

ImportError: No module named 'ddgs'

# Install using uv
uv pip install ddgs

# Or run in the script directory (uv will auto-handle)
cd skills/ddgs-search
uv run scripts/ddgs_search.py "query"

Empty Search Results

• Check network connection
• Try changing the --backend parameter (auto/html/lite)
• Some regions may require a proxy

Rate Limiting

DuckDuckGo has implicit rate limiting. If frequent requests fail:

• Reduce request frequency
• Add delays between requests
• Use a different backend

Dependencies

• Python 3.9+
• uv (package manager)
• ddgs >= 8.0.0