skill-seekers-reference/docs/FAQ.md

Frequently Asked Questions (FAQ)

Version: 2.7.0 Last Updated: 2026-01-18

---

General Questions

What is Skill Seekers?

Skill Seekers is a Python tool that converts documentation websites, GitHub repositories, and PDF files into AI skills for Claude AI, Google Gemini, OpenAI ChatGPT, and generic Markdown format.

Use Cases:

• Create custom documentation skills for your favorite frameworks
• Analyze GitHub repositories and extract code patterns
• Convert PDF manuals into searchable AI skills
• Combine multiple sources (docs + code + PDFs) into unified skills

Which platforms are supported?

Supported Platforms (4):

1. Claude AI - ZIP format with YAML frontmatter
2. Google Gemini - tar.gz format for Grounded Generation
3. OpenAI ChatGPT - ZIP format for Vector Stores
4. Generic Markdown - ZIP format with markdown files

Each platform has a dedicated adaptor for optimal formatting and upload.

Is it free to use?

Tool: Yes, Skill Seekers is 100% free and open-source (MIT license).

API Costs:

• Scraping: Free (just bandwidth)
• AI Enhancement (API mode): ~$0.15-0.30 per skill (Claude API)
• AI Enhancement (LOCAL mode): Free! (uses your Claude Code Max plan)
• Upload: Free (platform storage limits apply)

Recommendation: Use LOCAL mode for free AI enhancement or skip enhancement entirely.

How long does it take to create a skill?

Typical Times:

• Documentation scraping: 5-45 minutes (depends on size)
• GitHub analysis: 1-5 minutes (basic) or 20-60 minutes (C3.x deep analysis)
• PDF extraction: 30 seconds - 5 minutes
• AI enhancement: 30-60 seconds (LOCAL or API mode)
• Total workflow: 10-60 minutes

Speed Tips:

• Use --async for 2-3x faster scraping
• Use --skip-scrape to rebuild without re-scraping
• Skip AI enhancement for faster workflow

---

Installation & Setup

How do I install Skill Seekers?

# Basic installation
pip install skill-seekers

# With all platform support
pip install skill-seekers[all-llms]

# Development installation
git clone https://github.com/yusufkaraaslan/Skill_Seekers.git
cd Skill_Seekers
pip install -e ".[all-llms,dev]"

What Python version do I need?

Required: Python 3.10 or higher Tested on: Python 3.10, 3.11, 3.12, 3.13 OS Support: Linux, macOS, Windows (WSL recommended)

Check your version:

python --version  # Should be 3.10+

Why do I get "No module named 'skill_seekers'" error?

Common Causes:

1. Package not installed
2. Wrong Python environment

Solutions:

# Install package
pip install skill-seekers

# Or for development
pip install -e .

# Verify installation
skill-seekers --version

How do I set up API keys?

# Claude AI (for enhancement and upload)
export ANTHROPIC_API_KEY=sk-ant-...

# Google Gemini (for upload)
export GOOGLE_API_KEY=AIza...

# OpenAI ChatGPT (for upload)
export OPENAI_API_KEY=sk-...

# GitHub (for higher rate limits)
export GITHUB_TOKEN=ghp_...

# Make permanent (add to ~/.bashrc or ~/.zshrc)
echo 'export ANTHROPIC_API_KEY=sk-ant-...' >> ~/.bashrc

---

Usage Questions

How do I scrape documentation?

Using preset config:

skill-seekers scrape --config react

Using custom URL:

skill-seekers scrape --base-url https://docs.example.com --name my-framework

From custom config file:

skill-seekers scrape --config configs/my-framework.json

Can I analyze GitHub repositories?

Yes! Skill Seekers has powerful GitHub analysis:

# Basic analysis (fast)
skill-seekers github https://github.com/facebook/react

# Deep C3.x analysis (includes patterns, tests, guides)
skill-seekers github https://github.com/vercel/next.js --analysis-depth c3x

C3.x Features:

• Design pattern detection (10 GoF patterns)
• Test example extraction
• How-to guide generation
• Configuration pattern extraction
• Architectural overview
• API reference generation

Can I extract content from PDFs?

Yes! PDF extraction with OCR support:

# Basic PDF extraction
skill-seekers pdf manual.pdf --name product-manual

# With OCR (for scanned PDFs)
skill-seekers pdf scanned.pdf --enable-ocr

# Extract images and tables
skill-seekers pdf document.pdf --extract-images --extract-tables

Can I combine multiple sources?

Yes! Unified multi-source scraping:

Create unified config (configs/unified/my-framework.json):

{
  "name": "my-framework",
  "sources": {
    "documentation": {
      "type": "docs",
      "base_url": "https://docs.example.com"
    },
    "github": {
      "type": "github",
      "repo_url": "https://github.com/org/repo"
    },
    "pdf": {
      "type": "pdf",
      "pdf_path": "manual.pdf"
    }
  }
}

Run unified scraping:

skill-seekers unified --config configs/unified/my-framework.json

How do I upload skills to platforms?

