How to Add Web Search to an Agent Skill With the You.com Web Search API

TLDR: An agent skill is a folder with a SKILL.md file and optional scripts that any compatible agent can load. Web search makes skills useful for anything current. This guide shows the SKILL.md frontmatter, a Python script that calls the You.com Web Search API, the decision rules for when a skill should search, and the failure modes that break skills in practice.

Agent skills are the newest portability layer in the agent ecosystem. A skill is a folder containing a SKILL.md file with a name, a description, and instructions, and it can bundle scripts, templates, and reference files. Agents load skills through progressive disclosure: they read only the name and description at startup, pull the full instructions when a task matches, and run the bundled code only when needed. The pattern is documented at agentskills.io and in Anthropic's engineering writeup, and clients from Claude Code to OpenClaw now support it. The one thing most skills cannot do out of the box is know what happened after the agent's training cutoff, which is where You.com comes in: a skill script that calls the Web Search API gives the agent live web results on demand.

What Should a Web Search Skill Contain?

A web search skill needs three parts: a SKILL.md that tells the agent when searching is worth doing, a script that performs the search, and a short contract for what the script returns. The skill folder looks like this.

web-search-skill/
  SKILL.md
  scripts/
    search.py

Keep the skill small. Skills are loaded on demand, but the instructions still occupy the agent's context once activated, and a bloated SKILL.md pushes real task context out. One skill, one job.

What Does the SKILL.md Look Like?

The SKILL.md file has YAML frontmatter with the metadata agents read at startup, followed by instructions the agent reads on activation.

---
name: web-search
description: Search the live web for current information using the You.com Web Search API. Use when a task needs facts, versions, prices, news, or anything that changes over time. Do not use for stable knowledge the agent already has.
---

# Web Search

Run scripts/search.py with a single query string argument.
It prints JSON with url, title, and description for each result.

Search when:
- The task names a version, date, or price
- The task mentions a product, library, or company
- The user asks "latest", "current", or "today"

Do not search when:
- The answer is a stable fact
- The task is pure code editing
- You already searched this exact query in this session

The description field does most of the work. Agents decide whether to activate a skill from the description alone, so it must say both when to use the skill and when not to. A description that only says what the skill does invites the agent to search on every turn, which wastes time and context.

How Does the Search Script Call the API?

The script is a thin, defensive wrapper around one documented endpoint.

#!/usr/bin/env python3
import json, os, sys, urllib.request

def search(query: str, count: int = 5) -> list:
    url = "https://ydc-index.io/v1/search"
    payload = json.dumps({"query": query, "count": count}).encode()
    req = urllib.request.Request(
        url,
        data=payload,
        headers={
            "X-API-Key": os.environ["YDC_API_KEY"],
            "Content-Type": "application/json",
        },
        method="POST",
    )
    try:
        with urllib.request.urlopen(req, timeout=15) as resp:
            data = json.loads(resp.read().decode())
    except urllib.error.HTTPError as e:
        return [{"error": f"search failed with HTTP {e.code}"}]
    except urllib.error.URLError as e:
        return [{"error": f"search unreachable: {e.reason}"}]
    return data.get("results", {}).get("web", [])

if __name__ == "__main__":
    if len(sys.argv) < 2:
        print(json.dumps({"error": "usage: search.py QUERY"}))
        sys.exit(1)
    print(json.dumps(search(sys.argv[1]), indent=2))

Three choices matter here. The API key is read from an environment variable, never hardcoded, because skill folders get shared, copied into repositories, and zipped across teams. Errors are returned as structured JSON instead of raised exceptions, because an agent that sees an error object can tell the user the search failed, while an agent hit by a stack trace just breaks. The result count defaults to five, because a skill that returns twenty results per search spends the agent's context faster than the task earns it back. The Web Search API guide documents every parameter this script can pass, including freshness windows and domain filters.

When Should the Skill Search Instead of Answering From Memory?

Give the agent explicit rules, because agents default to answering. A practical split:

Search: anything versioned, priced, dated, or announced. Library releases, API changes, current events, competitor pages.
Do not search: stable facts, language syntax, math, and anything the agent just searched or read from a file in the same session.

The strongest signal that a skill needs this rule: the agent re-searches the same query mid-task. Track queries in the session and instruct the agent to reuse earlier results, or add a cheap cache keyed on the query string inside the script.

What Breaks Web Search Skills in Practice?

Hardcoded keys. A key pasted into the script ships with the folder on the first share. Detection: grep the skill folder for the key prefix before every commit, and rotate the key if it ever landed in a repository.

Silent failures. A script that swallows exceptions and prints an empty array teaches the agent that nothing exists on the topic. Detection: return the error object, as above, and count error responses per day as a health metric.

Stale instructions. The SKILL.md tells the agent to run a script or call an endpoint that has since changed. Detection: include a one-line changelog at the top of the SKILL.md and re-test the skill on every agent client upgrade.

Context flooding. Full search responses are large, and an agent that reads them raw loses task context. Detection: watch the agent's context usage on multi-search tasks, and cap both the result count and the fields the script prints.

How Do You Test and Distribute the Skill?

Test the skill the way agents will use it: from outside the folder, with a fresh environment, and with the key provided only through the environment variable. The three checks worth automating:

The dry run: execute scripts/search.py with one query and confirm the JSON prints with url, title, and description fields present. This catches endpoint and key problems before an agent ever loads the skill.
The error run: unset the key and run again. The script must print the structured error, not a stack trace, because agents on other machines will hit this path first.
The activation test: in your agent client of choice, give a task that matches the description, such as "check the latest version of this library," and confirm the agent activates the skill and reuses results instead of re-searching.

For distribution, keep the skill in version control with a README that names the required environment variable and nothing secret. A skill folder that needs no key to distribute and no installer to run is the one that actually gets adopted by other teams.

Related Guides

FAQ

Where do skill scripts actually run? In the environment of the agent host that activates the skill. The script is a normal executable on that machine, so environment variables, network access, and installed runtimes come from the host. A skill that assumes a dependency should check for it and fail with a readable message.

Do skills work across different agent clients? The SKILL.md format is an open pattern supported by a growing list of clients, including Claude Code, Codex, OpenCode, and others listed on the agentskills.io client showcase. Scripts are ordinary executables, so portability depends on keeping the script dependency-light, which the Python standard library example above does deliberately.

How do I keep the API key out of the skill? Read it from an environment variable in the script, never from a file inside the skill folder. Distribute the skill without a key, and let each user provide their own through their environment. This also lets different hosts use different keys with the same skill.

Should the skill print results or let the agent open URLs? Print results. The agent cannot assume it has a browser, and search snippets answer most skill-level questions. If a task needs full page content, pair this skill with a content extraction step, or use the extraction options documented in the Web Search API guide.

LI Test
LI Test

Related resources.

No items found.