Skill: yangsjt/deep-research-cli (version 0.1.0)

--- name: deep-research description: 深度多步网页研究。迭代搜索、页面抓取、综合分析，生成带引用的 Markdown 报告。触发词：deep search、deep research、深度搜索、深度研究、深度思考、深度学习、comprehensive research。 --- You are an expert research analyst. Follow the methodology below using your platform's available search and fetch tools (see [Tool Mapping](#tool-mapping)). ## Research Methodology ### Step 1: Problem Decomposition Break the user's query into 3-5 distinct sub-questions that collectively cover the topic: - Identify the core question and its key dimensions - Consider temporal aspects (historical context, current state, future outlook) - Include comparative or contrasting perspectives where relevant - Note any implicit assumptions that need verification Think through this step carefully before proceeding. List the sub-questions explicitly. ### Step 2: Breadth-First Search For each sub-question, perform 2-3 diverse search queries using the available web search tool (see [Tool Mapping](#tool-mapping)): - Use varied phrasings and angles for each sub-question - Include both broad and specific search terms - Search in the language most likely to yield quality results for the topic - Target a total of 8-15 searches across all sub-questions - Log each search query and briefly note what useful results appeared ### Step 3: Deep Reading Select 5-10 of the most valuable pages from search results and fetch their full content using the available page fetch tool (see [Tool Mapping](#tool-mapping)): - Prioritize primary sources, official documentation, peer-reviewed content - Include diverse source types (academic, industry, news, official) - Read each page thoroughly and extract key facts, data points, and quotes - Note the publication date and author credibility for each source ### Step 4: Gap Analysis After initial research, critically evaluate what's missing: - Identify sub-questions that remain unanswered or weakly supported - Note contradictions between sources that need resolution - Find claims that lack sufficient evidence - Perform 2-3 additional targeted searches to fill gaps - Fetch 2-3 more pages if needed for gap-filling ### Step 5: Synthesis & Report Compile findings into a structured Markdown report following this template: ```markdown # [Research Topic] _Generated: [YYYY-MM-DD] | Sources consulted: [N] pages_ ## Executive Summary [2-3 paragraph overview of the most important findings. Should stand alone as a complete briefing.] ## Key Findings ### [Sub-topic 1] [Detailed findings with inline citations as numbered references, e.g., [1], [2]] ### [Sub-topic 2] [...] ### [Sub-topic N] [...] ## Detailed Analysis [Deeper exploration of complex aspects, cross-cutting themes, and nuanced points that don't fit neatly into sub-topic sections] ## Contradictions & Limitations - [Conflicting information found between sources] - [Areas where evidence is thin or outdated] - [Potential biases in available sources] - [Questions that remain unanswered] ## Sources 1. [Title](URL) — [Brief description of the source and what it contributed] 2. [Title](URL) — [...] ... ``` ### Step 6: Quality Check Before delivering the report, verify: - [ ] Every factual claim has at least one source citation - [ ] Sources are diverse (not all from the same domain/author) - [ ] Executive summary accurately reflects the detailed findings - [ ] Contradictions and limitations are honestly disclosed - [ ] The report directly answers the user's original question - [ ] Numbers, dates, and proper nouns are accurately transcribed from sources ## Output Language Match the language of the user's prompt: - If the user writes in Chinese, output the report in Chinese (with English terms where conventional) - If the user writes in English, output the report in English - For mixed-language prompts, default to the language used for the main question ## Tool Mapping This skill uses generic descriptions for web tools. Map to your platform: | Action | Gemini CLI | Claude Code | Generic | |--------|-----------|-------------|---------| | Web search | `google_web_search` | `WebSearch` | Any available search tool | | Fetch page | `web_fetch` | `WebFetch` | Any available URL fetch tool | | Fetch page (fallback) | N/A | `https://r.jina.ai/<url>` | Prepend `https://r.jina.ai/` to any URL | > **SearXNG fallback**: If your platform has no built-in search tool, you can self-host [SearXNG](https://github.com/searxng/searxng) as a local search backend: > ```bash > docker run -d -p 8080:8080 searxng/searxng > ``` > Search: `curl -s "http://localhost:8080/search?q=<url-encoded-query>&format=json"` (returns `results[]` with `title`, `url`, `content`) > Fetch: Prepend `https://r.jina.ai/` to any URL. ## Important Guidelines 1. **Use your platform's native search/fetch tools for research.** Do NOT use a `browser` tool. If no search/fetch tool is available, inform the user — never launch a browser. 2. **Do NOT ask for API keys.** Gemini CLI uses OAuth authentication. If search/fetch tools are unavailable, instruct the user to run `gemini login` to authenticate via OAuth. No separate API key is needed. 3. **Do NOT fabricate sources or citations** — every URL must come from actual search results. - Be thorough but honest — clearly state when information is uncertain or unavailable - Prefer recent sources over older ones when both exist - Include specific data points, numbers, and dates whenever available - Distinguish between facts, expert opinions, and speculation

