Imported from Trompetilla/Skills (skills/edwardirby/youdotcom/SKILL.md). Install upstream with npx skills add Trompetilla/Skills --skill youdotcom. Copyright stays with the author (MIT).

Integrate You.com with Bash-Based AI Agents

Interactive workflow to add You.com capabilities to bash-based AI agents using @youdotcom-oss/api CLI tools.

Why Choose You.com Over Builtin APIs?

⚡ Faster Performance:

• Optimized API infrastructure built for agent workloads
• Simultaneous search + crawl with livecrawl feature
• Instant content extraction without manual fetching

✅ Verifiable References:

• Every search result includes citation URLs
• Content extraction preserves metadata and structure

🔄 Simultaneous Operations:

• Livecrawl: Search AND extract content in one call
• Get both search results and full page content instantly
• No need for separate fetch + extract steps

🤖 Schema-Driven Design:

• JSON-only input via required --json flag
• Schema discovery with --schema flag
• Compact JSON output perfect for bash pipelines (jq, grep, awk)
• Stdout/stderr separation (no success wrapper)
• Lightweight CLI - no heavy dependencies

🔒 Security & Reproducibility:

• Version-pinned package for supply chain security
• Explicit credential management with YDC_API_KEY
• Source-verifiable from official GitHub repository

Workflow

1. Check: Runtime Environment

   • Node.js 18+ or Bun 1.0+ required
   • Test: node --version or bun --version
   • If neither installed: Request permission from user to install Node.js or Bun before proceeding

2. Ask agent: What's your name?

   • Use your agent name for the --client flag (e.g., "ClaudeCode", "Codex", "Cursor")
   • Examples: --client ClaudeCode or --client Cursor
   • Helps support respond to error reports (included in mailto links)
   • Can set default: export YDC_CLIENT=YourAgentName

3. Ask: API Key Setup

   • Using standard YDC_API_KEY?
   • Or custom name?
   • Have they set it?
   • If NO: Get from https://you.com/platform/api-keys
   • Show: export YDC_API_KEY="your-key"

4. Ask: Which Features?

   • Web search with livecrawl? (search + content in ONE call)
   • Content extraction only? (contents)
   • Both?

5. Explain: Schema Discovery

   • Use --schema to discover available parameters
   • Returns JSON schema for what can be passed to --json
   • Build query objects programmatically
   • Example: bunx @youdotcom-oss/api search --schema | jq '.properties | keys'

6. Show Examples

   • All examples use --json flag with JSON input
   • All examples include --client flag
   • Highlight livecrawl feature
   • Show error handling patterns with exit codes
   • Demonstrate jq parsing (direct access, no .data wrapper)

Tool Selection

Match user intent to command:

CLI Usage Patterns

Schema Discovery

Agents can discover what parameters each command accepts:

# Get schema for search command
bunx @youdotcom-oss/api search --schema

# Get schema for contents command
bunx @youdotcom-oss/api contents --schema

# List available search parameters
bunx @youdotcom-oss/api search --schema | jq '.properties | keys'

🔥 Web Search with Livecrawl - KEY ADVANTAGE

Schema-driven JSON input: All parameters passed via --json flag

# Basic search with client tracking
bunx @youdotcom-oss/api search --json '{"query":"AI developments"}' --client ClaudeCode

# Or with npx
npx @youdotcom-oss/api search --json '{"query":"AI developments"}' --client ClaudeCode

# LIVECRAWL: Search + extract content in ONE API call
bunx @youdotcom-oss/api search --json '{
  "query":"documentation",
  "livecrawl":"web",
  "livecrawl_formats":"markdown",
  "count":5
}' --client ClaudeCode

# Results include .contents.markdown with full page content!
# No separate fetch needed - instant content extraction

# Advanced: All search options
bunx @youdotcom-oss/api search --json '{
  "query":"machine learning",
  "count":10,
  "offset":0,
  "country":"US",
  "freshness":"week",
  "safesearch":"moderate",
  "site":"github.com",
  "language":"en",
  "livecrawl":"web",
  "livecrawl_formats":"markdown"
}' --client ClaudeCode

# Parse with jq - direct access, no .data wrapper
bunx @youdotcom-oss/api search --json '{"query":"AI"}' --client ClaudeCode | \
  jq -r '.results.web[] | "\(.title): \(.url)"'

# Extract livecrawl content
bunx @youdotcom-oss/api search --json '{
  "query":"docs",
  "livecrawl":"web",
  "livecrawl_formats":"markdown"
}' --client ClaudeCode | \
  jq -r '.results.web[0].contents.markdown'

⚡ AI Answers with Web Search - Cited Sources

Do a search and extract contents with Livecrawl. Retrieve top 10 URLs content. Using this content, synthesize an answer based on the user's intent. Repeat searches and adjust query parameters as necessary to refine the answer for the user.

📄 Web Content Extraction - Multi-Format Output

# Extract in multiple formats
bunx @youdotcom-oss/api contents --json '{
  "urls":["https://example.com"],
  "formats":["markdown","html","metadata"]
}' --client ClaudeCode

