Major enhancement release focusing on quality and reliability:
## Key Features
### Comprehensive Quality Checker
- Automatic quality validation before packaging
- Quality scoring system (0-100 + A-F grades)
- Enhancement verification (code examples, sections)
- Structure validation (SKILL.md, references/)
- Content quality checks (frontmatter, language tags)
- Link validation (internal markdown links)
- Detailed reporting with errors, warnings, and info
### Headless Enhancement Mode (Default)
- Runs enhancement in background (no terminal windows)
- Main console waits for completion (no race conditions)
- 10-minute timeout protection (configurable)
- Verification that SKILL.md was actually updated
- Interactive mode still available via --interactive-enhancement
## Statistics
- 391 tests passing (up from 379)
- +12 quality checker tests
- All CI checks passing
- 5 commits in this release
## Breaking Changes
- Enhancement now runs in headless mode by default
- Use --interactive-enhancement for old terminal mode behavior
See CHANGELOG.md for full details and migration guide.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
The terminal detection tests were failing because they expected the old
terminal mode behavior, but headless mode is now the default.
Fix:
- Add headless=False parameter to all terminal detection tests
- Tests now explicitly test interactive (terminal) mode
- test_subprocess_popen_called_with_correct_args: Tests terminal launch
- test_terminal_launch_error_handling: Tests error handling
- test_output_message_unknown_terminal: Tests warning messages
These tests only run on macOS (they're skipped on Linux) and test the
interactive terminal launch functionality, so they need headless=False.
Impact:
- All 3 failing macOS tests should now pass
- 391 tests passing on Linux
- CI should pass on macOS now
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
The MCP server's package_skill_tool was failing in CI because the quality
checker was prompting for user input, which doesn't exist in CI/MCP contexts.
Fix:
- Add --skip-quality-check flag to package_skill command in MCP server
- This prevents interactive prompts that cause EOFError in CI
- MCP tools should skip interactive checks since they run in background
Impact:
- All 25 MCP server tests now pass
- All 391 tests passing
- CI builds will succeed
Context:
- Quality checks are interactive by default for CLI users
- MCP server runs commands programmatically without user input
- This is the correct behavior: interactive for CLI, non-interactive for MCP
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Phase 4: Testing and verification
New test file: test_quality_checker.py
- 12 comprehensive tests for quality checker functionality
- Tests for structure validation (missing SKILL.md, missing references)
- Tests for enhancement verification (template indicators, code examples)
- Tests for content quality (YAML frontmatter, language tags)
- Tests for link validation (broken internal links)
- Tests for quality scoring and grading system
- Tests for is_excellent property
- CLI tests (help output, nonexistent directory)
Updated test_package_skill.py:
- Added skip_quality_check=True to all test calls
- Fixes OSError "reading from stdin while output is captured"
- All 9 package_skill tests passing
Test Results:
- 391 tests passing (up from 386 before)
- 32 skipped
- 0 failures
- Added 12 new quality checker tests
- All existing tests still passing
Completes Phase 4 of enhancement race condition fix.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Phase 2 & 3: Quality assurance before packaging
New module: quality_checker.py
- Enhancement verification (checks for template text, code examples, sections)
- Structure validation (SKILL.md, references/ directory)
- Content quality checks (YAML frontmatter, language tags, "When to Use" section)
- Link validation (internal markdown links)
- Quality scoring system (0-100 score + A-F grade)
- Detailed reporting with errors, warnings, and info messages
- CLI with --verbose and --strict modes
Integration in package_skill.py:
- Automatic quality checks before packaging
- Display quality report with score and grade
- Ask user to confirm if warnings/errors found
- Add --skip-quality-check flag to bypass checks
- Updated help examples
Benefits:
- Catch quality issues before packaging
- Ensure SKILL.md is properly enhanced
- Validate all links work
- Give users confidence in skill quality
- Comprehensive quality reports
Addresses user request: "check some sort of quality check at the end
like is links working, skill is good etc and give report the user"
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Phase 1: Fix race condition where main console exits before enhancement completes
Changes to enhance_skill_local.py:
- Add headless mode (default) using subprocess.run() which WAITS for completion
- Add timeout protection (default 10 minutes, configurable)
- Verify SKILL.md was actually updated (check mtime and size)
- Add --interactive-enhancement flag to use old terminal mode
- Detailed progress messages and error handling
- Clean up temp files after completion
Changes to doc_scraper.py:
- Use skill-seekers-enhance entry point instead of direct python path
- Pass --interactive-enhancement flag through if requested
- Update help text to reflect new headless default behavior
- Show proper status messages (HEADLESS vs INTERACTIVE)
Benefits:
- Main console now waits for enhancement to complete
- No more "Package your skill" message while enhancement is running
- Timeout prevents infinite hangs
- Terminal mode still available for users who want it
- Better error messages and progress tracking
Fixes user request: "make sure 1. console wait for it to finish"
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Fixes#182
Changes:
- Add 'anthropic-beta: skills-2025-10-02' header (required by Anthropic Skills API)
- Change multipart field name from 'skill' to 'files[]' (correct API format)
Without these fixes, all upload attempts returned 404 errors.
Verified:
- All 379 tests passing (100%)
- No regressions in test suite
- Upload functionality corrected per API requirements
Co-authored-by: Straughter "BatmanOsama" Guthrie <straughterguthrie@gmail.com>
Original PR: #183
Major updates for v2.0.0:
- Added PyPI publication status and installation instructions
- Updated to reflect modern Python packaging (src/ layout, pyproject.toml)
- Updated all commands to use 'skill-seekers' CLI instead of python3 cli/*
- Updated file structure section for src/ layout
- Updated key code locations with new paths
- Added FUTURE_RELEASES.md to documentation list
- Updated test count (379 passing, all CI checks green)
- Updated date to November 11, 2025
- Added development workflow section
- Reorganized Additional Documentation into categories
All sections now reflect the post-PyPI publication state of the project.
- Add pip install -e . to install package in editable mode
- Update coverage path from cli/ to src/skill_seekers/
- Required for tests to import skill_seekers module
Fixes CI test failures: ModuleNotFoundError: No module named 'skill_seekers'
README.md:
- Add PyPI badges (version, downloads, python version)
- Update test count from 299 to 379 passing tests
- Add prominent 'Now Available on PyPI!' callout section
- Reorder installation options (pip as Option 1, uv as Option 2)
- Add links to Quick Start and Bulletproof guides
- Emphasize PyPI as the recommended installation method
CHANGELOG.md:
- Add comprehensive v2.0.0 release entry (dated 2025-11-11)
- Document PyPI publication as major milestone
- Detail modern Python packaging changes
- Include unified CLI interface documentation
- Add migration guide for users and developers
- List all breaking changes and deprecations
- Document 379 passing tests and import fixes
FUTURE_RELEASES.md (NEW):
- Create roadmap document for upcoming releases
- Plan v2.1.0 (Dec 2025): Test coverage & quality improvements
- Plan v2.2.0 (Q1 2026): Web presence & community growth
- Plan v2.3.0 (Q2 2026): Developer experience & integrations
- Long-term vision for v3.0+
- Community contribution guidelines
- Release schedule and priority system
🚀 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Fixes NameError that prevented generate_router.py from being imported.
The module uses Tuple[Path, Path] in type annotation but was missing
the import from typing module.
Add smart terminal selection for --enhance-local with cascading priority:
1. SKILL_SEEKER_TERMINAL env var (explicit user preference)
2. TERM_PROGRAM env var (inherit current terminal)
3. Terminal.app (fallback default)
Supports Ghostty, iTerm2, WezTerm, and Terminal.app. Includes comprehensive
test suite (11 tests) and user documentation.
Changes:
- Add detect_terminal_app() function with priority-based selection
- Support for 4 major macOS terminals via TERMINAL_MAP
- Fallback handling for unknown terminals (IDE terminals)
- Add TERMINAL_SELECTION.md with setup examples and troubleshooting
- Update README.md to link to terminal selection guide
- Full test coverage for all detection paths and edge cases
Fixed critical bug where unified, GitHub, and PDF skill builders
were generating SKILL.md files without required YAML frontmatter,
making skills invisible to Claude.
All 390 tests passing. No regressions.
Credits: @AbdelrahmanHafez (original fix)
**Problem:** (PR #170 verified)
Three skill builders were generating SKILL.md files without YAML
frontmatter, making skills invisible to Claude after upload:
- unified_skill_builder.py
- github_scraper.py
- pdf_scraper.py
Only doc_scraper.py had frontmatter implemented.
**Root Cause:**
Claude requires YAML frontmatter with 'name' and 'description' fields
to recognize and index skills. Without it, uploaded skills don't appear
in skill lists and can't be triggered.
**Fix:**
Added consistent frontmatter generation to all three builders:
- Normalizes skill name (lowercase, hyphens, max 64 chars)
- Truncates description to 1024 chars (Claude requirement)
- Generates YAML frontmatter with proper formatting
**Test Results:**
✅ All 390/390 tests passing (0 failures, 0 skipped)
✅ Consistent implementation across all builders
✅ Meets Claude's official skill specification
**Example Output:**
```yaml
---
name: my-skill-name
description: Skill description here
---
# My Skill Name
...
```
**Credits:**
Original fix by @AbdelrahmanHafez in PR #170
Rebased to current development by Claude Code
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: AbdelrahmanHafez <AbdelrahmanHafez@users.noreply.github.com>
**Context:**
PR #163 fixed critical venv detection bugs but used aggressive
--break-system-packages flag as immediate fallback.
**Improvement:**
Now when no venv is found, the script:
1. Warns user about missing virtual environment
2. Offers to create one automatically (y/n prompt)
3. If yes: Creates venv, activates it, proceeds safely
4. If creation fails: Falls back to system install with warning
5. If no: Proceeds with system install but shows clear warning
**Benefits:**
- Encourages best practices (venv usage)
- Less aggressive about bypassing system protections
- Still supports system install when needed
- Better user experience with clear choices
**Backward Compatibility:**
- All three original scenarios still work
- Only adds new prompt in "no venv" scenario
- Default behavior unchanged for existing venv users
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
## ✅ Merged - All Bugs Fixed
Excellent work fixing both critical bugs from the initial review! All 390 tests passing.
**Original bugs fixed:**
- ✅ Double "install" command issue resolved
- ✅ pytest line now uses $PIP_INSTALL_CMD
**What's merged:**
- Virtual environment detection (active venv)
- Auto-activation of inactive venv/
- System install fallback with --user --break-system-packages
**Next:** Will add refinements to the system install fallback in a follow-up commit.
🤖 Merged with [Claude Code](https://claude.com/claude-code)
**Problem:**
- GitHub Actions failing with 12 test failures in test_unified.py
- ConfigValidator only accepting file paths, not dicts
- ConflictDetector expecting dict pages, but tests providing list
- Import path issues in test_unified.py
**Changes:**
1. **cli/config_validator.py**:
- Modified `__init__` to accept Union[Dict, str] instead of just str
- Added isinstance check to handle both dict and file path inputs
- Maintains backward compatibility with existing code
2. **cli/conflict_detector.py**:
- Modified `_extract_docs_apis()` to handle both dict and list formats for pages
- Added support for 'analyzed_files' key (in addition to 'files')
- Made 'file' key optional in file_info dict
- Handles both production and test data structures
3. **tests/test_unified.py**:
- Fixed import path: sys.path now points to parent.parent/cli
- Fixed test regex: "Invalid source type" -> "Invalid type"
- All 18 unified tests now passing
**Test Results:**
- ✅ 390/390 tests passing (100%)
- ✅ All unified tests fixed (0 failures)
- ✅ No regressions in other test suites
**Impact:**
- Fixes failing GitHub Actions CI
- Improves testability of ConfigValidator and ConflictDetector
- Makes APIs more flexible for both production and test usage
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
## ✅ Approved and Merged
Excellent work, @StuartFenton! This is a critical bug fix that unblocks MCP integration for Claude Code CLI users.
### Review Summary
**Test Results:** ✅ All 372 tests passing (100% success rate)
**Code Quality:** ✅ Minimal, surgical changes with clear documentation
**Impact:** ✅ Fixes critical MCP scraping bug (1 page → 100 pages)
**Compatibility:** ✅ Fully backward compatible, no breaking changes
### What This Fixes
1. **MCP subprocess EOFError**: No more crashes on user input prompts
2. **Link discovery**: Now finds navigation links outside main content (10-100x more pages)
3. **--fresh flag**: Properly skips user prompts in automation mode
### Changes Merged
- **cli/doc_scraper.py**: Link extraction from entire page + --fresh flag fix
- **skill_seeker_mcp/server.py**: Auto-pass --fresh flag to prevent prompts
### Testing Validation
Real-world MCP testing shows:
- ✅ Tailwind CSS: 1 page → 100 pages
- ✅ No user prompts during execution
- ✅ Navigation links properly discovered
- ✅ End-to-end workflow through Claude Code CLI
Thank you for the thorough problem analysis, comprehensive testing, and excellent PR description! 🎉
---
**Next Steps:**
- Will be included in next release (v2.0.1)
- Added to project changelog
- MCP integration now fully functional
🤖 Merged with [Claude Code](https://claude.com/claude-code)
- Move test_unified.py to tests/ directory (607 lines, 19 tests)
- Move conflicts.json to tests/fixtures/example_conflicts.json
- Tests cover config validation, conflict detection, merging, and skill building
- Example conflicts show docs/code mismatch scenarios for v2.0.0 feature
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Support <pre class="brush: java"> pattern (SyntaxHighlighter)
- Support bare class names like <pre class="python">
- Add _extract_language_from_classes() helper method
- Apply detection logic to both code and parent pre elements
- Add 3 comprehensive test cases
Improves language detection for 25+ programming languages across
various documentation site formats.
Co-authored-by: Ricardo JL Rufino <ricardo@edu3.com.br>
- Changed from manual pip install to using requirements.txt
- Fixed mcp/requirements.txt -> skill_seeker_mcp/requirements.txt
- This ensures all dependencies (including httpx) are installed
Fixes the v2.0.0 tag Release workflow failure
Fixed async test issues that were causing CI failures.
## Issue:
GitHub Actions tests were failing with:
- 4 FAILED tests/test_unified_mcp_integration.py (async def functions not supported)
- 346 passed tests
## Root Cause:
The new test_unified_mcp_integration.py file had async test functions without proper pytest-anyio configuration, causing pytest to fail when trying to run them.
## Fix:
1. **Added pytest.mark.anyio markers**
- Added module-level pytestmark = pytest.mark.anyio
- Ensures all async functions are recognized by anyio plugin
2. **Created tests/conftest.py**
- Overrides anyio_backend fixture to use only 'asyncio'
- Prevents tests from attempting to use 'trio' backend (not installed)
- Reduces test duplication (was running each test for both asyncio + trio)
3. **Updated README.md**
- Already pushed in previous commit (b4f9052)
- Updated descriptions to reflect GitHub scraping capability
## Test Results:
**Before Fix:**
- 4 failed, 346 passed (in CI)
- Error: "async def functions are not natively supported"
**After Fix:**
- 4 passed tests/test_unified_mcp_integration.py
- All tests use asyncio backend only
- No trio-related errors
## Files Changed:
1. tests/test_unified_mcp_integration.py
- Added pytestmark = pytest.mark.anyio at module level
- All 4 async test functions now properly marked
2. tests/conftest.py (NEW)
- Created pytest configuration file
- Overrides anyio_backend to 'asyncio' only
- Prevents unnecessary test duplication
## Verification:
Local test run successful:
```
tests/test_unified_mcp_integration.py::test_mcp_validate_unified_config PASSED
tests/test_unified_mcp_integration.py::test_mcp_validate_legacy_config PASSED
tests/test_unified_mcp_integration.py::test_mcp_scrape_docs_detection PASSED
tests/test_unified_mcp_integration.py::test_mcp_merge_mode_override PASSED
4 passed in 0.21s
```
Expected CI result: 350/350 tests passing (up from 346/350)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Updated main description and feature sections to accurately reflect v2.0.0 capabilities:
## Changes:
**Main Description**:
- Changed from 'documentation website' to 'documentation websites, GitHub repositories, and PDFs'
- Added code analysis, conflict detection to workflow steps
- Emphasized multi-source capabilities
**What is Skill Seeker Section**:
- Updated to mention all three sources (docs, GitHub, PDFs)
- Added 'Analyzes code repositories with deep AST parsing'
- Added 'Detects conflicts between documentation and code'
- Now shows 6 steps instead of 4 (more comprehensive)
**Why Use This Section**:
- Updated use cases to include GitHub + docs combinations
- Added conflict detection benefits
- Added documentation gap analysis use case
- Added open source analysis use case
**GitHub Repository Scraping Section**:
- Updated version tag from v1.4.0 to v2.0.0
- Added 'Deep Code Analysis' with AST parsing
- Added 'API Extraction' with parameters and types
- Added 'Conflict Detection' feature
- Reorganized features to highlight new capabilities
## Rationale:
The previous README said 'any documentation website to skill' but we now support:
1. Documentation websites (original)
2. GitHub repositories (NEW - v2.0.0)
3. PDF files (v1.2.0)
4. Unified multi-source (docs + GitHub + PDF) (NEW - v2.0.0)
This update ensures users know they can scrape GitHub repos directly and combine multiple sources.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Major documentation update explaining the new unified scraping system that combines documentation + GitHub + PDF sources in a single skill with automatic conflict detection.
## Changes:
**README.md:**
- Update version badge to v2.0.0
- Add "Unified Multi-Source Scraping" to Key Features section
- Add comprehensive Option 5 section showing:
- Problem statement (documentation drift)
- Solution with code example
- Conflict detection types and severity levels
- Transparent reporting with side-by-side comparison
- List of advantages (identifies gaps, catches changes, single source of truth)
- Available unified configs
- Link to full guide (docs/UNIFIED_SCRAPING.md)
**CLAUDE.md:**
- Update Current Status to v2.0.0
- Add "Major Release: Unified Multi-Source Scraping" in Recent Updates
- Update configs count from 11/11 to 15/15 (added 4 unified configs)
- Add new "Unified Multi-Source Scraping" section under Core Commands
- Include command examples and feature highlights
- Explain what makes unified scraping special
**QUICKSTART.md:**
- Add Option D: Unified Multi-Source to Step 2
- Add unified configs to Available Presets section
- Show react_unified, django_unified, fastapi_unified, godot_unified examples
## Value:
This documentation update explains how unified scraping helps developers:
- Mix documentation + code in one skill
- Automatically detect conflicts (missing_in_docs, missing_in_code, signature_mismatch)
- Get transparent side-by-side comparisons with ⚠️ warnings
- Identify documentation gaps and outdated docs
- Create a single source of truth combining both sources
Related to: Phase 7-11 unified scraper implementation (commit 5d8c7e3)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Phase 3: Conflict Detection System ✅
- Created conflict_detector.py (500+ lines)
- Detects 4 conflict types:
* missing_in_docs - API in code but not documented
* missing_in_code - Documented API doesn't exist
* signature_mismatch - Different parameters/types
* description_mismatch - Docs vs code comments differ
- Fuzzy matching for similar names
- Severity classification (low/medium/high)
- Generates detailed conflict reports
Phase 4: Rule-Based Merger ✅
- Fast, deterministic merging rules
- 4 rules for handling conflicts:
1. Docs only → Include with [DOCS_ONLY] tag
2. Code only → Include with [UNDOCUMENTED] tag
3. Perfect match → Include normally
4. Conflict → Prefer code signature, keep docs description
- Generates unified API reference
- Summary statistics (matched, conflicts, etc.)
Phase 5: Claude-Enhanced Merger ✅
- AI-powered conflict reconciliation
- Opens Claude Code in new terminal
- Provides merge context and instructions
- Creates workspace with conflicts.json
- Waits for human-supervised merge
- Falls back to rule-based if needed
Testing:
✅ Conflict detector finds 5 conflicts in test data
✅ Rule-based merger successfully merges 5 APIs
✅ Proper handling of docs_only vs code_only
✅ JSON serialization works correctly
Next: Orchestrator to tie everything together
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