path: README.md
content: # Deep Research

An [OpenClaw](https://github.com/anthropics/openclaw) skill for deep research — produces comprehensive, well-sourced Markdown reports. Works with any AI platform: [Gemini CLI](https://github.com/google-gemini/gemini-cli), Claude Code, or any tool that supports SKILL.md-style prompts.

## Architecture

```mermaid
flowchart LR
    Q[Query] --> D[Decompose<br/>3-5 sub-questions]
    D --> B[Breadth Search<br/>8-15 web searches]
    B --> R[Deep Read<br/>5-10 full pages]
    R --> G[Gap Analysis<br/>2-3 follow-ups]
    G --> S[Synthesize<br/>structured report]
    S --> C[Quality Check<br/>citations & accuracy]
    C --> report[Markdown Report]

    style Q fill:#4a9eff,color:#fff
    style report fill:#34d399,color:#fff
```

**Tool mapping** — the skill adapts to whatever tools are available:

| Step | Gemini CLI | Claude Code | Generic |
|------|-----------|-------------|---------|
| Web search | `google_web_search` | `WebSearch` | any search tool |
| Page fetch | `web_fetch` | `WebFetch` | any fetch tool |

## Quick Start

**Option A: Gemini CLI Skill**
```bash
git clone https://github.com/yangsjt/deep-research.git ~/projects/deep-research
gemini skills link ~/projects/deep-research
```

**Option B: Standalone Script**
```bash
git clone https://github.com/yangsjt/deep-research.git ~/projects/deep-research
./scripts/search.sh -p "Latest developments in RISC-V 2026"
```

**Option C: Any AI Platform** — Copy `SKILL.md` into your AI's prompt or skill config. The methodology is self-contained; it only requires web search and page fetch capabilities.

> **Note:** Gemini CLI requires [Google AI Premium](https://one.google.com/explore-plan/gemini-advanced) and OAuth auth (`gemini login`). No separate API keys needed.

## Usage

### Script

```bash
./scripts/search.sh -p "AI Agent frameworks comparison 2026"
./scripts/search.sh -p "WebAssembly component model" -n "wasm" --background
./scripts/search.sh --help   # all options
```

### Interactive (Skill Mode)

Trigger with any of these phrases in your AI assistant:

> `deep search` · `deep research` · `深度研究` · `深度思考` · `深度学习` · `comprehensive research`

```
$ gemini
> deep search: State of RISC-V in consumer electronics
```

## License

[MIT](LICENSE)


path: references/research-methodology.md
content: # Research Methodology Reference

This document outlines the research methodology principles that underpin the deep search skill.

## Problem Decomposition

Effective research starts with breaking a complex question into manageable sub-questions:

- **MECE Principle**: Sub-questions should be Mutually Exclusive, Collectively Exhaustive
- **Dimensional Analysis**: Consider the topic from multiple dimensions:
  - Technical / Implementation
  - Economic / Market
  - Social / User impact
  - Temporal (past, present, future)
  - Comparative (alternatives, competitors)
- **Assumption Surfacing**: Identify and list implicit assumptions in the original question

## Query Optimization

Search queries should be crafted strategically:

- **Specificity Ladder**: Start broad, then narrow based on initial results
- **Synonym Variation**: Use different terms for the same concept across queries
- **Boolean Logic**: Combine terms to filter noise (e.g., "RISC-V laptop -Arduino")
- **Source Targeting**: Add site-specific terms when authoritative sources are known
- **Temporal Filtering**: Include year or date ranges for time-sensitive topics
- **Language Switching**: Search in the language most likely to have expert content

## Source Evaluation (CRAAP Test)

Evaluate each source against these criteria:

| Criterion | Questions to Ask |
|-----------|-----------------|
| **Currency** | When was it published? Is the information current for the topic? |
| **Relevance** | Does it directly address the research question? |
| **Authority** | Who is the author? What are their credentials? |
| **Accuracy** | Can claims be verified? Are sources cited? |
| **Purpose** | Is the content informational, commercial, or opinion? |

### Source Hierarchy (strongest to weakest)

1. Peer-reviewed research / official documentation
2. Government / institutional reports
3. Industry analysis from established firms
4. Quality journalism (named reporters, fact-checked outlets)
5. Expert blog posts / conference talks
6. Community forums / social media (use for signals, not facts)

## Synthesis Techniques

### Triangulation

- Verify key claims across 3+ independent sources
- Note when only a single source supports a claim
- Flag contradictions explicitly rather than silently choosing one version

### Chronological Threading

- Trace how information has evolved over time
- Note when "facts" from older sources have been superseded
- Identify emerging trends vs established consensus

### Confidence Levels

Apply confidence ratings to findings:

| Level | Meaning | Source Requirement |
|-------|---------|-------------------|
| **High** | Well-established, widely confirmed | 3+ independent authoritative sources |
| **Medium** | Likely accurate, some uncertainty | 1-2 authoritative sources |
| **Low** | Preliminary, unconfirmed | Single source or expert opinion only |
| **Speculative** | Reasonable inference, no direct evidence | Analyst interpretation |

## Common Pitfalls

- **Confirmation Bias**: Searching only for evidence that supports a hypothesis
- **Recency Bias**: Overweighting the latest news vs established fundamentals
- **Authority Bias**: Accepting claims from "experts" without verification
- **Survivorship Bias**: Focusing on successful cases while ignoring failures
- **Translation Errors**: Misinterpreting content in a non-native language


path: scripts/search.sh
content: #!/usr/bin/env bash
set -euo pipefail

# Deep Research — CLI entry point
# Usage: ./search.sh -p "your research question" [options]

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
SKILL_FILE="$PROJECT_DIR/SKILL.md"

# Defaults
PROMPT=""
TASK_NAME=""
OUTPUT_DIR="$HOME/gemini-research"
MODEL="gemini-2.5-pro"
TIMEOUT=600
BACKGROUND=false
NOTIFY="auto"

# Colors
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[0;33m'
BLUE='\033[0;34m'
NC='\033[0m'

usage() {
    cat <<'USAGE'
Deep Research — Iterative multi-step web research via Gemini CLI

Usage:
  search.sh -p "research question" [options]

Required:
  -p, --prompt        Research question or topic

Options:
  -n, --task-name     Task name (default: timestamp)
  -o, --output-dir    Output directory (default: ~/gemini-research/)
  -m, --model         Gemini model (default: gemini-2.5-pro)
      --timeout       Timeout in seconds (default: 600)
  -b, --background    Run in background
      --notify        Notification: auto | none (default: auto)
  -h, --help          Show this help

Examples:
  search.sh -p "Latest developments in RISC-V consumer products 2026"
  search.sh -p "AI Agent 框架现状分析" -n "ai-agents" --background
  search.sh -p "Compare React vs Vue vs Svelte" -m gemini-2.5-flash
USAGE
    exit 0
}

log_info()  { echo -e "${BLUE}[INFO]${NC} $*"; }
log_ok()    { echo -e "${GREEN}[OK]${NC} $*"; }
log_warn()  { echo -e "${YELLOW}[WARN]${NC} $*"; }
log_error() { echo -e "${RED}[ERROR]${NC} $*" >&2; }

# Parse arguments
while [[ $# -gt 0 ]]; do
    case "$1" in
        -p|--prompt)     PROMPT="$2";     shift 2 ;;
        -n|--task-name)  TASK_NAME="$2";  shift 2 ;;
        -o|--output-dir) OUTPUT_DIR="$2"; shift 2 ;;
        -m|--model)      MODEL="$2";      shift 2 ;;
        --timeout)       TIMEOUT="$2";    shift 2 ;;
        -b|--background) BACKGROUND=true; shift ;;
        --notify)        NOTIFY="$2";     shift 2 ;;
        -h|--help)       usage ;;
        *)
            log_error "Unknown option: $1"
            usage
            ;;
    esac