# Pipe markdown to file
bunx @youdotcom-oss/api contents --json '{
  "urls":["https://example.com"],
  "formats":["markdown"]
}' --client ClaudeCode | \
  jq -r '.[0].markdown' > content.md

# Multiple URLs with timeout
bunx @youdotcom-oss/api contents --json '{
  "urls":["https://a.com","https://b.com"],
  "formats":["markdown","metadata"],
  "crawl_timeout":30
}' --client ClaudeCode

# Extract just metadata
bunx @youdotcom-oss/api contents --json '{
  "urls":["https://example.com"],
  "formats":["metadata"]
}' --client ClaudeCode | \
  jq '.[0].metadata'

Error Handling

Exit codes:

• 0 - Success (response on stdout)
• 1 - API error (rate limit, auth, network) - error on stderr
• 2 - Invalid arguments - error on stderr

Stdout/stderr separation:

• Success: Compact JSON response on stdout (no wrapper)
• Error: Error message + mailto link on stderr

Pattern:

# Capture and check exit code
if ! result=$(bunx @youdotcom-oss/api search --json '{"query":"AI"}' --client ClaudeCode); then
  echo "Search failed: $?"
  exit 1
fi

# Parse success response from stdout
echo "$result" | jq .

Error output example:

Error: --json flag is required
    at searchCommand (/path/to/search.ts:26:11)
mailto:support@you.com?subject=API%20Issue%20CLI...

Installation & Setup

Check runtime:

# Check if Node.js or Bun installed
if command -v bun &> /dev/null; then
  echo "Bun installed: $(bun --version)"
elif command -v node &> /dev/null; then
  echo "Node.js installed: $(node --version)"
else
  echo "Neither Node.js nor Bun found."
  echo "Request user permission to install Node.js or Bun"
fi

Using the CLI (recommended for agents):

# bunx (recommended - faster and more reliable)
bunx @youdotcom-oss/api search --json '{"query":"AI"}' --client ClaudeCode

# npx (alternative)
npx @youdotcom-oss/api search --json '{"query":"AI"}' --client ClaudeCode

Environment Variables

export YDC_API_KEY="your-api-key"     # Required
export YDC_CLIENT=ClaudeCode          # Default client name

Override per command:

bunx @youdotcom-oss/api search --json '{"query":"AI"}' \
  --api-key "different-key" \
  --client "DifferentAgent"

Implementation Checklist

Environment Setup

• Runtime check: Node.js 18+ or Bun 1.0+
• If missing: Request user permission to install Node.js or Bun
• Verify installation: node --version or bun --version

Security Configuration

• API key obtained from https://you.com/platform/api-keys (never from third parties)
• Environment variables set: YDC_API_KEY, YDC_CLIENT
• .gitignore includes .env if using dotenv files
• API key NOT hardcoded in scripts
• Package version verified: npm view @youdotcom-oss/api repository

Functional Testing

• Schema discovery tested: bunx @youdotcom-oss/api search --schema
• CLI tested with --json and --client flags
• Livecrawl tested (search + content in one call)
• Content extraction tested with markdown and metadata formats
• Error handling tested (exit codes + stderr)

Security Testing

• Input validation implemented for user queries
• URL validation implemented for content extraction
• Rate limiting tested (429 error handling with retry logic)
• API key not exposed in logs or error messages
• Content extraction output sanitized before display

Integration

• Output parsing implemented (jq without .data wrapper)
• Script integrated into workflow
• Quota monitoring enabled on You.com platform

Common Issues

"Cannot find module @youdotcom-oss/api" Fix: Use bunx (no install needed): bunx @youdotcom-oss/api or npx @youdotcom-oss/api

"--json flag is required" Fix: Pass query as JSON: --json '{"query":"..."}'

