github yusufkaraaslan/Skill_Seekers v2.7.0
v2.7.0 - Smart Rate Limits, Multi-Token Config & Documentation Overhaul
on GitHub

7 hours ago

[2.7.0] - 2026-01-18

🔐 Smart Rate Limit Management & Multi-Token Configuration

This minor feature release introduces intelligent GitHub rate limit handling, multi-profile token management, and comprehensive configuration system. Say goodbye to indefinite waits and confusing token setup!

Added

  • 🎯 Multi-Token Configuration System - Flexible GitHub token management with profiles

    • Secure config storage at ~/.config/skill-seekers/config.json with 600 permissions
    • Multiple GitHub profiles support (personal, work, OSS, etc.)
      • Per-profile rate limit strategies: prompt, wait, switch, fail
      • Configurable timeout per profile (default: 30 minutes)
      • Auto-detection and smart fallback chain
      • Profile switching when rate limited
    • API key management for Claude, Gemini, OpenAI
      • Environment variable fallback (ANTHROPIC_API_KEY, GOOGLE_API_KEY, OPENAI_API_KEY)
      • Config file storage with secure permissions
    • Progress tracking for resumable jobs
      • Auto-save at configurable intervals (default: 60 seconds)
      • Job metadata: command, progress, checkpoints, timestamps
      • Stored at ~/.local/share/skill-seekers/progress/
    • Auto-cleanup of old progress files (default: 7 days, configurable)
    • First-run experience with welcome message and quick setup
    • ConfigManager class with singleton pattern for global access

  • 🧙 Interactive Configuration Wizard - Beautiful terminal UI for easy setup

    • Main menu with 7 options:
      1. GitHub Token Setup
      2. API Keys (Claude, Gemini, OpenAI)
      3. Rate Limit Settings
      4. Resume Settings
      5. View Current Configuration
      6. Test Connections
      7. Clean Up Old Progress Files
    • GitHub token management:
      • Add/remove profiles with descriptions
      • Set default profile
      • Browser integration - opens GitHub token creation page
      • Token validation with format checking (ghp_, github_pat_)
      • Strategy selection per profile
    • API keys setup with browser integration for each provider
    • Connection testing to verify tokens and API keys
    • Configuration display with current status and sources
    • CLI commands:
      • skill-seekers config - Main menu
      • skill-seekers config --github - Direct to GitHub setup
      • skill-seekers config --api-keys - Direct to API keys
      • skill-seekers config --show - Show current config
      • skill-seekers config --test - Test connections

  • 🚦 Smart Rate Limit Handler - Intelligent GitHub API rate limit management

    • Upfront warning about token status (60/hour vs 5000/hour)
    • Real-time detection of rate limits from GitHub API responses
      • Parses X-RateLimit-* headers
      • Detects 403 rate limit errors
      • Calculates reset time from timestamps
    • Live countdown timers with progress display
    • Automatic profile switching - tries next available profile when rate limited
    • Four rate limit strategies:
      • prompt - Ask user what to do (default, interactive)
      • wait - Auto-wait with countdown timer
      • switch - Automatically try another profile
      • fail - Fail immediately with clear error
    • Non-interactive mode for CI/CD (fail fast, no prompts)
    • Configurable timeouts per profile (prevents indefinite waits)
    • RateLimitHandler class with strategy pattern
    • Integration points: GitHub fetcher, GitHub scraper

  • 📦 Resume Command - Resume interrupted scraping jobs

    • List resumable jobs with progress details:
      • Job ID, started time, command
      • Current phase and file counts
      • Last updated timestamp
    • Resume from checkpoints (skeleton implemented, ready for integration)
    • Auto-cleanup of old jobs (respects config settings)
    • CLI commands:
      • skill-seekers resume --list - List all resumable jobs
      • skill-seekers resume <job-id> - Resume specific job
      • skill-seekers resume --clean - Clean up old jobs
    • Progress storage at ~/.local/share/skill-seekers/progress/<job-id>.json

  • ⚙️ CLI Enhancements - New flags and improved UX

    • --non-interactive flag for CI/CD mode
      • Available on: skill-seekers github
      • Fails fast on rate limits instead of prompting
      • Perfect for automated pipelines
    • --profile flag to select specific GitHub profile
      • Available on: skill-seekers github
      • Uses configured profile from ~/.config/skill-seekers/config.json
      • Overrides environment variables and defaults
    • Entry points for new commands:
      • skill-seekers-config - Direct config command access
      • skill-seekers-resume - Direct resume command access

  • 🧪 Comprehensive Test Suite - Full test coverage for new features

    • 16 new tests in test_rate_limit_handler.py
    • Test coverage:
      • Header creation (with/without token)
      • Handler initialization (token, strategy, config)
      • Rate limit detection and extraction
      • Upfront checks (interactive and non-interactive)
      • Response checking (200, 403, rate limit)
      • Strategy handling (fail, wait, switch, prompt)
      • Config manager integration
      • Profile management (add, retrieve, switch)
    • All tests passing ✅ (16/16)
    • Test utilities: Mock responses, config isolation, tmp directories

  • 🎯 Bootstrap Skill Feature - Self-hosting capability (PR #249)

    • Self-Bootstrap: Generate skill-seekers as a Claude Code skill
      • ./scripts/bootstrap_skill.sh - One-command bootstrap
      • Combines manual header with auto-generated codebase analysis
      • Output: output/skill-seekers/ ready for Claude Code
      • Install: cp -r output/skill-seekers ~/.claude/skills/
    • Robust Frontmatter Detection:
      • Dynamic YAML frontmatter boundary detection (not hardcoded line counts)
      • Fallback to line 6 if frontmatter not found
      • Future-proof against frontmatter field additions
    • SKILL.md Validation:
      • File existence and non-empty checks
      • Frontmatter delimiter presence
      • Required fields validation (name, description)
      • Exit with clear error messages on validation failures
    • Comprehensive Error Handling:
      • UV dependency check with install instructions
      • Permission checks for output directory
      • Graceful degradation on missing header file

  • 🔧 MCP Now Optional - User choice for installation profile

    • CLI Only: pip install skill-seekers - No MCP dependencies
    • MCP Integration: pip install skill-seekers[mcp] - Full MCP support
    • All Features: pip install skill-seekers[all] - Everything enabled
    • Lazy Loading: Graceful failure with helpful error messages when MCP not installed
    • Interactive Setup Wizard:
      • Shows all installation options on first run
      • Stored at ~/.config/skill-seekers/.setup_shown
      • Accessible via skill-seekers-setup command
    • Entry Point: skill-seekers-setup for manual access

  • 🧪 E2E Testing for Bootstrap - Comprehensive end-to-end tests

    • 6 core tests verifying bootstrap workflow:
      • Output structure creation
      • Header prepending
      • YAML frontmatter validation
      • Line count sanity checks
      • Virtual environment installability
      • Platform adaptor compatibility
    • Pytest markers: @pytest.mark.e2e, @pytest.mark.venv, @pytest.mark.slow
    • Execution modes:
      • Fast tests: pytest -k "not venv" (~2-3 min)
      • Full suite: pytest -m "e2e" (~5-10 min)
    • Test utilities: Fixtures for project root, bootstrap runner, output directory

  • 📚 Comprehensive Documentation Overhaul - Complete v2.7.0 documentation update

    • 7 new documentation files (~3,750 lines total):
      • docs/reference/API_REFERENCE.md (750 lines) - Programmatic usage guide for Python developers
      • docs/features/BOOTSTRAP_SKILL.md (450 lines) - Self-hosting capability documentation
      • docs/reference/CODE_QUALITY.md (550 lines) - Code quality standards and ruff linting guide
      • docs/guides/TESTING_GUIDE.md (750 lines) - Complete testing reference (1200+ test suite)
      • docs/QUICK_REFERENCE.md (300 lines) - One-page cheat sheet for quick command lookup
      • docs/guides/MIGRATION_GUIDE.md (400 lines) - Version upgrade guides (v1.0.0 → v2.7.0)
      • docs/FAQ.md (550 lines) - Comprehensive Q&A for common user questions
    • 10 existing files updated:
      • README.md - Updated test count badge (700+ → 1200+ tests), v2.7.0 callout
      • ROADMAP.md - Added v2.7.0 completion section with task statuses
      • CONTRIBUTING.md - Added link to CODE_QUALITY.md reference
      • docs/README.md - Quick links by use case, recent updates section
      • docs/guides/MCP_SETUP.md - Fixed server_fastmcp references (PR #252)
      • docs/QUICK_REFERENCE.md - Updated MCP server reference (server.py → server_fastmcp.py)
      • CLAUDE_INTEGRATION.md - Updated version references
      • 3 other documentation files with v2.7.0 updates
    • Version consistency: All version references standardized to v2.7.0
    • Test counts: Standardized to 1200+ tests (was inconsistent 700+ in some docs)
    • MCP tool counts: Updated to 18 tools (from 17)

  • 📦 Git Submodules for Configuration Management - Improved config organization and API deployment

    • Configs as git submodule at api/configs_repo/ for cleaner repository
    • Production configs: Added official production-ready configuration presets
    • Duplicate removal: Cleaned up all duplicate configs from main repository
    • Test filtering: Filtered out test-example configs from API endpoints
    • CI/CD integration: GitHub Actions now initializes submodules automatically
    • API deployment: Updated render.yaml to use git submodule for configs_repo
    • Benefits: Cleaner main repo, better config versioning, production/test separation

  • 🔍 Config Discovery Enhancements - Improved config listing

    • --all flag for estimate command: skill-seekers estimate --all
    • Lists all available preset configurations with descriptions
    • Helps users discover supported frameworks before scraping
    • Shows config names, frameworks, and documentation URLs

Changed

  • GitHub Fetcher - Integrated rate limit handler

    • Modified github_fetcher.py to use RateLimitHandler
    • Added upfront rate limit check before starting
    • Check responses for rate limits on all API calls
    • Automatic profile detection from config
    • Raises RateLimitError when rate limit cannot be handled
    • Constructor now accepts interactive and profile_name parameters

  • GitHub Scraper - Added rate limit support

    • New --non-interactive flag for CI/CD mode
    • New --profile flag to select GitHub profile
    • Config now supports interactive and github_profile keys
    • CLI argument passing for non-interactive and profile options

  • Main CLI - Enhanced with new commands

    • Added config subcommand with options (--github, --api-keys, --show, --test)
    • Added resume subcommand with options (--list, --clean)
    • Updated GitHub subcommand with --non-interactive and --profile flags
    • Updated command documentation strings
    • Version bumped to 2.7.0

  • pyproject.toml - New entry points and dependency restructuring

    • Added skill-seekers-config entry point
    • Added skill-seekers-resume entry point
    • Added skill-seekers-setup entry point for setup wizard
    • MCP moved to optional dependencies - Now requires pip install skill-seekers[mcp]
    • Updated pytest markers: e2e, venv, bootstrap, slow
    • Version updated to 2.7.0

  • install_skill.py - Lazy MCP loading

    • Try/except ImportError for MCP imports
    • Graceful failure with helpful error message when MCP not installed
    • Suggests alternatives: scrape + package workflow
    • Maintains backward compatibility for existing MCP users

Fixed

  • Code Quality Improvements - Fixed all 21 ruff linting errors across codebase

    • SIM102: Combined nested if statements using and operator (7 fixes)
    • SIM117: Combined multiple with statements into single multi-context with (9 fixes)
    • B904: Added from e to exception chaining for proper error context (1 fix)
    • SIM113: Removed unused enumerate counter variable (1 fix)
    • B007: Changed unused loop variable to _ (1 fix)
    • ARG002: Removed unused method argument in test fixture (1 fix)
    • Files affected: config_extractor.py, config_validator.py, doc_scraper.py, pattern_recognizer.py (3), test_example_extractor.py (3), unified_skill_builder.py, pdf_scraper.py, and 6 test files
    • Result: Zero linting errors, cleaner code, better maintainability

  • Version Synchronization - Fixed version mismatch across package (Issue #248)

    • All __init__.py files now correctly show version 2.7.0 (was 2.5.2 in 4 files)
    • Files updated: src/skill_seekers/__init__.py, src/skill_seekers/cli/__init__.py, src/skill_seekers/mcp/__init__.py, src/skill_seekers/mcp/tools/__init__.py
    • Ensures skill-seekers --version shows accurate version number
    • Critical: Prevents bug where PyPI shows wrong version (Issue #248)

  • Case-Insensitive Regex in Install Workflow - Fixed install workflow failures (Issue #236)

    • Made regex patterns case-insensitive using (?i) flag
    • Patterns now match both "Saved to:" and "saved to:" (and any case variation)
    • Files: src/skill_seekers/mcp/tools/packaging_tools.py (lines 529, 668)
    • Impact: install_skill workflow now works reliably regardless of output formatting

  • Test Fixture Error - Fixed pytest fixture error in bootstrap skill tests

    • Removed unused tmp_path parameter causing fixture lookup errors
    • File: tests/test_bootstrap_skill.py:54
    • Result: All CI test runs now pass without fixture errors

  • MCP Setup Modernization - Updated MCP server configuration (PR #252, @MiaoDX)

    • Fixed 41 instances of server_fastmcp_fastmcp → server_fastmcp typo in docs/guides/MCP_SETUP.md
    • Updated all 12 files to use skill_seekers.mcp.server_fastmcp module
    • Enhanced setup_mcp.sh with automatic venv detection (.venv, venv, $VIRTUAL_ENV)
    • Updated tests to accept -e ".[mcp]" format and module references
    • Files: .claude/mcp_config.example.json, CLAUDE.md, README.md, docs/guides/*.md, setup_mcp.sh, tests/test_setup_scripts.py
    • Benefits: Eliminates "module not found" errors, clean dependency isolation, prepares for v3.0.0

  • Rate limit indefinite wait - No more infinite waiting

    • Configurable timeout per profile (default: 30 minutes)
    • Clear error messages when timeout exceeded
    • Graceful exit with helpful next steps
    • Resume capability for interrupted jobs

  • Token setup confusion - Clear, guided setup process

    • Interactive wizard with browser integration
    • Token validation with helpful error messages
    • Clear documentation of required scopes
    • Test connection feature to verify tokens work

  • CI/CD failures - Non-interactive mode support

    • --non-interactive flag fails fast instead of hanging
    • No user prompts in non-interactive mode
    • Clear error messages for automation logs
    • Exit codes for pipeline integration

  • AttributeError in codebase_scraper.py - Fixed incorrect flag check (PR #249)

    • Changed if args.build_api_reference: to if not args.skip_api_reference:
    • Aligns with v2.5.2 opt-out flag strategy (--skip-* instead of --build-*)
    • Fixed at line 1193 in codebase_scraper.py

Technical Details

  • Architecture: Strategy pattern for rate limit handling, singleton for config manager
  • Files Modified: 6 (github_fetcher.py, github_scraper.py, main.py, pyproject.toml, install_skill.py, codebase_scraper.py)
  • New Files: 6 (config_manager.py ~490 lines, config_command.py ~400 lines, rate_limit_handler.py ~450 lines, resume_command.py ~150 lines, setup_wizard.py ~95 lines, test_bootstrap_skill_e2e.py ~169 lines)
  • Bootstrap Scripts: 2 (bootstrap_skill.sh enhanced, skill_header.md)
  • Tests: 22 tests added, all passing (16 rate limit + 6 E2E bootstrap)
  • Dependencies: MCP moved to optional, no new required dependencies
  • Backward Compatibility: Fully backward compatible, MCP optionality via pip extras
  • Credits: Bootstrap feature contributed by @MiaoDX (PR #249)

Migration Guide

Existing users - No migration needed! Everything works as before.

MCP users - If you use MCP integration features: 

# Reinstall with MCP support
pip install -U skill-seekers[mcp]

# Or install everything
pip install -U skill-seekers[all]

New installation profiles: 

# CLI only (no MCP)
pip install skill-seekers

# With MCP integration
pip install skill-seekers[mcp]

# With multi-LLM support (Gemini, OpenAI)
pip install skill-seekers[all-llms]

# Everything
pip install skill-seekers[all]

# See all options
skill-seekers-setup

To use new features: 

# Set up GitHub token (one-time)
skill-seekers config --github

# Add multiple profiles
skill-seekers config
# → Select "1. GitHub Token Setup"
# → Select "1. Add New Profile"

# Use specific profile
skill-seekers github --repo owner/repo --profile work

# CI/CD mode
skill-seekers github --repo owner/repo --non-interactive

# View configuration
skill-seekers config --show

# Bootstrap skill-seekers as a Claude Code skill
./scripts/bootstrap_skill.sh
cp -r output/skill-seekers ~/.claude/skills/

Breaking Changes

None - this release is fully backward compatible.

Check out latest releases or
releases around yusufkaraaslan/Skill_Seekers v2.7.0

Don't miss a new Skill_Seekers release

NewReleases is sending notifications on new releases.

Get notifications