done

# Validate required args
if [[ -z "$PROMPT" ]]; then
    log_error "Missing required argument: --prompt / -p"
    usage
fi

# Validate gemini CLI
if ! command -v gemini &>/dev/null; then
    log_error "gemini CLI not found in PATH"
    echo "Install: https://github.com/google-gemini/gemini-cli"
    exit 1
fi

# Validate SKILL.md exists
if [[ ! -f "$SKILL_FILE" ]]; then
    log_error "SKILL.md not found at $SKILL_FILE"
    exit 1
fi

# Generate task name if not provided
TIMESTAMP="$(date +%Y%m%d_%H%M%S)"
if [[ -z "$TASK_NAME" ]]; then
    TASK_NAME="research_${TIMESTAMP}"
else
    TASK_NAME="${TASK_NAME}_${TIMESTAMP}"
fi

# Create output directory
mkdir -p "$OUTPUT_DIR"

OUTPUT_FILE="$OUTPUT_DIR/${TASK_NAME}.md"
PID_FILE="$OUTPUT_DIR/${TASK_NAME}.pid"

# Extract SKILL.md body: skip YAML front matter (everything between the two --- lines)
SKILL_BODY="$(awk '/^---$/{n++; next} n>=2' "$SKILL_FILE")"

# Build the full prompt
FULL_PROMPT="$(cat <<PROMPT_EOF
${SKILL_BODY}

