yusufkaraaslan--skill_seekers/docs/guides/MIGRATION_GUIDE.md

Migration Guide

Version: 3.6.0 Last Updated: 2026-02-18 Status: ✅ Production Ready

---

Overview

This guide helps you upgrade Skill Seekers between major versions. Each section covers breaking changes, new features, and step-by-step migration instructions.

Current Version: v3.6.0

Supported Upgrade Paths:

• v3.5.0 → v3.6.0 (Latest)
• v3.0.0 → v3.5.0 or v3.6.0
• v2.7.0 → v3.6.0
• v2.5.0 → v2.7.0 or v3.6.0
• v2.1.0 → v2.5.0+
• v1.0.0 → v2.x.0 or v3.x.0

---

Quick Version Check

# Check installed version
skill-seekers --version

# Check for updates
pip show skill-seekers | grep Version

# Upgrade to latest
pip install --upgrade skill-seekers[all-llms]

---

v3.5.0 → v3.6.0 (Latest)

Release Date: May 2026 Type: Minor release (backward compatible)

Summary of Changes

✅ Fully Backward Compatible - No breaking changes

• 40 MCP tools (up from 27)
• 21 package targets (up from 12)
• 18 source types (17 + config)
• 19 CLI commands
• Documentation overhaul and version synchronization

What's New

1. MCP Expansion

   • 40 comprehensive MCP tools (up from 27)
   • FastMCP-based server with stdio + HTTP transports
   • Marketplace tools, workflow tools, vector DB exports

2. Platform Expansion

   • 21 package targets (up from 12)
   • New: IBM Bob, LangChain, LlamaIndex, Haystack, Pinecone, Weaviate, Chroma, FAISS, Qdrant

3. Source Types

   • 17 source types + unified config type = 18 total
   • Generic scraper delegates to all source types

4. CLI Commands

   • 19 total commands: create, scan, doctor, enhance, package, upload, install, install-agent, estimate, split, workflows, and source-specific commands

Migration Steps

No migration required! This is a drop-in replacement.

# Upgrade
pip install --upgrade skill-seekers[all-llms]

# Verify
skill-seekers --version  # Should show 3.6.0

# Run tests (optional)
pytest tests/ -v

Compatibility

Feature	v3.5.0	v3.6.0	Notes
CLI commands	✅	✅	Fully compatible
Config files	✅	✅	No changes needed
MCP tools	27 tools	40 tools	Additive only
Platform adaptors	12	21	Opt-in new targets
Python versions	3.10-3.13	3.10-3.13	Same support

---

v2.5.0 → v2.6.0

Release Date: January 14, 2026 Type: Minor release

Summary of Changes

✅ Mostly Backward Compatible - One minor breaking change

Breaking Change:

• Codebase analysis features changed from opt-in (--build-*) to opt-out (--skip-*)
• Default behavior: All C3.x features enabled

What's New

1. C3.x Codebase Analysis Suite (C3.1-C3.8)

   • Pattern detection (10 GoF patterns, 9 languages)
   • Test example extraction
   • How-to guide generation
   • Configuration extraction
   • Architectural overview
   • Architectural pattern detection
   • API reference + dependency graphs

2. Multi-Platform Support

   • Claude AI, Google Gemini, OpenAI ChatGPT, Generic Markdown
   • Platform adaptor architecture
   • Unified packaging and upload

3. MCP Expansion

   • 18 MCP tools (up from 9)
   • New tools: enhance_skill, merge_sources, etc.

4. Test Improvements

   • 700+ tests passing
   • Improved test coverage

Migration Steps

1. Upgrade Package

pip install --upgrade skill-seekers[all-llms]

2. Update Codebase Analysis Commands

Before (v2.5.0 - opt-in, old codebase subcommand):

# Had to enable features explicitly
skill-seekers codebase --directory . --build-api-reference --build-dependency-graph

After (current — opt-out, via the unified create command):

# All features enabled by default
skill-seekers create --directory .

# Or skip specific features
skill-seekers create --directory . --skip-patterns --skip-how-to-guides

3. Legacy Flags (Removed)

The old codebase subcommand and the --build-* opt-in flags are gone — use create with --skip-* flags instead:

