You Web Search

---
name: you-web-search
description: Web search using You.com Search API with high-quality, cited results — runs keyless out of the box; YDC_API_KEY unlocks higher limits and real-time web crawling
metadata:
  title: You.com Web Search
  mode: read-only
  category: basics
  var: ""
  tags:
    - web
    - search
    - research
  requires:
    - YDC_API_KEY?
---

> **${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

Key check: read the "Keys set for this run" line in your run notes, never a shell test (those are refused and cost a turn). `YDC_API_KEY` on that line = AUTH_MODE `keyed`, not on it = `keyless`. Read the two optional settings with one call:
```bash
node -e 'console.log("freshness=" + (process.env.YOUCOM_FRESHNESS || "week") + " livecrawl=" + (process.env.YOUCOM_LIVECRAWL || ""))'
```
It prints FRESHNESS (default `week`) and LIVECRAWL (empty when unset).

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.

`QUERY` = `${var}`, or `current notable developments in AI, crypto, and technology` when it is empty. `COUNT` = `10`. Make exactly one call for the AUTH_MODE you got, with QUERY, FRESHNESS and LIVECRAWL written in literally (`--data-urlencode` does the URL encoding).

**`keyed`** (livecrawl is a keyed-tier feature; the keyless endpoint answers it with 402). Add the `livecrawl` line only when LIVECRAWL is non-empty:
```bash
./secretcurl -s -o /tmp/youcom-search.json -w 'youcom http=%{http_code} auth_mode=keyed bytes=%{size_download}\n' \
  --max-time 30 -G "https://api.you.com/v1/search" \
  --data-urlencode "query=<QUERY>" --data-urlencode "count=10" --data-urlencode "safesearch=strict" --data-urlencode "freshness=<FRESHNESS>" \
  --data-urlencode "livecrawl=<LIVECRAWL>" \
  -H "X-API-Key: {YDC_API_KEY}" \
  -H "User-Agent: youdotcom-integration/aeonfun-aeon"
```

**`keyless`**. If LIVECRAWL is non-empty, first record that it is skipped:
```bash
echo "youcom livecrawl=skipped reason=keyless (set YDC_API_KEY to enable)"
```
Then:
```bash
./secretcurl -s -o /tmp/youcom-search.json -w 'youcom http=%{http_code} auth_mode=keyless bytes=%{size_download}\n' \
  --max-time 30 -G "https://api.you.com/v1/agents/search" \
  --data-urlencode "query=<QUERY>" --data-urlencode "count=10" --data-urlencode "safesearch=strict" --data-urlencode "freshness=<FRESHNESS>" \
  -H "User-Agent: youdotcom-integration/aeonfun-aeon"
```

The `-w` label prints HTTP (`000` on a network failure) and the body size.

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 a non-empty body (`bytes` above 0), extract web and news results using the documented Search API shape, one call:

```bash
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
```

`RESULT_COUNT` = the number of rows it printed (state `Extracted <N> search results`). If `jq` failed, the parse failed and `RESULT_COUNT` = 0. On any other HTTP, `RESULT_COUNT` = 0.

Then decide (in prose, no `if`/`case` block). Any non-200, or a 200 with nothing usable, hands the run to the built-in WebSearch:
- `RESULT_COUNT` above 0: `SOURCE_PATH=youcom`.
- `RESULT_COUNT` = 0: `SOURCE_PATH=websearch`, with `REASON` = `EMPTY` (HTTP 200, parse OK), `PARSE` (HTTP 200, `jq` failed), `NETWORK` (HTTP `000`), else `HTTP_<code>`. Record it with one call, values written in literally:
  ```bash
  echo "youcom fallback=websearch reason=<REASON> auth_mode=<AUTH_MODE>"
  ```

### 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
```

Typical triggers are a keyless `401` (see [Error Handling](#error-handling)), the keyless `429` daily cap (shared GitHub Actions runner IPs can hit it even on light usage), `5xx`, a network timeout (`reason=NETWORK`), an unparseable body (`reason=PARSE`), or zero results (`reason=EMPTY`). Only fall back once per run. If WebSearch also returns nothing, report that neither source returned results.

## 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: ${source}
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
```

`${source}` is exactly one of `You.com Search API (${auth_mode})` or `WebSearch (fallback: ${reason})`, matching `SOURCE_PATH`. Never print both.

## 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 the auth mode actually used (`keyless` or `keyed`)
- When the fallback ran, say so and give the reason (e.g. "via WebSearch — You.com returned HTTP 401")
- Include livecrawl info when enabled (or that it was skipped on the keyless tier)

### Memory Integration  

Log the search for future reference:

1. **Log record** - this skill is `read-only`, so the workflow's read-only guard writes its `### you-web-search` log entry from your captured output; a self-written entry would be a duplicate. Don't append to `memory/logs/` yourself - put this record in your **final output**:
   ```
   ### you-web-search
   - Query: "${var}"
   - Source: ${source}
   - 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 (append with a one-line `node -e` writer, e.g. `node -e 'require("fs").appendFileSync("memory/searches.md", process.argv[1] + "\n")' "<line>"`)

## Error Handling

### API Failure Recovery

Every failure below ends in the [WebSearch fallback](#websearch-fallback), so a run always has results. The notes say what to tell the operator:

- **Keyless 401**: In `keyless` mode no key is sent, so a `401` is **not** a credential problem. Some locations currently get `401` from the keyless endpoint with a body like `{"detail":"'ascii' codec can't encode characters ..."}`. This is a known server-side issue with non-ASCII region names (e.g. `Île-de-France`), and `country`/`language` parameters don't avoid it. Fall back and log `reason=HTTP_401`. Setting `YDC_API_KEY` uses the keyed endpoint, which is unaffected
- **Rate limits (429)**: Log rate limit hit. In `keyless` mode this is usually the 100/day per-IP cap — suggest setting `YDC_API_KEY` (get one at https://you.com/platform?utm_source=aeonfun-aeon&utm_medium=oss_integration&utm_campaign=2026-09-oss-integrations&utm_content=error-message). In `keyed` mode, suggest checking the plan quota
- **Payment required (402)**: The request needs the keyed tier (e.g. livecrawl without a key) — suggest setting `YDC_API_KEY`
- **Invalid key (401/403, keyed mode)**: Clear error about checking `YDC_API_KEY`
- **Server errors (5xx)**: Transient. Fall back and log `reason=HTTP_<code>` (e.g. `HTTP_503`)
- **Network failures**: Fall back and log `reason=NETWORK`
- **Malformed responses**: A `200` whose body `jq` can't parse. Fall back and log `reason=PARSE`
- **Empty results**: A `200` with zero results. Fall back and log `reason=EMPTY`. If WebSearch is also empty, suggest query refinement or broader terms

### Logging Failures  

Record failure reasons for debugging:
- `youcom-api-unavailable` — API endpoint unreachable
- `youcom-rate-limited` — Hit plan limits or the keyless daily cap
- `youcom-payment-required` — Keyed-tier feature requested without a key
- `youcom-auth-invalid` — API key rejected (keyed mode)
- `youcom-keyless-401` — Keyless endpoint returned 401 with no key sent
- `youcom-parse-error` — Response format unexpected

## Network

Both modes go through `./secretcurl` so one code path covers them: keyed calls carry the `{YDC_API_KEY}` placeholder (never a bare `$YDC_API_KEY` on the line); keyless calls carry no placeholder and are passed through unchanged. Every request sends `User-Agent: youdotcom-integration/aeonfun-aeon`.

**Shell shape.** Each Bash call is one allowed command (pipes are fine). The run refuses a call that sets a variable (`X=$(...)`), uses `if` / `case` / `[ ... ] &&` tests, contains `$(...)`, or joins commands with `;`, `&&` or `||`, and each refusal costs a model turn. So the key check reads the run notes' "Keys set for this run" line instead of a shell test, the settings check is a `node -e` one-liner, the search is one `./secretcurl` call per auth mode with every value written in literally (`--data-urlencode` instead of `jq @uri`), the `-w` label replaces the `echo ... $(wc -c ...)` line, and the fallback decision is a prose step. This skill is read-only: any file it keeps (such as `memory/searches.md`) is written with a one-line `node -e` writer, never `>` or `>>`.

## Environment Variables

- **`YDC_API_KEY`** (optional) — You.com API key. Unset: the skill runs on the free keyless tier (100 searches/day per IP, no livecrawl). Set: keyed Search API with your plan's limits and livecrawl. Get a key at https://you.com/platform?utm_source=aeonfun-aeon&utm_medium=oss_integration&utm_campaign=2026-09-oss-integrations&utm_content=docs.
- **`YOUCOM_FRESHNESS`** (optional) — Freshness filter (`day`, `week`, `month`, `year`, or a date range).
- **`YOUCOM_LIVECRAWL`** (optional, keyed only) — Pass through to `livecrawl` when you want full page content (`web`, `news`, or `all`). Ignored on the keyless tier.

## 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
- **Never end a run empty** — on any You.com failure, fall back to WebSearch and log `youcom fallback=websearch reason=<REASON>`
- **Report the path honestly** — say whether results came from You.com or the WebSearch fallback, never present fallback results as You.com results

## Integration Notes  

### Relationship to Built-in WebSearch

This skill **complements** Aeon's built-in WebSearch, but it is a separate Search API path (keyless by default, keyed when `YDC_API_KEY` is set):

- **You.com advantages**: Higher quality results, real-time crawling, better relevance ranking
- **WebSearch advantages**: No API dependency, always available, deeply integrated. It is also this skill's fallback whenever the You.com call fails
- **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 — the keyless tier is capped at 100 searches/day per IP

### 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.