context7

Original source / Raw SKILL.md

---
name: context7
description: "Fetch up-to-date library documentation via Context7 REST API. Use when needing current API docs, framework patterns, or code examples for any library. Use when user asks about React, Next.js, Prisma, Express, Vue, Angular, Svelte, or any npm/PyPI package. Use when user says 'how do I use X library', 'what's the API for Y', or needs official documentation. Lightweight alternative to Context7 MCP with no persistent context overhead."
allowed-tools: Bash(python:*)
---

# Context7 Documentation Lookup Skill

Fetch current library documentation, API references, and code examples without MCP context overhead.

**Works on all platforms via REST API.**

## When to Use

**Activate automatically when:**

- User asks about library APIs or framework patterns
- User requests code generation using specific libraries/frameworks
- Import statements suggest documentation needs: `import`, `require`, `from`
- Questions about specific library versions or migration
- Need for official documentation patterns vs generic solutions
- Setting up or configuring third-party tools
- "How do I use X library?", "What's the API for Y?"

**Examples:**

- "Create Next.js middleware with authentication" → Use context7
- "Set up Prisma with PostgreSQL" → Use context7
- "Implement Supabase authentication" → Use context7

## Workflow

### Quick Start (If You Know the Library)

**Skip the search** when you already know the library:

```bash
scripts/context7.py docs "/vercel/next.js" "middleware authentication"
```

Common library IDs:

- React: `/facebook/react`
- Next.js: `/vercel/next.js`
- Prisma: `/prisma/prisma`
- Supabase: `/supabase/supabase`
- Express: `/expressjs/express`

### Full Workflow

#### Step 1: Search for Library ID (if unknown)

Search first to get the correct library ID:

```bash
scripts/context7.py search "library-name"
```

Example output shows library IDs you can use:

```txt
ID: /facebook/react
Name: React
Snippets: 2135 | Score: 79.4
```

#### Step 2: Fetch Documentation

```bash
scripts/context7.py docs "<library-id>" "[topic]" "[mode]"
```

**Parameters:**

- `library-id`: From search results (e.g., `/facebook/react`) or known library ID
- `topic`: Optional focus area (e.g., `hooks`, `routing`, `authentication`)
- `mode`: `code` (default) for API/examples, `info` for guides

**Version-Specific Docs:**

```bash
# Request specific version by adding it to the library ID
scripts/context7.py docs "/vercel/next.js/14" "middleware"

# Or mention in topic
scripts/context7.py docs "/facebook/react" "hooks in React 18"
```

**Examples:**

```bash
# Get React hooks documentation
scripts/context7.py docs "/facebook/react" "hooks"

# Get Next.js routing docs
scripts/context7.py docs "/vercel/next.js" "routing"

# Get conceptual guide (info mode)
scripts/context7.py docs "/vercel/next.js" "app router" info

# Get version-specific docs
scripts/context7.py docs "/vercel/next.js/14" "server components"
```

#### Step 3: Apply to User's Question

Use the returned documentation to:

1. Provide accurate, version-specific answers
2. Show official code patterns and examples
3. Reference correct API signatures
4. Include relevant caveats or deprecations
5. Cite the source URL when available

## Script Reference

| Command | Purpose | Example |
|---------|---------|---------|
| `search` | Find library ID | `scripts/context7.py search "prisma"` |
| `docs` | Fetch documentation | `scripts/context7.py docs "/prisma/prisma" "queries"` |

**Requirements:**

- Python 3.6+ (built-in on most systems)
- No external dependencies - uses Python standard library only

## Documentation Modes

| Mode | Use For | Example |
|------|---------|---------|
| `code` | API references, code examples, function signatures (default) | `scripts/context7.py docs "/facebook/react" "useState"` |
| `info` | Conceptual guides, tutorials, architecture docs | `scripts/context7.py docs "/vercel/next.js" "routing" info` |

## Example Workflow

