you-web-search

Files (1)

• SKILL.md

SKILL.md (first lines)

> **${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
- **Works with zero configuration** — no key, wallet, or sign-up needed for the keyless tier
- **Real-time web crawling** for fresh content when `livecrawl=web` is enabled (keyed tier)
- **Structured result format** with titles, URLs, snippets, and publication dates
- **Optional livecrawl control** through `YOUCOM_LIVECRAWL` when a full page fetch is useful

### Auth modes

| Mode | When | Endpoint | Limits |
| --- | --- | --- | --- |
| `keyless` | `YDC_API_KEY` unset | `https://api.you.com/v1/agents/search` | 100 searches/day per IP, no livecrawl |
| `keyed` | `YDC_API_KEY` set | `https://api.you.com/v1/search` | Your plan's limits, livecrawl available |

## Phase 1 — Execute Search

### Auth Mode

Check whether the key is set via `${VAR:+x}` — a bare `$YDC_API_KEY` trips the secret-expansion analyzer:
```bash
if [ -n "${YDC_API_KEY:+x}" ]; then AUTH_MODE="keyed"; else AUTH_MODE="keyless"; fi
echo "youcom auth_mode=$AUTH_MODE"
```

A missing key is **not** an error — the skill runs on the keyless tier.

### API Call

Both modes call the same REST contract through `./secretcurl`. In `keyed` mode the `{YDC_API_KEY}` placeholder is substituted inside the helper; in `keyless` mode no key header is sent at all.

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

FRESHNESS="${YOUCOM_FRESHNESS:-week}"
LIVECRAWL="${YOUCOM_LIVECRAWL:-}"
PARAMS="query=$(echo "$QUERY" | jq -Rr @uri)&count=$COUNT&safesearch=strict&freshness=$(echo "$FRESHNESS" | jq -Rr @uri)"

if [ "$AUTH_MODE" = "keyed" ]; then
  SEARCH_URL="https://api.you.com/v1/search?$PARAMS"
  # livecrawl is a keyed-tier feature; the keyless endpoint answers it with 402.
  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")
else
  SEARCH_URL="https://api.you.com/v1/agents/search?$PARAMS"
  [ -n "${LIVECRAWL:+x}" ] && echo "youcom livecrawl=skipped reason=keyless (set YDC_API_KEY to enable)"
  HTTP=$(./secretcurl -s -o /tmp/youcom-search.json -w '%{http_code}' \
    --max-time 30 -X GET \
    "$SEARCH_URL" \
    -H "User-Agent: youdotcom-integration/aeonfun-aeon")
fi

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

Never send the key to the keyless endpoint, and never call the keyed endpoint without a key (it answers with a `402` payment challenge rather than results).

### Response Processing

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

```bash
if [ "$HTTP" = "200" ] && [ -s /tmp/youcom-search.json ]; then
  # Extract web and news results using the documented Search API shape.
  if 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; then
    PARSE_OK=1
  else
    PARSE_OK=0
    : > /tmp/youcom-results.txt
  fi
  
  # Count results
  RESULT_COUNT=$(wc -l < /tmp/youcom-results.txt)
  echo "Extracted $RESULT_COUNT search results"
else
  PARSE_OK=1
  RESULT_COUNT=0
fi

# Any non-200 (or a 200 with nothing usable) hands the run to the built-in WebSearch.
if [ "$RESULT_COUNT" -eq 0 ]; then
  case "$HTTP" in
    200) if [ "$PARSE_OK" = "1" ]; then REASON="EMPTY"; else REASON="PARSE"; fi ;;
    000) REASON="NETWORK" ;;
    *)   REASON="HTTP_$HTTP" ;;
  esac
  SOURCE_PATH="websearch"
  echo "youcom fallback=websearch reason=$REASON auth_mode=$AUTH_MODE"
else
  SOURCE_PATH="youcom"
fi
```

### WebSearch Fallback

When `SOURCE_PATH=websearch`, don't end the run empty. Run the same query (`$QUERY`) through the built-in **WebSearch** tool and continue to Phase 2 with those results. The log line above is the record of why:

```
youcom fallback=websearch reason=HTTP_401 auth_mode=keyless
```

From aeonfun/aeon, MIT.

More from aeonfun/aeon