Lukasstrickler AI Dev Atelier Search

Search

Search web, library docs, and GitHub code using progressive escalation.

Quick Start

Decision Tree:

• Library/framework docs? → Context7 get-library-docs
• Code examples/patterns? → GitHub Grep grep_searchGitHub
• Web info/tutorials? → Tavily tavily_search (fallback chain: Exa → Z.AI webSearchPrime)
• Error screenshot/diagram? → Z.AI Vision diagnose_error_screenshot / understand_technical_diagram
• Multiple sources needed? → Run tools in parallel

Default Workflow:

1. Start simple: search_depth: "basic", maxResults: 5
2. If insufficient: Escalate to Level 2 (expand query, increase results)
3. If repeated problem: Escalate to Level 3 (parallel queries, extraction, crawling)

Agent Roles

If you are the main agent (orchestrator):

• External questions → Fire 3-5 librarian agents in parallel with different angles
• Local codebase patterns → Fire explore in background
• Quick web lookups → Do Tavily yourself (faster than delegation overhead)
• Build confidence → Fire multiple librarians: 2 for docs, 2 for real-world examples, 2 to find edge cases/gotchas
• Collect results with background_output, synthesize, cross-validate

If you are the librarian (subagent):

• You are the WORKHORSE - do NOT be lazy or return minimal results
• Fire 3-5 parallel tool calls depending on request complexity (see TYPE A/B/C/D in your system prompt)
• Vary your queries - different angles, not the same pattern repeated
• Always cite with permalinks - every claim needs [Source](url#L10-L20) format
• Rate your confidence - end with: CONFIDENCE: HIGH/MEDIUM/LOW and why

Subagent Calling Example

// GOOD: Fire multiple librarians with different angles for comprehensive coverage
background_task({
  agent: "librarian",
  prompt: `Find OFFICIAL documentation for Next.js 15 App Router authentication.

FIRST: MUST load and read 'search' skill before starting
LEVEL: 3 (deep research - parallel queries, thorough extraction)
FOCUS: Official Next.js and next-auth docs only
TOOLS: Context7 for Next.js, next-auth docs
FORMAT: Use markdown tables for comparisons, code blocks for snippets
OUTPUT: Official recommended approach with doc permalinks
END WITH: CONFIDENCE rating (HIGH/MEDIUM/LOW) and reasoning`
})

background_task({
  agent: "librarian", 
  prompt: `Find REAL-WORLD implementations of Next.js 15 authentication.

FIRST: MUST load and read 'search' skill before starting
LEVEL: 3 (deep research - multiple pattern variations, cross-repo)
FOCUS: Production codebases on GitHub
TOOLS: grep_searchGitHub with queries: "getServerSession(", "auth(", language: TypeScript
FORMAT: For each example: repo name, permalink, architecture notes
OUTPUT: 3-5 code examples with GitHub permalinks, note patterns/variations
END WITH: CONFIDENCE rating (HIGH/MEDIUM/LOW) and reasoning`
})

background_task({
  agent: "librarian",
  prompt: `Find EDGE CASES and GOTCHAS for Next.js 15 authentication.

FIRST: MUST load and read 'search' skill before starting
LEVEL: 3 (deep research - cross-reference multiple sources)
FOCUS: Issues, discussions, Stack Overflow
TOOLS: zai-zread_search_doc for repo issues/discussions (thorough), tavily_search for blog posts/SO
FORMAT: Problem → Evidence → Solution table
OUTPUT: Common pitfalls, breaking changes, migration issues
END WITH: CONFIDENCE rating (HIGH/MEDIUM/LOW) and reasoning`
})

// Then collect and cross-validate:
// - Do real-world examples match official docs?
// - Are there gotchas the docs don't mention?
// - Synthesize into recommendation with overall confidence

// BAD: No skill loading, no structure
background_task({
  agent: "librarian", 
  prompt: "How does Next.js auth work?"  // Missing FIRST step, no level, no format = lazy results
})

Tools Overview

Tavily (Web Search)

Web Fallback Providers

Context7 (Library Docs)

GitHub Grep (Code Search)

Critical: GitHub Grep searches literal code patterns, not keywords!

• ✅ Good: useState(, getServerSession, (?s)try {.*await
• ❌ Bad: react tutorial, how to authenticate

Z.AI Zread (Semantic GitHub Search)

Use when: Code/keyword search misses context, need discussion threads, searching for "why" not "what".

Z.AI Vision (Visual Content)

Use when: User provides screenshot, error image, architecture diagram, or UI mockup.

GitHub CLI (Repo Search)

# Repository structure
gh api "repos/{owner}/{repo}/git/trees/{branch}?recursive=1"

# Search issues
gh api -X GET search/issues -f q="repo:{owner}/{repo} is:issue {keywords}"

# Read file directly
webfetch("https://raw.githubusercontent.com/{owner}/{repo}/{branch}/{path}")

Progressive Escalation Levels

Level 1: Simple Search (Default)

When: Quick lookups, straightforward questions, first encounter

1. Tavily: search_depth: "basic", maxResults: 5
2. Context7: mode: "code" for API, mode: "info" for concepts
3. GitHub Grep: literal code patterns with language filter
4. Parallel execution when appropriate

Sufficient? → Done. Insufficient? → Level 2

Level 2: Enhanced Search

When: Initial results incomplete, need more examples, outdated results

1. Expand query: Add synonyms, context (keep <400 chars)
2. Increase: maxResults: 10-15, search_depth: "advanced"
3. Filter domains: include_domains: ["stackoverflow.com", "github.com"]
4. Time filter: time_range: "year" for recent info
5. Two-step extraction: Search → Filter by score (>0.5) → Extract top URLs
6. Discussions/docs gap: Use search_doc or gh api search/issues when keyword/code search misses context

Sufficient? → Done. Insufficient? → Level 3

Level 3: Deep Research

When: Problem encountered 2+ times, complex topic, building knowledge base

1. Parallel queries: 3-5 query variations with synonyms
2. Systematic extraction: Top 5-10 URLs with extract_depth: "advanced"
3. Website exploration: tavily_map → tavily_crawl
4. GitHub deep dive: Multiple pattern variations, regex, cross-repo comparison
5. Cross-reference: Verify across multiple sources

Key Tips (Reminders)

Query Formulation

• 400 char limit - Break complex queries into sub-queries
• Natural language works better - Full sentences > keywords
• Be specific - Include technology, use case, context
• For full guide: See references/query-guide.md

Score-Based Filtering

• Tavily results include score (0-1)
• >0.5 typically good - Adjust based on distribution
• Filter before extracting to save credits

Two-Step Extraction Pattern

1. Search with search_depth: "advanced"
2. Filter URLs by score (>0.5)
3. Extract top 2-5 URLs with extract_depth: "basic"
4. Upgrade to "advanced" only if needed

GitHub Grep Patterns

# API usage
Query: getServerSession
Language: ['TypeScript'], Path: '/api/'

# Multiline with regex
Query: (?s)useEffect\(\(\) => {.*cleanup
useRegexp: true

Cost Optimization

• basic = 1 credit, advanced = 2 credits
• Prefer two-step extraction over include_raw_content: true
• Use tavily_map before tavily_crawl

Quota Management:

• Default to Tavily for important/critical searches (better relevance when quota available)
• If Tavily fails due to quota/rate limit (429), fail over immediately to Exa (no retry)
• For other transient Tavily failures (timeout/5xx), do one jittered retry (~300-800ms)
• Fallback to Exa (websearch_web_search_exa) when Tavily still fails after that retry
• If Exa fails due to quota/rate limit, fail over immediately to Z.AI webSearchPrime (no retry)
• For other transient Exa failures (timeout/5xx), do one jittered retry (~300-800ms), then fail over to Z.AI
• If Exa is empty/low-quality, fallback to Z.AI webSearchPrime
• Don't loop retries across providers; fail over immediately to next provider

For advanced techniques: See references/advanced-techniques.md

Common Patterns

For workflow examples: See references/examples/example-workflows.md

References

• references/reference-parameters.md - Complete parameter reference for all tools
• references/query-guide.md - Query structuring, 400 char limit, expansion strategies
• references/advanced-techniques.md - Two-step extraction, post-processing, cost optimization
• references/examples/example-workflows.md - Practical workflow examples

Output

Search results are used directly in context. No files saved unless requested. For comprehensive research with evidence cards, use the research skill.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.