```bash
# User asks: "How do I use React hooks?"

# Option A: If you know the library ID, skip search
scripts/context7.py docs "/facebook/react" "hooks"

# Option B: If you don't know the library ID
# Step 1: Search for React
scripts/context7.py search "react"
# Output shows: ID: /facebook/react

# Step 2: Fetch hooks docs
scripts/context7.py docs "/facebook/react" "hooks"

# Step 3: Use the returned documentation to answer
```

## Validation & Recovery

If results are unsatisfactory, follow this recovery workflow:

1. **Empty or irrelevant results?**
   - Try a broader topic (e.g., "hooks" instead of "useEffect cleanup")
   - Switch mode: use `info` if `code` returns nothing, or vice versa
   - Verify library ID is correct with a fresh search

2. **Library not found?**
   - Search with alternative names (e.g., "nextjs" vs "next.js")
   - Try the organization name (e.g., "vercel next")
   - Check for typos in the library ID format (`/org/repo`)

3. **Rate limited?**
   - Inform user about CONTEXT7_API_KEY for higher limits
   - Provide cached/general knowledge as fallback

**Always verify** the documentation matches the user's version requirements before providing answers.

## Common Use Cases

### Use Case 1: Direct Library Lookup

When you know the exact library the user is asking about:

```bash
# User: "Create a Next.js API route with authentication"
scripts/context7.py docs "/vercel/next.js" "api routes authentication"
```

### Use Case 2: Version-Specific Documentation

When the user mentions or needs a specific version:

```bash
# User: "How do I use Next.js 14 server actions?"
scripts/context7.py docs "/vercel/next.js/14" "server actions"

# Or search for the version
scripts/context7.py search "next.js 14"
```

### Use Case 3: Conceptual Understanding

When the user needs to understand concepts, not just code:

```bash
# User: "Explain how Next.js app router works"
scripts/context7.py docs "/vercel/next.js" "app router architecture" info
```

### Use Case 4: Discovery Search

When you're unsure which library the user means:

```bash
# User: "I need a database ORM for Node.js"
scripts/context7.py search "node.js ORM"
# Review results, pick most relevant (e.g., /prisma/prisma)
scripts/context7.py docs "/prisma/prisma" "getting started"
```

## Error Handling

If the script fails:

