skill-seekers-reference/docs/guides/MIGRATION_GUIDE.md

Migration Guide

Version: 3.1.0-dev 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: v2.7.0

Supported Upgrade Paths:

• v2.6.0 → v2.7.0 (Latest)
• v2.5.0 → v2.6.0 or v2.7.0
• v2.1.0 → v2.5.0+
• v1.0.0 → v2.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]

---

v2.6.0 → v2.7.0 (Latest)

Release Date: January 18, 2026 Type: Minor release (backward compatible)

Summary of Changes

✅ Fully Backward Compatible - No breaking changes

• Code quality improvements (21 ruff fixes)
• Version synchronization
• Bug fixes (case-sensitivity, test fixtures)
• Documentation updates

What's New

1. Code Quality

   • All 21 ruff linting errors fixed
   • Zero linting errors across codebase
   • Improved code maintainability

2. Version Synchronization

   • All __init__.py files now show correct version
   • Fixed version mismatch bug (Issue #248)

3. Bug Fixes

   • Case-insensitive regex in install workflow (Issue #236)
   • Test fixture issues resolved
   • 1200+ tests passing (up from 700+)

4. Documentation

   • Comprehensive documentation overhaul
   • New API reference guide
   • Bootstrap skill documentation
   • Code quality standards
   • Testing guide

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 2.7.0

# Run tests (optional)
pytest tests/ -v

Compatibility

Feature	v2.6.0	v2.7.0	Notes
CLI commands	✅	✅	Fully compatible
Config files	✅	✅	No changes needed
MCP tools	17 tools	18 tools	enhance_skill added
Platform adaptors	✅	✅	No API changes
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):

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

After (v2.6.0 - opt-out):

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

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

3. Legacy Flags (Deprecated but Still Work)

Old flags still work but show warnings:

# Works with deprecation warning
skill-seekers codebase --directory . --build-api-reference

# Recommended: Remove old flags
skill-seekers codebase --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	4 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 unified --config configs/unified/react-unified.json

# GitHub analysis
skill-seekers github 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 scrape --config react
skill-seekers github https://github.com/facebook/react
skill-seekers 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 scrape --config react
skill-seekers package output/react/ --target claude
skill-seekers upload output/react-claude.zip --target claude

# Or use one command
skill-seekers install react --target claude --upload

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	4 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 scrape --config react

Issue 2: Config Validation Errors

Problem:

InvalidConfigError: Missing 'sources' key

Solution:

# Old configs still work for single-source
skill-seekers scrape --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 scrape --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==2.7.0

# Or use version range
skill-seekers>=2.7.0,<3.0.0

---

Rollback Instructions

If migration fails, rollback to previous version:

# Rollback to v2.6.0
pip install skill-seekers==2.6.0

# Rollback to v2.5.0
pip install skill-seekers==2.5.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:** 2.5.0
**New Version:** 2.7.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 scrape --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
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.1.0-dev Last Updated: 2026-02-18 Status: ✅ Production Ready