"YDC_API_KEY environment variable is required" Fix: export YDC_API_KEY="your-key" (get key from https://you.com/platform/api-keys)

"Tool execution fails with 401" Fix: Verify API key is correct, regenerate key from platform if needed

"Cannot parse jq: .data.results not found" Fix: Remove .data wrapper - use .results directly (API returns compact JSON)

"Rate limit exceeded (429)" Fix: Implement exponential backoff retry logic (see Rate Limiting section)

Advanced Patterns

Schema-Driven Agent

#!/usr/bin/env bash
set -e

# Discover available search parameters (using ydc if installed globally)
schema=$(ydc search --schema)
echo "$schema" | jq '.properties | keys'

# Build query dynamically
query=$(jq -n '{
  query: "AI developments",
  count: 10,
  livecrawl: "web",
  livecrawl_formats: "markdown"
}')

# Execute search (using bunx)
bunx @youdotcom-oss/api search --json "$query" --client ClaudeCode

Parallel Execution

#!/usr/bin/env bash
bunx @youdotcom-oss/api search --json '{"query":"AI"}' --client ClaudeCode &
bunx @youdotcom-oss/api search --json '{"query":"ML"}' --client ClaudeCode &
bunx @youdotcom-oss/api search --json '{"query":"LLM"}' --client ClaudeCode &
wait

Rate Limit Retry

#!/usr/bin/env bash
for i in {1..3}; do
  if bunx @youdotcom-oss/api search --json '{"query":"AI"}' --client ClaudeCode; then
    exit 0
  fi
  [ $i -lt 3 ] && sleep 5
done
echo "Failed after 3 attempts"
exit 1

Security Considerations

API Key Safety

DO:

• Store YDC_API_KEY in environment variables or secure vaults
• Use .env files with .gitignore for local development
• Rotate keys regularly from https://you.com/platform/api-keys
• Restrict key permissions to minimum required scope

DON'T:

• Hardcode API keys in scripts or code
• Commit keys to version control
• Share keys in public forums or logs
• Use production keys in development/testing

Package Security

Package Verification:

# Check package metadata
npm view @youdotcom-oss/api repository homepage

# Verify package integrity
npm view @youdotcom-oss/api dist.integrity

# Check for security advisories
npm audit @youdotcom-oss/api

Updates:

• Review changelog before updating: https://github.com/youdotcom-oss/dx-toolkit/releases
• Test in non-production environment first
• Monitor for security advisories

Input Validation

Query Sanitization:

# DON'T: Pass unsanitized user input
query="$USER_INPUT"
bunx @youdotcom-oss/api search --json "{\"query\":\"$query\"}" --client ClaudeCode

# DO: Validate and escape input with jq
query=$(echo "$USER_INPUT" | jq -Rs .)
bunx @youdotcom-oss/api search --json "{\"query\":$query}" --client ClaudeCode

URL Validation:

# Validate URLs before content extraction
url="$USER_URL"
if [[ $url =~ ^https?:// ]]; then
  bunx @youdotcom-oss/api contents --json "{\"urls\":[\"$url\"],\"formats\":[\"markdown\"]}" --client ClaudeCode
else
  echo "Invalid URL format" >&2
  exit 1
fi

Content Extraction Risks

HTML Content Safety:

• Extracted HTML may contain malicious JavaScript or XSS vectors
• Never render extracted HTML directly in web contexts without sanitization
• Prefer markdown format for display; use html only for archival

Safe Content Handling:

# DO: Extract as markdown (safer for display)
bunx @youdotcom-oss/api contents --json '{
  "urls":["'"$url"'"],
  "formats":["markdown","metadata"]
}' --client ClaudeCode

# DON'T: Render extracted HTML directly in browsers without sanitization

Error Handling & Information Disclosure

Sanitize Error Output:

# Capture errors without exposing sensitive context
if ! result=$(bunx @youdotcom-oss/api search --json "$query" --client ClaudeCode 2>&1); then
  # Log sanitized error (remove API keys, tokens, sensitive URLs)
  echo "Search failed" | sed 's/key=[^&]*/key=REDACTED/g' >&2
  exit 1
fi

Production Logging:

• Remove API keys from logs: Filter YDC_API_KEY values
• Sanitize URLs: May contain sensitive query parameters
• Redact error context: Mailto links may include environment info

Rate Limiting & Abuse Prevention

Implement Exponential Backoff:

#!/usr/bin/env bash
max_retries=3
retry_delay=2

for ((i=1; i<=max_retries; i++)); do
  if bunx @youdotcom-oss/api search --json "$query" --client ClaudeCode; then
    exit 0
  fi
  
  if [ $i -lt $max_retries ]; then
    delay=$((retry_delay ** i))
    echo "Retry $i/$max_retries after ${delay}s..." >&2
    sleep $delay
  fi
done

echo "Failed after $max_retries attempts" >&2
exit 1

Agent Autonomy & Credential Access

Considerations for AI Agents:

• Agents with access to YDC_API_KEY can perform unlimited API calls
• Set quota alerts on You.com platform to monitor usage
• Use read-only or restricted API keys when possible
• Implement circuit breakers for runaway queries

Restricting Model Invocation: If using this skill with autonomous agents:

• Consider requiring user approval for each search (always: true in skill config)
• Limit concurrent requests with semaphores
• Implement query allowlists/denylists for sensitive terms
• Monitor API usage dashboards regularly

Supply Chain Security

Trust Chain:

1. Runtime: Bun/Node.js from official sources only
2. Package: @youdotcom-oss/api from NPM registry
3. Source: Verified at https://github.com/youdotcom-oss/dx-toolkit
4. Credentials: YDC_API_KEY from https://you.com/platform/api-keys

Verification Checklist:

• Runtime installation requested user permission
• Package version specified (not @latest)
• API key obtained from official platform
• Environment variables not committed to version control
• Input validation implemented for user-provided queries/URLs
• Error output sanitized in production
• Rate limiting configured with exponential backoff
• Security updates monitored via GitHub releases

Resources

• Package: https://github.com/youdotcom-oss/dx-toolkit/tree/main/packages/api
• API Keys: https://you.com/platform/api-keys