SponsoredSkillry: Agent Skills with taste. Designed and tested in-house, so one prompt gives you polished slides, web pages and launch videos.Skillry: Agent Skills with taste Try free Skills
Agent Skills
  • Skills
  • Picks
  • ShopSoon
  • Solutions
  • Specification
  • Submit
Agent Skills
Agent Skills

Discover and share powerful Agent Skills for AI assistants

GitHubX (Twitter)
Skills
  • View All
  • Install Guide
  • Documentation
  • Solutions
  • Product Launch Video
  • Submit
Tools
  • Claude Code
  • Cursor
  • OpenCode
  • Codex CLI
  • Gemini CLI
Resources
  • anthropics/skills
  • awesome-claude-skills
  • vercel-labs/agent-skills
  • kepano/obsidian-skills
Company
  • About
  • Changelog
  • Privacy Policy
  • Terms of Service

Sponsored by Vectrust @ OpenDev Org & NextRouter Alliance

© 2026 EvergreenAI. Built with JimmyLv
valyu-best-practices - Agent Skill - Agent Skills
Home/Skills/valyu-best-practices

valyu-best-practices

4
MIT

Complete Valyu API toolkit for AI agents. Use this skill when asked to perform real-time search across web, academic, medical, transportation, financial sources, content extraction from URLs, AI-powered answers with citations, or comprehensive deep research reports.

Download FolderView on GitHub

CLI Install

Recommended

Use the skills CLI to install this skill with one command. Auto-detects all installed AI assistants.

Method 1 - skills CLI

npx skills i valyuAI/skills/valyu-search/valyu-best-practices

Method 2 - openskills (supports sync & update)

npx openskills install valyuAI/skills

Auto-detects Claude Code, Cursor, Codex CLI, Gemini CLI, and more. One install, works everywhere.

Installation Path

Download and extract to one of the following locations:

~/.claude/skills/valyu-best-practices/
SKILL.md

Skill Instructions

Back

Run with Cloud Agent

No setup needed. Let our cloud agents run this skill for you.

Select Provider

Select Model

ClaudeClaude Sonnet 5.5
$0.20/task

Best for coding tasks

Join Cloud Agent Waitlist

No setup required

Before you install

Read from this skill's files on GitHub on 2026-11-09. These are facts about the files, not a review of how well the skill works.

Files
47 files, 1 script, SKILL.md is 2054 words
Needs on your machine
Python, Node.js
Environment variables it reads
VALYU_API_KEY, GOOGLE_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY
Web addresses in its scripts
No URLs in its scripts
Worth a look before running
No sudo, rm -rf, curl | sh or shell=True in its scripts
Agent Skills spec
name and description present, name matches the folder
Last upstream change
2026-01-21

Valyu Best Practices

This skill provides instructions for using the Valyu API to perform search, content extraction, AI-powered answers, and deep research tasks.

Quick Reference: Choosing the Right API

Use this decision tree to select the appropriate Valyu API:

What do you need?

├─ Find information across multiple sources
│  └─ Use Search API
│
├─ Extract content from specific URLs
│  └─ Use Contents API
│
├─ Get an AI-synthesized answer with citations
│  └─ Use Answer API
│
├─ Generate a comprehensive research report
│  └─ Use DeepResearch API
│
└─ Discover available data sources
   └─ Use Datasources API

⚠️ MANDATORY: Use Official Valyu SDK Libraries

CRITICAL: When writing code that uses the Valyu API, you MUST use the official SDK libraries. NEVER make raw HTTP/fetch calls to the Valyu API endpoints.

JavaScript/TypeScript: valyu-js
npm install valyu-js
# or
pnpm add valyu-js
import { Valyu } from 'valyu-js';
 
const valyu = new Valyu(process.env.VALYU_API_KEY);
 
// Now use valyu.search(), valyu.contents(), valyu.answer(), valyu.deepResearch
Python: valyu
pip install valyu
# or
uv add valyu
from valyu import Valyu
 
valyu = Valyu(api_key=os.environ.get("VALYU_API_KEY"))
 