---

## Research Task

${PROMPT}

Please execute the 6-step research methodology above and produce the full report.
PROMPT_EOF
)"

# Notification function
send_notification() {
    local title="$1"
    local message="$2"

    case "$NOTIFY" in
        none)
            return 0
            ;;
        auto|*)
            send_system_notification "$title" "$message"
            ;;
    esac
}

send_system_notification() {
    local title="$1"
    local message="$2"

    case "$(uname -s)" in
        Darwin)
            osascript -e "display notification \"$message\" with title \"$title\"" 2>/dev/null || true
            ;;
        Linux)
            if command -v notify-send &>/dev/null; then
                notify-send "$title" "$message" 2>/dev/null || true
            fi
            ;;
    esac
}

# Run the research
run_research() {
    log_info "Starting deep search: $TASK_NAME"
    log_info "Model: $MODEL"
    log_info "Output: $OUTPUT_FILE"
    log_info "Timeout: ${TIMEOUT}s"
    echo ""

    local start_time
    start_time="$(date +%s)"

    if timeout "$TIMEOUT" gemini "$FULL_PROMPT" \
        --approval-mode yolo \
        -m "$MODEL" \
        --output-format text \
        2>/dev/null | tee "$OUTPUT_FILE"; then

        local end_time duration
        end_time="$(date +%s)"
        duration=$(( end_time - start_time ))

        log_ok "Research complete in ${duration}s"
        log_ok "Report saved to: $OUTPUT_FILE"

        send_notification \
            "Deep Research" \
            "Research complete: ${TASK_NAME} (${duration}s)"
    else
        local exit_code=$?
        if [[ $exit_code -eq 124 ]]; then
            log_error "Research timed out after ${TIMEOUT}s"
            send_notification \
                "Deep Research" \
                "Research timed out: ${TASK_NAME}"
        else
            log_error "Research failed with exit code $exit_code"
            send_notification \
                "Deep Research" \
                "Research failed: ${TASK_NAME}"
        fi
        return $exit_code
    fi
}

# Execute
if [[ "$BACKGROUND" == true ]]; then
    log_info "Running in background..."
    nohup bash -c "$(declare -f run_research send_notification send_system_notification log_info log_ok log_warn log_error); \
        TASK_NAME='$TASK_NAME' MODEL='$MODEL' OUTPUT_FILE='$OUTPUT_FILE' TIMEOUT='$TIMEOUT' \
        NOTIFY='$NOTIFY' \
        FULL_PROMPT=$(printf '%q' "$FULL_PROMPT") \
        RED='$RED' GREEN='$GREEN' YELLOW='$YELLOW' BLUE='$BLUE' NC='$NC' \
        run_research" \
        > "$OUTPUT_DIR/${TASK_NAME}.log" 2>&1 &
    BG_PID=$!
    echo "$BG_PID" > "$PID_FILE"
    log_ok "Background PID: $BG_PID"
    log_ok "PID file: $PID_FILE"
    log_ok "Log file: $OUTPUT_DIR/${TASK_NAME}.log"
else
    run_research
fi


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)