# Everything on by default
skill-seekers create --directory .

4. Verify MCP Configuration

If using MCP server, note new tools:

# Test new enhance_skill tool
python -m skill_seekers.mcp.server

# In Claude Code:
# "Use enhance_skill tool to improve the react skill"

Compatibility

Feature	v2.5.0	v2.6.0	Migration Required
CLI commands	✅	✅	No
Config files	✅	✅	No
Codebase flags	--build-*	--skip-*	Yes (but backward compatible)
MCP tools	9 tools	18 tools	No (additive)
Platform support	Claude only	12 platforms	No (opt-in)

---

v2.1.0 → v2.5.0

Release Date: November 29, 2025 Type: Minor release

Summary of Changes

✅ Backward Compatible

• Unified multi-source scraping
• GitHub repository analysis
• PDF extraction
• Test coverage improvements

What's New

1. Unified Scraping

   • Combine docs + GitHub + PDF
   • Conflict detection
   • Smart merging

2. GitHub Integration

   • Full repository analysis
   • Unlimited local analysis (no API limits)

3. PDF Support

   • Extract from PDF documents
   • OCR for scanned PDFs
   • Image extraction

4. Testing

   • 427 tests passing
   • Improved coverage

Migration Steps

# Upgrade
pip install --upgrade skill-seekers

# New unified scraping
skill-seekers create --config configs/unified/react-unified.json

# GitHub analysis
skill-seekers create https://github.com/facebook/react

Compatibility

All v2.1.0 commands work in v2.5.0. New features are additive.

---

v1.0.0 → v2.0.0+

Release Date: October 19, 2025 → Present Type: Major version upgrade

Summary of Changes

⚠️ Major Changes - Some breaking changes

Breaking Changes:

1. CLI structure changed to git-style
2. Config format updated for unified scraping
3. MCP server architecture redesigned

What Changed

1. CLI Structure (Breaking)

Before (v1.0.0):

# Separate commands
doc-scraper --config react.json
github-scraper https://github.com/facebook/react
pdf-scraper manual.pdf

After (v2.0.0+):

# Unified CLI
skill-seekers create --config react
skill-seekers create https://github.com/facebook/react
skill-seekers create --pdf manual.pdf

Migration:

• Replace command prefixes with skill-seekers <subcommand>
• Update scripts/CI/CD workflows

2. Config Format (Additive)

v1.0.0 Config:

{
  "name": "react",
  "base_url": "https://react.dev",
  "selectors": {...}
}

v2.0.0+ Unified Config:

{
  "name": "react",
  "sources": {
    "documentation": {
      "type": "docs",
      "base_url": "https://react.dev",
      "selectors": {...}
    },
    "github": {
      "type": "github",
      "repo_url": "https://github.com/facebook/react"
    }
  }
}

Migration:

• Old configs still work for single-source scraping
• Use new format for multi-source scraping

3. MCP Server (Breaking)

Before (v1.0.0):

• 9 basic MCP tools
• stdio transport only

After (v2.0.0+):

• 18 comprehensive MCP tools
• stdio + HTTP transports
• FastMCP framework

Migration:

• Update MCP server configuration in claude_desktop_config.json
• Use skill-seekers-mcp instead of custom server script

Migration Steps

Step 1: Upgrade Package

# Uninstall old version
pip uninstall skill-seekers

# Install latest
pip install skill-seekers[all-llms]

# Verify
skill-seekers --version

Step 2: Update Scripts

Before:

#!/bin/bash
doc-scraper --config react.json
package-skill output/react/ claude
upload-skill output/react-claude.zip

After:

#!/bin/bash
skill-seekers create --config react
skill-seekers package output/react/ --target claude
skill-seekers upload output/react-claude.zip --target claude

# Or use one command (uploads by default)
skill-seekers install --config react --target claude

Step 3: Update Configs (Optional)

Convert to unified format:

# Old config (still works)
{
  "name": "react",
  "base_url": "https://react.dev"
}

# New unified config (recommended)
{
  "name": "react",
  "sources": {
    "documentation": {
      "type": "docs",
      "base_url": "https://react.dev"
    }
  }
}

Step 4: Update MCP Configuration