# Upload to Claude AI
export ANTHROPIC_API_KEY=sk-ant-...
skill-seekers upload output/react-claude.zip --target claude

# Upload to Google Gemini
export GOOGLE_API_KEY=AIza...
skill-seekers upload output/react-gemini.tar.gz --target gemini

# Upload to OpenAI ChatGPT
export OPENAI_API_KEY=sk-...
skill-seekers upload output/react-openai.zip --target openai

Or use complete workflow:

skill-seekers install react --target claude --upload

---

Platform-Specific Questions

What's the difference between platforms?

Feature	Claude AI	Google Gemini	OpenAI ChatGPT	Markdown
Format	ZIP + YAML	tar.gz	ZIP	ZIP
Upload API	Projects API	Corpora API	Vector Stores	N/A
Model	Sonnet 4.5	Gemini 2.0 Flash	GPT-4o	N/A
Max Size	32MB	10MB	512MB	N/A
Use Case	Claude Code	Grounded Gen	ChatGPT Custom	Export

Choose based on:

• Claude AI: Best for Claude Code integration
• Google Gemini: Best for Grounded Generation in Gemini
• OpenAI ChatGPT: Best for ChatGPT Custom GPTs
• Markdown: Generic export for other tools

Can I use multiple platforms at once?

Yes! Package and upload to all platforms:

# Package for all platforms
for platform in claude gemini openai markdown; do
  skill-seekers package output/react/ --target $platform
done

# Upload to all platforms
skill-seekers install react --target claude,gemini,openai --upload

How do I use skills in Claude Code?

1. Install skill to Claude Code directory:

skill-seekers install-agent --skill-dir output/react/ --agent-dir ~/.claude/skills/react

2. Use in Claude Code:

Use the react skill to explain React hooks

3. Or upload to Claude AI:

skill-seekers upload output/react-claude.zip --target claude

---

Features & Capabilities

What is AI enhancement?

AI enhancement transforms basic skills (2-3/10 quality) into production-ready skills (8-9/10 quality) using LLMs.

Two Modes:

1. API Mode: Direct Claude API calls (fast, costs ~$0.15-0.30)
2. LOCAL Mode: Uses Claude Code CLI (free with your Max plan)

What it improves:

• Better organization and structure
• Clearer explanations
• More examples and use cases
• Better cross-references
• Improved searchability

Usage:

# API mode (if ANTHROPIC_API_KEY is set)
skill-seekers enhance output/react/

# LOCAL mode (free!)
skill-seekers enhance output/react/ --mode LOCAL

# Background mode
skill-seekers enhance output/react/ --background
skill-seekers enhance-status output/react/ --watch

What are C3.x features?

C3.x features are advanced codebase analysis capabilities:

• C3.1: Design pattern detection (Singleton, Factory, Strategy, etc.)
• C3.2: Test example extraction (real usage examples from tests)
• C3.3: How-to guide generation (educational guides from test workflows)
• C3.4: Configuration pattern extraction (env vars, config files)
• C3.5: Architectural overview (system architecture analysis)
• C3.6: AI enhancement (Claude API integration for insights)
• C3.7: Architectural pattern detection (MVC, MVVM, Repository, etc.)
• C3.8: Standalone codebase scraping (300+ line SKILL.md from code alone)

Enable C3.x:

# All C3.x features enabled by default
skill-seekers codebase --directory /path/to/repo

# Skip specific features
skill-seekers codebase --directory . --skip-patterns --skip-how-to-guides

What are router skills?

Router skills help Claude navigate large documentation (>500 pages) by providing a table of contents and keyword index.

When to use:

• Documentation with 500+ pages
• Complex multi-section docs
• Large API references

Generate router:

skill-seekers generate-router output/large-docs/

What preset configurations are available?

24 preset configs:

• Web: react, vue, angular, svelte, nextjs
• Python: django, flask, fastapi, sqlalchemy, pytest
• Game Dev: godot, pygame, unity
• DevOps: docker, kubernetes, terraform, ansible
• Unified: react-unified, vue-unified, nextjs-unified, etc.

List all:

skill-seekers list-configs

---

Troubleshooting

Scraping is very slow, how can I speed it up?

Solutions:

1. Use async mode (2-3x faster):

skill-seekers scrape --config react --async

2. Increase rate limit (faster requests):

{
  "rate_limit": 0.1  // Faster (but may hit rate limits)
}

3. Limit pages:

{
  "max_pages": 100  // Stop after 100 pages
}

Why are some pages missing?

Common Causes:

1. URL patterns exclude them
2. Max pages limit reached
3. BFS didn't reach them

Solutions:

# Check URL patterns in config
{
  "url_patterns": {
    "include": ["/docs/"],  // Make sure your pages match
    "exclude": []           // Remove overly broad exclusions
  }
}

# Increase max pages
{
  "max_pages": 1000  // Default is 500
}

# Use verbose mode to see what's being scraped
skill-seekers scrape --config react --verbose

How do I fix "NetworkError: Connection failed"?

Solutions:

1. Check internet connection
2. Verify URL is accessible:

curl -I https://docs.example.com

