Web Search Agent Skills: How to Build Web Search Agent Skills in Claude Code

---
name: your-skill-name
description: Brief description of what this skill does and when to use it
---
 
# Your Skill Name
 
[Instructions section]
Clear, step-by-step guidance for Claude.
 
[Examples section]
Concrete input/output examples.

~/.claude/skills/skill-name/SKILL.md

.claude/skills/skill-name/SKILL.md

mkdir -p ~/.claude/skills/web-search-api

---
name: web-search-api
description: Search the web and extract content using WebSearchAPI.ai. Use when needing real-time web data, current information, news, research, or when asked to search the internet. Supports web search, content extraction, and web scraping with advanced filtering options.
---
 
# Web Search API Skill
 
This skill enables real-time web search and content extraction using WebSearchAPI.ai, providing Google-quality results optimized for AI applications.
 
Prerequisites: Ensure you have a WebSearchAPI.ai API key set as environment variable:
export WEBSEARCHAPI_KEY="your_api_key_here"
 
Basic Web Search - use the following curl command:
curl -X POST "https://api.websearchapi.ai/v1/search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $WEBSEARCHAPI_KEY" \
  -d '{"query": "YOUR_SEARCH_QUERY", "num_results": 10}'
 
Advanced Options:
- Geographic filtering: Add "country": "US", "language": "en"
- Time filtering: Add "freshness": "day|week|month|year"
- Full content: Add "include_content": true
 
Content Extraction:
curl -X POST "https://api.websearchapi.ai/v1/extract" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $WEBSEARCHAPI_KEY" \
  -d '{"url": "https://example.com", "output_format": "markdown"}'
 
Tips:
1. Use specific queries for better results
2. Limit results to what you need
3. Use freshness filters for time-sensitive info
4. Always check response status codes

#!/usr/bin/env python3
"""
WebSearchAPI.ai Search Script
Usage: python search.py "your search query" [--num-results 10] [--freshness day]
"""
 
import argparse
import json
import os
import sys
from urllib.request import Request, urlopen
from urllib.error import HTTPError, URLError
 
def search(query: str, num_results: int = 10, freshness: str = None,
           include_content: bool = False, country: str = "US") -> dict:
    """Perform web search using WebSearchAPI.ai"""
 
    api_key = os.environ.get("WEBSEARCHAPI_KEY")
    if not api_key:
        return {"error": "WEBSEARCHAPI_KEY environment variable not set"}
 
    payload = {
        "query": query,
        "num_results": num_results,
        "country": country
    }
 
    if freshness:
        payload["freshness"] = freshness
    if include_content:
        payload["include_content"] = True
 
    data = json.dumps(payload).encode("utf-8")
 
    req = Request(
        "https://api.websearchapi.ai/v1/search",
        data=data,
        headers={
            "Content-Type": "application/json",
            "Authorization": f"Bearer {api_key}"
        },
        method="POST"
    )
 
    try:
        with urlopen(req, timeout=30) as response:
            return json.loads(response.read().decode("utf-8"))
    except HTTPError as e:
        return {"error": f"HTTP {e.code}: {e.reason}"}
    except URLError as e:
        return {"error": f"URL Error: {e.reason}"}
    except Exception as e:
        return {"error": str(e)}
 
def main():
    parser = argparse.ArgumentParser(description="Search the web using WebSearchAPI.ai")
    parser.add_argument("query", help="Search query")
    parser.add_argument("--num-results", type=int, default=10, help="Number of results")
    parser.add_argument("--freshness", choices=["day", "week", "month", "year"],
                        help="Time filter")
    parser.add_argument("--include-content", action="store_true",
                        help="Include full content")
    parser.add_argument("--country", default="US", help="Country code")
 
    args = parser.parse_args()
 
    results = search(
        query=args.query,
        num_results=args.num_results,
        freshness=args.freshness,
        include_content=args.include_content,
        country=args.country
    )
 
    print(json.dumps(results, indent=2))
 