Before (claude_desktop_config.json):

{
  "mcpServers": {
    "skill-seekers": {
      "command": "python",
      "args": ["/path/to/mcp_server.py"]
    }
  }
}

After:

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

Compatibility

Feature	v1.0.0	v2.0.0+	Migration
CLI commands	Separate	Unified	Update scripts
Config format	Basic	Unified	Old still works
MCP server	9 tools	18 tools	Update config
Platforms	Claude only	12 platforms	Opt-in

---

Common Migration Issues

Issue 1: Command Not Found

Problem:

doc-scraper --config react.json
# command not found: doc-scraper

Solution:

# Use new CLI
skill-seekers create --config react

Issue 2: Config Validation Errors

Problem:

InvalidConfigError: Missing 'sources' key

Solution:

# Old configs still work for single-source
skill-seekers create --config configs/react.json

# Or convert to unified format
# Add 'sources' wrapper

Issue 3: MCP Server Not Starting

Problem:

ModuleNotFoundError: No module named 'skill_seekers.mcp'

Solution:

# Reinstall with latest version
pip install --upgrade skill-seekers[all-llms]

# Use correct command
skill-seekers-mcp

Issue 4: API Key Errors

Problem:

APIError: Invalid API key

Solution:

# Set environment variables
export ANTHROPIC_API_KEY=sk-ant-...
export GOOGLE_API_KEY=AIza...
export OPENAI_API_KEY=sk-...

# Verify
echo $ANTHROPIC_API_KEY

---

Best Practices for Migration

1. Test in Development First

# Create test environment
python -m venv test-env
source test-env/bin/activate

# Install new version
pip install skill-seekers[all-llms]

# Test your workflows
skill-seekers create --config react --dry-run

2. Backup Existing Configs

# Backup before migration
cp -r configs/ configs.backup/
cp -r output/ output.backup/

3. Update in Stages

# Stage 1: Upgrade package
pip install --upgrade skill-seekers[all-llms]

# Stage 2: Update CLI commands
# Update scripts one by one

# Stage 3: Test workflows
pytest tests/ -v

# Stage 4: Update production

4. Version Pinning in Production

# Pin to specific version in requirements.txt
skill-seekers==3.6.0

# Or use version range
skill-seekers>=3.5.0,<4.0.0

---

Rollback Instructions

If migration fails, rollback to previous version:

# Rollback to v3.5.0
pip install skill-seekers==3.5.0

# Rollback to v2.7.0
pip install skill-seekers==2.7.0

# Restore configs
cp -r configs.backup/* configs/

---

Getting Help

Resources

• CHANGELOG - Full version history
• Troubleshooting - Common issues
• GitHub Issues - Report problems
• Discussions - Ask questions

Reporting Migration Issues

When reporting migration issues:

1. Include both old and new versions
2. Provide config files (redact sensitive data)
3. Share error messages and stack traces
4. Describe what worked before vs. what fails now

Issue Template:

**Old Version:** 3.5.0
**New Version:** 3.6.0
**Python Version:** 3.11.7
**OS:** Ubuntu 22.04

**What I did:**
1. Upgraded with pip install --upgrade skill-seekers
2. Ran skill-seekers create --config react

**Expected:** Scraping completes successfully
**Actual:** Error: ...

**Error Message:**
[paste full error]

**Config File:**
[paste config.json]

---

Version History

Version	Release Date	Type	Key Changes
v3.6.0	2026-05-30	Minor	40 MCP tools, 21 platforms, 18 source types
v3.5.0	2026-04-09	Minor	MCP expansion, docs overhaul
v3.2.0	2026-03-15	Minor	17 source types, generic scraper
v3.1.0	2026-02-18	Minor	Enhancement workflows, bootstrap skill
v2.7.0	2026-01-18	Minor	Code quality, bug fixes, docs
v2.6.0	2026-01-14	Minor	C3.x suite, multi-platform
v2.5.0	2025-11-29	Minor	Unified scraping, GitHub, PDF
v2.1.0	2025-10-19	Minor	Test coverage, quality
v1.0.0	2025-10-19	Major	Production release

---

Version: 3.6.0 Last Updated: 2026-02-18 Status: ✅ Production Ready