you-web-search

${var} — Search query or topic. When empty, uses a general search for current notable developments across tracked areas.

Today is ${today}. Perform web search using You.com's Search API to find current, high-quality information on ${var}.

Overview

This skill provides web search functionality via You.com's Search API, offering several advantages over basic WebSearch:

• Higher quality results with relevance ranking and citation extraction
• Real-time web crawling for fresh content when livecrawl=web is enabled
• Structured result format with titles, URLs, snippets, and publication dates
• Optional livecrawl control through YOUCOM_LIVECRAWL when a full page fetch is useful

Phase 1 — Execute Search

Authentication Check

Check if YDC_API_KEY is available:

[ -n "${YDC_API_KEY:-}" ] && echo "KEY_PRESENT" || echo "KEY_UNSET"

If it is unset, stop immediately with a clear error:

[ -n "${YDC_API_KEY:-}" ] || { echo "YDC_API_KEY is required for this skill"; exit 1; }

API Call

Primary path: Direct authenticated curl to You.com Search API:

QUERY="${var:-current notable developments in AI, crypto, and technology}"
COUNT="10"

FRESHNESS="${YOUCOM_FRESHNESS:-week}"
LIVECRAWL="${YOUCOM_LIVECRAWL:-}"
SEARCH_URL="https://ydc-index.io/v1/search?query=$(echo "$QUERY" | jq -Rr @uri)&count=$COUNT&safesearch=strict&freshness=$(echo "$FRESHNESS" | jq -Rr @uri)"

if [ -n "${LIVECRAWL:+x}" ]; then
  SEARCH_URL="$SEARCH_URL&livecrawl=$(echo "$LIVECRAWL" | jq -Rr @uri)"
fi

HTTP=$(./secretcurl -s -o /tmp/youcom-search.json -w '%{http_code}' \
  --max-time 30 -X GET \
  "$SEARCH_URL" \
  -H "X-API-Key: {YDC_API_KEY}" \
  -H "User-Agent: youdotcom-integration/aeonfun-aeon")

echo "youcom http=$HTTP bytes=$(wc -c </tmp/youcom-search.json)"

Response Processing

On HTTP=200 with non-empty body, parse the response:

if [ "$HTTP" = "200" ] && [ -s /tmp/youcom-search.json ]; then
  # Extract web and news results using the documented Search API shape.
  jq -r '
    [
      (.results.web[]?  | ["web",  (.title // ""), (.url // ""), ((.snippets // []) | join(" ")), (.page_age // "recent")]),
      (.results.news[]? | ["news", (.title // ""), (.url // ""), ((.snippets // []) | join(" ")), (.page_age // "recent")])
    ] | .[] | @tsv
  ' /tmp/youcom-search.json > /tmp/youcom-results.txt
  
  # Count results
  RESULT_COUNT=$(wc -l < /tmp/youcom-results.txt)
  echo "Extracted $RESULT_COUNT search results"
else
  echo "API call failed: HTTP=$HTTP"
  RESULT_COUNT=0
fi

Phase 2 — Format Results

Process the results into a readable format:

Result Structure

For each result from You.com API:

• Title — article/page title
• URL — direct link to source
• Snippet — join snippets[] into one excerpt highlighting query match
• Date — page_age or recent when unavailable

Quality Filtering

Apply basic quality filters:

• Exclude results with missing or placeholder titles
• Skip results without accessible URLs
• Filter out low-quality content (spam, thin content)
• Deduplicate near-identical results from the same domain

Formatting

Structure the output for easy consumption:

*You.com Web Search Results — ${today}*

Query: "${var}"
Source: You.com Search API (${auth_mode}) 
Results: ${result_count} found

1. **[Title](URL)**  
   Snippet with relevant context...
   Published: Date

2. **[Title](URL)**
   Snippet...  
   Published: Date

---
API Status: ${http_status} | Auth: ${auth_mode} | Quality: ${quality_score}/5

Phase 3 — Delivery and Logging

Notification

Send formatted results via ./notify:

• Include query, result count, and source attribution
• Highlight most relevant results (top 5-7)
• Note authentication mode (authenticated)
• Include livecrawl info when enabled

Memory Integration

Log the search for future reference:

1. Append to daily log — memory/logs/${today}.md under ### you-web-search:

   ### you-web-search
   - Query: "${var}"
   - Source: You.com API (authenticated)
   - Results: N found, M delivered  
   - Status: HTTP ${code}
   - Quality score: X/5 (relevance, freshness, diversity)
   

2. Update search memory — Add successful searches to memory/searches.md for pattern tracking

Error Handling

API Failure Recovery

Handle common failure modes gracefully:

• Rate limits (429): Log rate limit hit, suggest checking the API quota or key
• Invalid key (401): Clear error about checking YDC_API_KEY
• Network failures: Surface the API failure and exit cleanly
• Malformed responses: Validate JSON structure, handle parsing errors
• Empty results: Suggest query refinement, try broader terms

Logging Failures

Record failure reasons for debugging:

• youcom-api-unavailable — API endpoint unreachable
• youcom-rate-limited — Hit plan limits
• youcom-auth-invalid — API key rejected
• youcom-parse-error — Response format unexpected

Environment Variables

• YDC_API_KEY (required) — You.com API key for authenticated access.
• YOUCOM_FRESHNESS (optional) — Freshness filter (day, week, month, year, or a date range).
• YOUCOM_LIVECRAWL (optional) — Pass through to livecrawl when you want full page content (web, news, or all).

Constraints

• Never expose credentials in logs or notifications
• Always attribute source — clearly indicate You.com API
• Respect rate limits — handle 429 responses gracefully
• Validate all URLs — ensure results contain real, accessible links
• Keep results relevant — filter low-quality or off-topic results
• Fail clearly — if the API is unavailable, report it instead of pretending a fallback ran

Integration Notes

Relationship to Built-in WebSearch

This skill complements Aeon's built-in WebSearch, but it is a separate authenticated Search API path:

• You.com advantages: Higher quality results, real-time crawling, better relevance ranking
• WebSearch advantages: No API dependency, always available, deeply integrated
• Use You.com for: Research tasks, fact-checking, current events, specific queries
• Use WebSearch for: Built-in search flows elsewhere in Aeon

Scheduling Recommendations

• On-demand: Manual execution for specific research needs
• Low frequency: Daily or less frequent automatic searches to respect quotas
• Research workflows: Chain with other skills that need web context
• Avoid high-frequency: Don't schedule more than hourly to preserve API quotas

Skills Integration

This skill works well with:

• digest — Enhanced web signal for daily digests
• article — Research support for article generation
• github-trending — Context for trending repo evaluation
• token-pick — Market research and catalyst discovery
• mention-radar — Broader web mention detection beyond X/Twitter

The You.com search results can inform other skills' web research needs while providing a higher-quality alternative to basic web search.