# Now use valyu.search(), valyu.contents(), valyu.answer(), valyu.deep_research
Why SDK Over Raw API Calls?
  1. Type safety - Full TypeScript/Python type hints for all parameters and responses
  2. Automatic retries - Built-in retry logic for transient failures
  3. Streaming support - Proper async iterator support for streaming responses
  4. Error handling - Structured error types with helpful messages
  5. Future compatibility - SDK updates handle API changes automatically
❌ NEVER Do This
// DON'T make raw fetch calls
const response = await fetch('https://api.valyu.ai/v1/search', {
  method: 'POST',
  headers: {
    'x-api-key': apiKey,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ query: '...' })
});
✅ Always Do This
// DO use the SDK
import { Valyu } from 'valyu-js';
 
const valyu = new Valyu(process.env.VALYU_API_KEY);
const response = await valyu.search({ query: '...' });

1. Search API

Purpose: Find information across web, academic, medical, transportation, financial, news, and proprietary sources.

When to Use
  • Finding recent information on any topic
  • Academic research (arXiv, PubMed, bioRxiv, medRxiv)
  • Financial data (SEC filings, earnings reports, stock data)
  • News monitoring and current events
  • Healthcare data (clinical trials, drug labels)
  • Prediction markets (Polymarket, Kalshi)
  • Transportation (UK National Rail, Global Shipping)
Basic Usage
const response = await valyu.search({
  query: "transformer architecture attention mechanism 2024",
  searchType: "all",
  maxNumResults: 10
});
Search Types
TypeUse For
allEverything - web, academic, financial, proprietary
webGeneral internet content only
proprietaryLicensed academic papers and research
newsNews articles and current events
Key Parameters
Parameter (TS/JS)Parameter (Python)PurposeExample
queryquerySearch query (under 400 chars)"CRISPR gene editing 2024"
searchTypesearch_typeSource scope"all", "web", "proprietary", "news"
Domain-Specific Search Patterns

Academic Research:

await valyu.search({
  query: "CRISPR therapeutic applications clinical trials",
  searchType: "proprietary",
  includedSources: ["valyu/valyu-arxiv", "valyu/valyu-pubmed", "valyu/valyu-biorxiv"],
  startDate: "2024-01-01"
});

Financial Analysis:

await valyu.search({
  query: "Apple revenue Q4 2024 earnings",
  searchType: "all",
  includedSources: ["valyu/valyu-sec-filings", "valyu/valyu-earnings-US"]
});

News Monitoring:

await valyu.search({
  query: "AI regulation EU",
  searchType: "news",
  startDate: "2024-06-01",
  countryCode: "EU"
});
Search Recipes

For detailed patterns, see:

  • Basic Search Patterns
  • Academic Search
  • Finance Search
  • News Search
  • Healthcare Search

2. Contents API

Purpose: Extract clean, structured content from web pages optimized for LLM processing.

When to Use
  • Converting web pages to clean markdown
  • Extracting article text for summarization
  • Parsing documentation for RAG systems
  • Structured data extraction from product pages
  • Processing academic papers