1. **Dependencies**: Verify Python 3.6+ is installed (`python3 --version`)
2. **Library ID format**: Check the format is `/org/project` (with leading slash)
3. **Topic too narrow**: Try a broader topic or no topic filter
4. **Wrong mode**: Try `info` mode if `code` returns insufficient results
5. **Network issues**: Check connectivity and firewall settings
6. **Rate limiting**: If using without API key, you may be rate-limited. Get a free key at [context7.com/dashboard](https://context7.com/dashboard)

**Debug mode:**

```bash
# Check Python version
python3 --version

# Test basic connectivity
python3 scripts/context7.py search "react"
```

## Notes

- **Script path**: All `scripts/context7.py` commands are relative to this skill's directory
- **No MCP overhead**: Uses REST API directly, no tool schemas in context
- **API key optional**: Works without key, but rate-limited. Get free key at [context7.com/dashboard](https://context7.com/dashboard)
- **Topic filtering**: Use specific topics for focused results
- **Search first (when needed)**: Search to find the correct library ID only if you don't know it
- **Skip search (when possible)**: Use known library IDs directly (e.g., `/facebook/react`, `/vercel/next.js`)
- **Caching**: Results are not cached; each call fetches fresh data
- **Version support**: Append version to library ID (e.g., `/vercel/next.js/14`) or mention in topic
- **Cross-platform**: Python 3.6+ works on Windows, macOS, and Linux
- **No external dependencies**: Uses only Python standard library

**Performance Tips:**

- Keep known library IDs in memory (React = `/facebook/react`, Next.js = `/vercel/next.js`, etc.)
- Skip search when you know the library
- Use specific topics to get focused results faster
- Use `code` mode (default) for implementation details, `info` mode for concepts

**Environment Variables:**

```bash
# Set API key (all platforms)
export CONTEXT7_API_KEY="your-api-key"

# Windows Command Prompt
set CONTEXT7_API_KEY=your-api-key

# Windows PowerShell
$env:CONTEXT7_API_KEY="your-api-key"
```

---

> **License:** MIT License - See LICENSE for complete terms
> **Author:** Arvind Menon
> **Based on:** Context7 REST API by Upstash


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### scripts/context7.py

```python
#!/usr/bin/env python3
"""
Context7 REST API wrapper - Cross-platform Python implementation
Based on @upstash/context7-mcp source

Usage:
    context7.py search <query>
    context7.py docs <library-id> [topic] [mode]

Examples:
    context7.py search react
    context7.py search "next.js app router"
    context7.py docs /facebook/react hooks
    context7.py docs /vercel/next.js routing
    context7.py docs /prisma/prisma queries info
"""

import sys
import json
import os
from urllib.request import Request, urlopen
from urllib.parse import quote
from urllib.error import HTTPError, URLError

BASE_URL = "https://context7.com/api/v2"
API_KEY = os.environ.get("CONTEXT7_API_KEY", "")


def make_request(url):
    """Make HTTP request with optional authentication.

    Args:
        url: The URL to request

    Returns:
        Response text as string

    Raises:
        SystemExit: On HTTP or URL errors
    """
    headers = {"X-Context7-Source": "claude-skill"}
    if API_KEY:
        headers["Authorization"] = f"Bearer {API_KEY}"

    try:
        req = Request(url, headers=headers)
        with urlopen(req) as response:
            return response.read().decode("utf-8")
    except HTTPError as e:
        print(f"HTTP Error {e.code}: {e.reason}", file=sys.stderr)
        if e.code == 404:
            print("Suggestions:", file=sys.stderr)
            print(
                "  - Verify the library ID format: /org/project (e.g., /facebook/react)",
                file=sys.stderr,
            )
            print(
                "  - Run 'context7.py search <name>' to find the correct library ID",
                file=sys.stderr,
            )
            print(
                "  - Try a broader search term if the library name is ambiguous",
                file=sys.stderr,
            )
        elif e.code == 429:
            print("Rate limited. Suggestions:", file=sys.stderr)
            print(
                "  - Set CONTEXT7_API_KEY environment variable for higher limits",
                file=sys.stderr,
            )
            print(
                "  - Get a free API key at: https://context7.com/dashboard",
                file=sys.stderr,
            )
            print("  - Wait a few minutes and retry", file=sys.stderr)
        elif e.code >= 500:
            print(
                "Server error. The Context7 service may be temporarily unavailable.",
                file=sys.stderr,
            )
            print("Try again in a few minutes.", file=sys.stderr)
        sys.exit(1)
    except URLError as e:
        print(f"URL Error: {e.reason}", file=sys.stderr)
        print("Suggestions:", file=sys.stderr)
        print("  - Check your internet connection", file=sys.stderr)
        print("  - Verify no firewall is blocking context7.com", file=sys.stderr)
        sys.exit(1)
    except Exception as e:
        print(f"Error: {e}", file=sys.stderr)
        sys.exit(1)


def search_library(query):
    """Search for library ID.

    Args:
        query: Search query string
    """
    if not query:
        print("Usage: context7.py search <query>", file=sys.stderr)
        print("Example: context7.py search react", file=sys.stderr)
        sys.exit(1)

    encoded_query = quote(query)
    url = f"{BASE_URL}/search?query={encoded_query}"

    print(f"Searching for: {query}")
    print("---")

    response_text = make_request(url)

    try:
        data = json.loads(response_text)
    except json.JSONDecodeError as e:
        print(f"Error parsing JSON response: {e}", file=sys.stderr)
        print(f"Raw response: {response_text}", file=sys.stderr)
        sys.exit(1)

    if "results" in data:
        for result in data["results"]:
            print(f"ID: {result['id']}")
            print(f"Name: {result.get('title', 'Unknown')}")
            print(
                f"Snippets: {result.get('totalSnippets', 'N/A')} | Score: {result.get('benchmarkScore', 'N/A')}"
            )
            desc = result.get("description", "No description")
            if len(desc) > 100:
                desc = desc[:100]
            print(f"Description: {desc}")
            print("---")
    elif "error" in data:
        print(f"Error: {data['error']}", file=sys.stderr)
        sys.exit(1)
    else:
        print(json.dumps(data, indent=2))


def fetch_docs(library_id, topic="", mode="code"):
    """Fetch documentation for a library.

    Args:
        library_id: Library ID (e.g., /facebook/react)
        topic: Optional focus area (e.g., hooks, routing)
        mode: 'code' for API/examples or 'info' for guides
    """
    if not library_id:
        print("Usage: context7.py docs <library-id> [topic] [mode]", file=sys.stderr)
        print("", file=sys.stderr)
        print("Arguments:", file=sys.stderr)
        print(
            "  library-id    Format: /org/project or /org/project/version",
            file=sys.stderr,
        )
        print(
            "  topic         Optional: Focus area (e.g., 'hooks', 'routing')",
            file=sys.stderr,
        )
        print("  mode          Optional: 'code' (default) or 'info'", file=sys.stderr)
        print("", file=sys.stderr)
        print("Examples:", file=sys.stderr)
        print("  context7.py docs /facebook/react hooks", file=sys.stderr)
        print("  context7.py docs /vercel/next.js routing code", file=sys.stderr)
        print('  context7.py docs /vercel/next.js "app router" info', file=sys.stderr)
        sys.exit(1)

    if mode not in ["code", "info"]:
        print("Error: mode must be 'code' or 'info'", file=sys.stderr)
        sys.exit(1)

    cleaned_id = library_id.lstrip("/")
    url = f"{BASE_URL}/docs/{mode}/{cleaned_id}?type=txt"

    if topic:
        encoded_topic = quote(topic)
        url += f"&topic={encoded_topic}"

    print(f"Fetching docs: /{cleaned_id}")
    if topic:
        print(f"Mode: {mode} | Topic: {topic}")
    else:
        print(f"Mode: {mode}")
    print("---")

    response_text = make_request(url)
    print(response_text)


def show_help():
    """Display help message."""
    print("Context7 Documentation Lookup")
    print("")
    print("Usage: context7.py <command> [args...]")
    print("")
    print("Commands:")
    print("  search <query>                    Search for library ID")
    print("  docs <library-id> [topic] [mode]  Fetch documentation")
    print("")
    print("Modes:")
    print("  code    API references and code examples (default)")
    print("  info    Conceptual guides and tutorials")
    print("")
    print("Examples:")
    print("  context7.py search react")
    print('  context7.py search "next.js app router"')
    print("  context7.py docs /facebook/react hooks")
    print("  context7.py docs /vercel/next.js routing")
    print("  context7.py docs /prisma/prisma queries info")
    print("")
    print("Environment:")
    print("  CONTEXT7_API_KEY    Optional API key for higher rate limits")
    print("                      Get one at: https://context7.com/dashboard")


def main():
    """Main entry point for the CLI."""
    if len(sys.argv) < 2:
        show_help()
        sys.exit(1)

    command = sys.argv[1]

    if command in ["-h", "--help", "help"]:
        show_help()
        sys.exit(0)
    elif command == "search":
        query = " ".join(sys.argv[2:])
        search_library(query)
    elif command == "docs":
        if len(sys.argv) < 3:
            print("Error: docs requires a library-id argument", file=sys.stderr)
            sys.exit(1)

        library_id = sys.argv[2]
        topic = sys.argv[3] if len(sys.argv) > 3 else ""
        mode = sys.argv[4] if len(sys.argv) > 4 else "code"

        fetch_docs(library_id, topic, mode)
    else:
        print(f"Unknown command: {command}", file=sys.stderr)
        print("", file=sys.stderr)
        show_help()
        sys.exit(1)


if __name__ == "__main__":
    main()

```