3. Increase timeout:

{
  "timeout": 30  // 30 seconds
}

4. Check rate limiting:

{
  "rate_limit": 1.0  // Slower requests
}

Tests are failing, what should I do?

Quick fixes:

# Ensure package is installed
pip install -e ".[all-llms,dev]"

# Clear caches
rm -rf .pytest_cache/ **/__pycache__/

# Run specific failing test
pytest tests/test_file.py::test_name -vv

# Check for missing dependencies
pip install -e ".[all-llms,dev]"

If still failing:

1. Check Troubleshooting Guide
2. Report issue on GitHub

---

MCP Server Questions

How do I start the MCP server?

# stdio mode (Claude Code, VS Code + Cline)
skill-seekers-mcp

# HTTP mode (Cursor, Windsurf, IntelliJ)
skill-seekers-mcp --transport http --port 8765

What MCP tools are available?

18 MCP tools:

1. list_configs - List preset configurations
2. generate_config - Generate config from docs URL
3. validate_config - Validate config structure
4. estimate_pages - Estimate page count
5. scrape_docs - Scrape documentation
6. package_skill - Package to .zip
7. upload_skill - Upload to platform
8. enhance_skill - AI enhancement
9. install_skill - Complete workflow
10. scrape_github - GitHub analysis
11. scrape_pdf - PDF extraction
12. unified_scrape - Multi-source scraping
13. merge_sources - Merge docs + code
14. detect_conflicts - Find discrepancies
15. split_config - Split large configs
16. generate_router - Generate router skills
17. add_config_source - Register git repos
18. fetch_config - Fetch configs from git

How do I configure MCP for Claude Code?

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "skill-seekers": {
      "command": "skill-seekers-mcp"
    }
  }
}

Restart Claude Code, then use:

Use skill-seekers MCP tools to scrape React documentation

---

Advanced Questions

Can I use Skill Seekers programmatically?

Yes! Full API for Python integration:

from skill_seekers.cli.doc_scraper import scrape_all, build_skill
from skill_seekers.cli.adaptors import get_adaptor

# Scrape documentation
pages = scrape_all(
    base_url='https://docs.example.com',
    selectors={'main_content': 'article'},
    config={'name': 'example'}
)

# Build skill
skill_path = build_skill(
    config_name='example',
    output_dir='output/example'
)

# Package for platform
adaptor = get_adaptor('claude')
package_path = adaptor.package(skill_path, 'output/')

See: API Reference

How do I create custom configurations?

Create config file (configs/my-framework.json):

{
  "name": "my-framework",
  "description": "My custom framework documentation",
  "base_url": "https://docs.example.com/",
  "selectors": {
    "main_content": "article",  // CSS selector
    "title": "h1",
    "code_blocks": "pre code"
  },
  "url_patterns": {
    "include": ["/docs/", "/api/"],
    "exclude": ["/blog/", "/changelog/"]
  },
  "categories": {
    "getting_started": ["intro", "quickstart"],
    "api": ["api", "reference"]
  },
  "rate_limit": 0.5,
  "max_pages": 500
}

Use config:

skill-seekers scrape --config configs/my-framework.json

Can I contribute preset configs?

Yes! We welcome config contributions:

1. Create config in configs/ directory
2. Test it thoroughly:

skill-seekers scrape --config configs/your-framework.json

3. Submit PR on GitHub

Guidelines:

• Name: {framework-name}.json
• Include all required fields
• Add to appropriate category
• Test with real documentation

How do I debug scraping issues?

# Verbose output
skill-seekers scrape --config react --verbose

# Dry run (no actual scraping)
skill-seekers scrape --config react --dry-run

# Single page test
skill-seekers scrape --base-url https://docs.example.com/intro --max-pages 1

# Check selectors
skill-seekers validate-config configs/react.json

---

Getting More Help

Where can I find documentation?

Main Documentation:

• README - Project overview
• Usage Guide - Detailed usage
• API Reference - Programmatic usage
• Troubleshooting - Common issues

Guides:

• MCP Setup
• Testing Guide
• Migration Guide
• Quick Reference

How do I report bugs?

1. Check existing issues: https://github.com/yusufkaraaslan/Skill_Seekers/issues
2. Create new issue with:
   • Skill Seekers version (skill-seekers --version)
   • Python version (python --version)
   • Operating system
   • Config file (if relevant)
   • Error message and stack trace
   • Steps to reproduce

How do I request features?

1. Check roadmap: ROADMAP.md
2. Create feature request: https://github.com/yusufkaraaslan/Skill_Seekers/issues
3. Join discussions: https://github.com/yusufkaraaslan/Skill_Seekers/discussions

Is there a community?

Yes!

• GitHub Discussions: https://github.com/yusufkaraaslan/Skill_Seekers/discussions
• Issue Tracker: https://github.com/yusufkaraaslan/Skill_Seekers/issues
• Project Board: https://github.com/users/yusufkaraaslan/projects/2

---

Version: 2.7.0 Last Updated: 2026-01-18 Questions? Ask on GitHub Discussions