Basic Usage
const response = await valyu.contents({
  urls: ["https://example.com/article"]
});
With Summarization
const response = await valyu.contents({
  urls: ["https://arxiv.org/abs/2401.12345"],
  summary: "Extract key findings in 3 bullet points"
});
Structured Extraction (JSON Schema)
const response = await valyu.contents({
  urls: ["https://example.com/product"],
  summary: {
    type: "object",
    properties: {
      product_name: { type: "string" },
      price: { type: "number" },
      features: { type: "array", items: { type: "string" } }
    },
    required: [

Key Parameters
Parameter (TS/JS)Parameter (Python)PurposeExample
urlsurlsURLs to process (1-10)["https://example.com"]
responseLengthresponse_lengthContent length"short", "medium", "large", "max"
Content Recipes

For detailed patterns, see:

  • Basic Content Extraction
  • Extraction with Summary
  • Structured Extraction
  • Research Paper Extraction

3. Answer API

Purpose: Get AI-powered answers grounded in real-time search results with citations.

When to Use
  • Questions requiring current information synthesis
  • Multi-source fact verification
  • Technical documentation questions
  • Research requiring cited sources
  • Structured data extraction from search results
Basic Usage
const response = await valyu.answer({
  query: "What are the latest developments in quantum computing?"
});
With Fast Mode (Lower Latency)
const response = await valyu.answer({
  query: "Current Bitcoin price and 24h change",
  fastMode: true
});
With Custom Instructions
const response = await valyu.answer({
  query: "Compare React and Vue for enterprise applications",
  systemInstructions: "Provide a balanced comparison with pros and cons. Format as a comparison table."
});
With Streaming
const stream = await valyu.answer({
  query: "Explain transformer architecture",
  streaming: true
});
 
for await (const chunk of stream) {
  // Handle: search_results, content, metadata, done, error
  console.log(chunk);
}
Structured Output
const response = await valyu.answer({
  query: "Apple Q4 2024 financial highlights",
  structuredOutput: {
    type: "object",
    properties: {
      revenue: { type: "string" },
      growthRate: { type: "string" },
      keyHighlights: { type: "array", items: { type: "string" } }
    }
  }
Key Parameters
Parameter (TS/JS)Parameter (Python)PurposeExample
queryqueryQuestion to answer"What is quantum computing?"
fastModefast_modeLower latencytrue
systemInstructions
Answer Recipes

For detailed patterns, see:

  • Basic Answer
  • Fast Mode
  • Streaming
  • Custom Instructions

4. DeepResearch API

Purpose: Generate comprehensive research reports with detailed analysis and citations.

When to Use
  • Comprehensive market analysis
  • Literature reviews
  • Competitive intelligence
  • Technical deep dives
  • Topics requiring multi-source synthesis
Research Modes
ModeDurationBest For
fast~5 minutesQuick lookups, simple questions
standard~10-20 minutesBalanced research (most common)
heavy~90 minutesComprehensive analysis, complex topics
Create Research Task
const task = await valyu.deepResearch.create({
  query: "AI chip market competitive landscape 2024",
  model: "standard"
});
// Returns: { deepresearch_id: "abc123", status: "queued" }
Poll for Completion
const status = await valyu.deepResearch.getStatus(task.deepresearch_id);
// status: "queued" | "running" | "completed" | "failed" | "cancelled"
 
if (status.status === "completed") {
  console.log(status.output);  // Markdown report
  console.log(status.sources); // Cited sources
  console.log(status.pdf_url); // PDF download link
}
Key Parameters
Parameter (TS/JS)Parameter (Python)PurposeExample
queryqueryResearch question"AI market trends 2024"
modelmodelResearch depth"fast", "standard", "heavy"
DeepResearch Recipes

For detailed patterns, see:

  • Fast Research
  • Standard Research
  • Heavy Research

5. Query Writing Best Practices
Core Principles
  1. Be specific - Use domain terminology
  2. Be concise - Keep queries under 400 characters
  3. Be focused - One topic per query
  4. Add constraints - Include timeframes, source types
Query Anatomy
ElementDescriptionExample
IntentWhat you need"latest advancements" vs "overview"
DomainTopic terminology"transformer architecture"
ConstraintsFilters"2024", "peer-reviewed"
Source typeWhere to lookacademic papers, SEC filings
Good vs Bad Queries
BAD:  "I want to know about AI"
GOOD: "transformer attention mechanism survey 2024"

BAD:  "Apple financial information"
GOOD: "Apple revenue growth Q4 2024 earnings SEC filing"

BAD:  "gene editing research"
GOOD: "CRISPR off-target effects therapeutic applications 2024"
Split Complex Requests
# Don't do this
"Tesla stock performance, new products, and Elon Musk statements"

# Do this instead
Query 1: "Tesla stock performance Q4 2024"
Query 2: "Tesla Cybertruck production updates 2024"
Query 3: "Tesla FSD autonomous driving progress"
Source Filtering

Use includedSources for domain authority: ​ Financial Research Collection. Some sources to include:

  • valyu/valyu-sec-filings - SEC regulatory filings
  • valyu/valyu-stocks - Stock market data
  • valyu/valyu-earnings-US - Earnings reports
  • reuters.com - Financial news
  • bloomberg.com - Market analysis ​ Medical Research Collection. Some sources to include:
  • valyu/valyu-pubmed - Medical literature
  • valyu/valyu-clinical-trials - Clinical trial data
  • valyu/valyu-drug-labels - FDA drug information
  • nejm.org - New England Journal of Medicine
  • thelancet.com - The Lancet ​ Tech Documentation Collection. Some sources to include:
  • docs.aws.amazon.com - AWS documentation
  • cloud.google.com/docs - Google Cloud docs
  • learn.microsoft.com - Microsoft docs
  • kubernetes.io/docs - Kubernetes docs
// Academic
includedSources: ["valyu/valyu-arxiv", "valyu/valyu-pubmed", "nature"]
 
// Financial
includedSources: ["valyu/valyu-sec-filings", "bloomberg.com", "reuters.com"]
 
// Tech news
includedSources: ["techcrunch.com", "theverge.com", "arstechnica.com"]

For complete prompting guide, see references/prompting.md.


6. Common Workflows
Research Workflow
// 1. Quick search to find sources
const searchResults = await valyu.search({
  query: "CRISPR therapeutic applications",
  searchType: "proprietary",
  maxNumResults: 20
});
 
// 2. Extract key content from top results
const contents = await valyu.contents({








Financial Analysis Workflow
// 1. Get SEC filings
const filings = await valyu.search({
  query: "Apple 10-K 2024",
  includedSources: ["valyu/valyu-sec-filings"]
});
 
// 2. Quick synthesis
const summary = await valyu.answer({
  query: "Apple Q4 2024 financial highlights"















7. Available Data Sources

Valyu provides access to 25+ specialized datasets:

CategoryExamples
AcademicarXiv (2.5M+ papers), PubMed (37M+), bioRxiv, medRxiv
FinancialSEC filings, earnings transcripts, stock data, crypto
HealthcareClinical trials, DailyMed, PubChem, drug labels, ChEMBL, DrugBank, Open Target, WHO ICD
EconomicFRED, BLS, World Bank, US Treasury, Destatis
PredictionsPolymarket, Kalshi
PatentsUS patent database
TransportationUK Rail, Ship Tracking

For complete datasource reference, see references/datasources.md.


8. API Reference

For complete API documentation including all parameters, response structures, and error codes, see references/api-guide.md.


9. Integration Guides

Platform-specific integration documentation:

  • Anthropic Claude
  • OpenAI
  • Vercel AI SDK
  • LangChain
  • LlamaIndex
  • MCP Server

Additional Resources
  • All Recipes Index
  • Design Philosophy
  • Prompting Guide
  • Full API Reference
maxNumResultsmax_num_resultsNumber of results (1-20)10
includedSourcesincluded_sourcesLimit to specific sources["valyu/valyu-arxiv", "valyu/valyu-pubmed"]
startDate / endDatestart_date / end_dateDate filtering"2024-01-01"
relevanceThresholdrelevance_thresholdMinimum relevance (0-1)0.7
"product_name"
,
"price"
]
}
});
extractEffortextract_effortExtraction quality"normal", "high", "auto"
summarysummaryAI summarizationtrue, "instructions", or JSON schema
screenshotscreenshotCapture screenshotstrue
});
system_instructions
AI directives
"Be concise"
structuredOutputstructured_outputJSON schema{type: "object", ...}
streamingstreamingEnable SSE streamingtrue
dataMaxPricedata_max_priceDollar limit1.0
outputFormat
output_format
Report format
"markdown", "pdf"
includedSourcesincluded_sourcesSource filtering["valyu/valyu-arxiv", "techcrunch.com"]
startDate / endDatestart_date / end_dateDate range"2024-01-01"
  • developer.mozilla.org - MDN Web Docs
  • urls: searchResults.results.slice(0, 3).map(r => r.url),
    summary: "Extract key findings"
    });
    // 3. Deep analysis for comprehensive report
    const research = await valyu.deepResearch.create({
    query: "CRISPR therapeutic applications comprehensive review",
    model: "heavy"
    });
    ,
    fastMode: true
    });
    // 3. Structured extraction
    const metrics = await valyu.answer({
    query: "Apple financial metrics 2024",
    structuredOutput: {
    type: "object",
    properties: {
    revenue: { type: "string" },
    netIncome: { type: "string" },
    growthRate: { type: "string" }
    }
    }
    });