if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
WebSearchAPI.ai Content Extraction Script
Usage: python extract.py "https://example.com/article" [--format markdown]
"""
 
import argparse
import json
import os
import sys
from urllib.request import Request, urlopen
from urllib.error import HTTPError, URLError
 
def extract(url: str, output_format: str = "markdown",
            include_images: bool = False, clean_content: bool = True) -> dict:
    """Extract content from URL using WebSearchAPI.ai"""
 
    api_key = os.environ.get("WEBSEARCHAPI_KEY")
    if not api_key:
        return {"error": "WEBSEARCHAPI_KEY environment variable not set"}
 
    payload = {
        "url": url,
        "output_format": output_format,
        "include_images": include_images,
        "clean_content": clean_content
    }
 
    data = json.dumps(payload).encode("utf-8")
 
    req = Request(
        "https://api.websearchapi.ai/v1/extract",
        data=data,
        headers={
            "Content-Type": "application/json",
            "Authorization": f"Bearer {api_key}"
        },
        method="POST"
    )
 
    try:
        with urlopen(req, timeout=60) as response:
            return json.loads(response.read().decode("utf-8"))
    except HTTPError as e:
        return {"error": f"HTTP {e.code}: {e.reason}"}
    except URLError as e:
        return {"error": f"URL Error: {e.reason}"}
    except Exception as e:
        return {"error": str(e)}
 
def main():
    parser = argparse.ArgumentParser(description="Extract content using WebSearchAPI.ai")
    parser.add_argument("url", help="URL to extract content from")
    parser.add_argument("--format", choices=["markdown", "text", "html"],
                        default="markdown", help="Output format")
    parser.add_argument("--include-images", action="store_true",
                        help="Include images in output")
    parser.add_argument("--raw", action="store_true",
                        help="Don't clean content")
 
    args = parser.parse_args()
 
    results = extract(
        url=args.url,
        output_format=args.format,
        include_images=args.include_images,
        clean_content=not args.raw
    )
 
    print(json.dumps(results, indent=2))
 
if __name__ == "__main__":
    main()

chmod +x ~/.claude/skills/web-search-api/scripts/*.py

---
name: rag-content-extractor
description: Extract and prepare web content for RAG systems and vector databases. Use when building knowledge bases, processing documents for embeddings, preparing content for semantic search, or creating training data for AI systems.
allowed-tools: Bash, Read, Write
---
 
# RAG Content Extractor
 
This skill extracts web content and formats it for optimal use in RAG systems.
Handles: Clean extraction, chunking for embeddings, metadata preservation, format optimization.
 
Quick Start:
python ~/.claude/skills/rag-content-extractor/scripts/rag_extract.py \
  "https://example.com/article" --chunk-size 500 --overlap 50 --output chunks.json
 
Chunking Strategies:
- Fixed-size: python scripts/rag_extract.py "URL" --strategy fixed --chunk-size 500
- Semantic: python scripts/rag_extract.py "URL" --strategy semantic
- Paragraph: python scripts/rag_extract.py "URL" --strategy paragraph
 
Output JSON format includes: source_url, title, extracted_at, chunks[], total_chunks, total_words
 
RAG Tips:
1. Chunk size: 300-500 tokens for most embedding models
2. Overlap: 10-20% prevents context loss at boundaries
3. Always preserve source URL and extraction timestamp
4. Check for duplicate content before adding to vector DB

---
name: research-assistant
description: Conduct comprehensive web research on any topic. Use when asked to research, investigate, analyze trends, compile information, or create reports on current topics. Combines web search, content extraction, and synthesis.
---
 
# Research Assistant Skill
 
This skill enables comprehensive research by combining multi-source web search, content extraction, information synthesis, and citation management.
 
Research Workflow:
1. Initial Search - broad search to identify key sources (20 results, freshness: month)
2. Extract Key Content - for each result, extract full content as markdown
3. Deep Dive Search - targeted searches on specific subtopics (10 results)
 
Research Templates:
- Market Research: market size, industry trends, competitive landscape, growth forecast
- Technical Research: documentation, best practices, implementation, benchmarks
- News/Events: latest news, announcements, upcoming events, updates
 
Output Structure:
- Executive Summary (2-3 paragraphs of key findings)
- Key Findings (with citations)
- Data Points (statistics with sources)
- Sources (all referenced URLs with access dates)
- Methodology (queries used, sources analyzed, date range)
 
Research Tips:
1. Diversify sources - don't rely on a single source
2. Verify facts - cross-reference important claims
3. Note freshness - prioritize recent information
4. Track citations - always note where information came from
5. Identify gaps - note what couldn't be found

---
name: database-query-assistant
description: Generate and optimize SQL queries for PostgreSQL, MySQL, and SQLite. Use when writing database queries, optimizing slow queries, explaining query plans, or working with database schemas.
allowed-tools: Bash, Read, Write
---
 
# Database Query Assistant
 
Helps generate, optimize, and explain SQL queries.
 
Capabilities:
- Generate SELECT/INSERT/UPDATE/DELETE queries from natural language
- Optimize slow queries with EXPLAIN ANALYZE
- Generate migrations and schema changes
- Convert between database dialects
 
Query Generation Pattern:
1. Understand the data model (read schema files or describe tables)
2. Identify required tables and relationships
3. Generate query with proper JOINs and indexes
4. Validate with EXPLAIN before running
 
Optimization Tips:
- Always use parameterized queries to prevent SQL injection
- Add appropriate indexes for WHERE and JOIN columns
- Use LIMIT for large result sets
- Prefer EXISTS over IN for subqueries

---
name: code-reviewer
description: Review code for quality, security vulnerabilities, and best practices. Use when reviewing pull requests, checking code quality, finding bugs, or auditing security.
allowed-tools: Read, Grep, Glob
---
 
# Code Review Skill
 
Performs comprehensive code review focusing on quality, security, and maintainability.
 
Review Checklist:
1. Security: SQL injection, XSS, CSRF, hardcoded secrets, auth issues
2. Performance: N+1 queries, memory leaks, inefficient algorithms
3. Code Quality: DRY violations, dead code, complex functions
4. Error Handling: Unhandled exceptions, missing validation
5. Testing: Missing tests, edge cases, mocking issues
 
Security Patterns to Flag:
- eval(), exec(), or dynamic code execution
- Unsanitized user input in queries or commands
- Hardcoded API keys, passwords, or tokens
- Missing authentication/authorization checks
- Insecure cryptographic practices
 
Output Format:
[SEVERITY] Issue description
Location: file:line
Problem: What's wrong
Fix: How to resolve it

---
name: git-workflow
description: Automate git workflows including commits, branches, PRs, and release management. Use when committing changes, creating branches, managing releases, or following git conventions.
---
 
# Git Workflow Skill
 
Automates git operations following team conventions.
 
Branch Naming:
- feature/TICKET-description
- bugfix/TICKET-description
- hotfix/TICKET-description
- release/vX.Y.Z
 
Commit Message Format:
type(scope): description
 
Types: feat, fix, docs, style, refactor, test, chore
Example: feat(auth): add two-factor authentication support
 
PR Workflow:
1. Create feature branch from main
2. Make changes with atomic commits
3. Push and create PR with template
4. Request reviews from CODEOWNERS
5. Squash merge after approval
 
Release Process:
1. Create release branch from main
2. Update version in package.json
3. Generate changelog from commits
4. Tag release with semantic version
5. Merge to main and deploy

---
name: api-tester
description: Test REST APIs, validate responses, and generate documentation. Use when testing endpoints, debugging API issues, validating schemas, or creating API documentation.
---
 
# API Testing Skill
 
Tests REST APIs and validates responses against expected schemas.
 
Testing Workflow:
1. Read API specification (OpenAPI/Swagger if available)
2. Generate test requests for each endpoint
3. Validate response status, headers, and body
4. Check error handling with invalid inputs
5. Measure response times
 
Test Categories:
- Happy Path: Valid requests with expected responses
- Error Cases: Invalid inputs, missing auth, rate limits
- Edge Cases: Empty arrays, null values, large payloads
- Security: Auth bypass, injection attempts
 
Request Template:
curl -X METHOD "URL" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TOKEN" \
  -d '{"key": "value"}'
 
Validation Checks:
- Status code matches expected
- Response time under threshold
- Required fields present
- Data types correct
- Pagination working

---
name: doc-generator
description: Generate documentation from code including API docs, README files, and architecture diagrams. Use when creating documentation, updating READMEs, or documenting APIs.
allowed-tools: Read, Grep, Glob, Write
---
 
# Documentation Generator
 
Creates and maintains documentation from source code.
 
Documentation Types:
- API Reference: Endpoints, parameters, responses
- Code Comments: JSDoc, docstrings, inline docs
- README: Project overview, setup, usage
- Architecture: System diagrams, data flow
 
README Template:
1. Project title and badges
2. Description and features
3. Installation instructions
4. Usage examples
5. Configuration options
6. Contributing guidelines
7. License information
 
API Doc Format:
Endpoint: METHOD /path
Description: What it does
Parameters: name (type, required) - description
Response: { schema }
Example: curl command
 
Best Practices:
- Keep docs close to code
- Include runnable examples
- Update docs with code changes
- Use consistent formatting

---
name: test-generator
description: Generate unit tests, integration tests, and test fixtures. Use when writing tests, improving coverage, creating mocks, or setting up test infrastructure.
allowed-tools: Read, Write, Bash
---
 
# Test Generator Skill
 
Generates comprehensive tests for functions, classes, and APIs.
 
Test Types:
- Unit Tests: Individual functions in isolation
- Integration Tests: Multiple components together
- E2E Tests: Full user workflows
- Snapshot Tests: UI component rendering
 
Coverage Targets:
- Happy path with valid inputs
- Edge cases (empty, null, boundary values)
- Error conditions and exceptions
- Async behavior and timeouts
 
Test Structure (Arrange-Act-Assert):
1. Arrange: Set up test data and mocks
2. Act: Execute the function under test
3. Assert: Verify expected outcomes
 
Mock Patterns:
- External APIs: Return canned responses
- Databases: Use in-memory or fixtures
- Time: Freeze or control time progression
- Random: Seed for reproducibility

---
name: env-setup
description: Configure development environments, manage dependencies, and set up tooling. Use when setting up projects, configuring environments, or onboarding new developers.
---
 
# Environment Setup Skill
 
Standardizes development environment configuration across teams.
 
Setup Checklist:
1. Install runtime (Node, Python, etc.)
2. Install package manager (npm, pip, etc.)
3. Clone repository
4. Install dependencies
5. Configure environment variables
6. Set up database
7. Run initial migrations
8. Verify with test suite
 
Environment Variables:
- Copy .env.example to .env
- Fill in required values
- Never commit .env to git
- Use different values per environment
 
Common Issues:
- Version mismatch: Use nvm/pyenv for version management
- Missing deps: Delete node_modules and reinstall
- Port conflicts: Check for running processes
- Permission errors: Fix file ownership

---
name: performance-profiler
description: Profile application performance, identify bottlenecks, and suggest optimizations. Use when debugging slow code, optimizing queries, or improving response times.
allowed-tools: Bash, Read, Grep
---
 
# Performance Profiler Skill
 
Identifies performance bottlenecks and suggests optimizations.
 
Profiling Areas:
- CPU: Hot functions, inefficient algorithms
- Memory: Leaks, excessive allocation
- I/O: Slow queries, network latency
- Rendering: Layout thrashing, repaints
 
Analysis Commands:
- Node.js: node --prof app.js && node --prof-process
- Python: python -m cProfile -s cumtime script.py
- Database: EXPLAIN ANALYZE query
 
Common Bottlenecks:
- N+1 queries: Batch database calls
- Synchronous I/O: Use async/await
- Large payloads: Paginate and compress
- Missing indexes: Add database indexes
- Memory leaks: Clean up event listeners
 
Optimization Priority:
1. Measure before optimizing
2. Fix algorithmic issues first (O(n²) → O(n))
3. Cache expensive computations
4. Optimize database queries
5. Consider caching layers (Redis)

---
name: deployment-helper
description: Automate deployments to Vercel, AWS, Docker, and Kubernetes. Use when deploying applications, setting up CI/CD, or managing infrastructure.
---
 
# Deployment Helper Skill
 
Automates deployment workflows for various platforms.
 
Supported Platforms:
- Vercel: vercel --prod
- AWS: aws deploy / cdk deploy
- Docker: docker build && docker push
- Kubernetes: kubectl apply -f
 
Pre-Deployment Checklist:
1. All tests passing
2. Environment variables configured
3. Database migrations ready
4. Build succeeds locally
5. Security scan clean
 
Deployment Commands:
Vercel: vercel --prod --env-file .env.production
Docker: docker build -t app:tag . && docker push registry/app:tag
K8s: kubectl apply -f k8s/ --namespace production
 
Rollback Procedures:
- Vercel: vercel rollback
- K8s: kubectl rollout undo deployment/app
- Docker: Update image tag to previous version
 
Health Checks:
- Verify endpoint responds
- Check logs for errors
- Monitor metrics dashboard
- Test critical user flows

---
name: safe-web-reader
description: Read-only web search and content viewing. Use for research and information gathering without making changes.
allowed-tools: Bash, Read, Grep, Glob
---

import time
from functools import wraps
 
def retry_with_backoff(max_retries=3, base_delay=1):
    def decorator(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            for attempt in range(max_retries):
                try:
                    return func(*args, **kwargs)
                except Exception as e:
                    if attempt == max_retries - 1:
                        raise
                    delay = base_delay * (2 ** attempt)
                    time.sleep(delay)
            return None
        return wrapper
    return decorator
 
@retry_with_backoff(max_retries=3)
def search_with_retry(query):
    return search(query)

import json
import hashlib
import os
from datetime import datetime, timedelta
 
CACHE_DIR = os.path.expanduser("~/.cache/websearchapi")
CACHE_TTL = timedelta(hours=1)
 
def get_cache_path(query):
    query_hash = hashlib.md5(query.encode()).hexdigest()
    return os.path.join(CACHE_DIR, f"{query_hash}.json")
 
def cached_search(query):
    os.makedirs(CACHE_DIR, exist_ok=True)
    cache_path = get_cache_path(query)
 
    # Check cache
    if os.path.exists(cache_path):
        with open(cache_path) as f:
            cached = json.load(f)
        cached_time = datetime.fromisoformat(cached["timestamp"])
        if datetime.now() - cached_time < CACHE_TTL:
            return cached["results"]
 
    # Fetch fresh results
    results = search(query)
 
    # Save to cache
    with open(cache_path, "w") as f:
        json.dump({
            "timestamp": datetime.now().isoformat(),
            "results": results
        }, f)
 
    return results

import time
from collections import deque
 
class RateLimiter:
    def __init__(self, max_requests=100, time_window=60):
        self.max_requests = max_requests
        self.time_window = time_window
        self.requests = deque()
 
    def wait_if_needed(self):
        now = time.time()
 
        # Remove old requests
        while self.requests and self.requests[0] < now - self.time_window:
            self.requests.popleft()
 
        # Wait if at limit
        if len(self.requests) >= self.max_requests:
            sleep_time = self.requests[0] + self.time_window - now
            if sleep_time > 0:
                time.sleep(sleep_time)
 
        self.requests.append(now)
 
limiter = RateLimiter(max_requests=100, time_window=60)
 
def rate_limited_search(query):
    limiter.wait_if_needed()
    return search(query)