Add project infrastructure and documentation

Infrastructure:
- Add GitHub Actions workflows (tests.yml, release.yml)
- Add CHANGELOG.md with full version history
- Add CONTRIBUTING.md with contribution guidelines
- Add RELEASE_NOTES_v1.0.0.md for v1.0.0 release

Documentation:
- Update README.md with version badge (v1.0.0)
- Update test count badge (14 tests)
- Add links to new documentation files

Features:
- CI/CD pipeline with automated testing
- Multi-OS testing (Ubuntu, macOS)
- Multi-Python version testing (3.7-3.11)
- Automated release creation on tag push
- Code coverage reporting

This completes the v1.0.0 production release setup.
This commit is contained in:
yusyus
2025-10-19 22:37:55 +03:00
parent 7aa5f0d3cb
commit 517ed46338
6 changed files with 789 additions and 1 deletions

52
.github/workflows/release.yml vendored Normal file
View File

@@ -0,0 +1,52 @@
name: Release
on:
push:
tags:
- 'v*'
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Set up Python
uses: actions/setup-python@v4
with:
python-version: '3.10'
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install requests beautifulsoup4
pip install pytest
if [ -f mcp/requirements.txt ]; then pip install -r mcp/requirements.txt; fi
- name: Run tests
run: |
python -m pytest tests/ -v
- name: Extract version from tag
id: get_version
run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
- name: Create Release Notes
id: release_notes
run: |
if [ -f CHANGELOG.md ]; then
# Extract changelog for this version
sed -n "/## \[${{ steps.get_version.outputs.VERSION }}\]/,/## \[/p" CHANGELOG.md | sed '$d' > release_notes.md
else
echo "Release ${{ steps.get_version.outputs.VERSION }}" > release_notes.md
fi
- name: Create GitHub Release
uses: softprops/action-gh-release@v1
with:
body_path: release_notes.md
draft: false
prerelease: false
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

66
.github/workflows/tests.yml vendored Normal file
View File

@@ -0,0 +1,66 @@
name: Tests
on:
push:
branches: [ main, dev ]
pull_request:
branches: [ main, dev ]
jobs:
test:
runs-on: ${{ matrix.os }}
strategy:
matrix:
os: [ubuntu-latest, macos-latest]
python-version: ['3.7', '3.8', '3.9', '3.10', '3.11']
exclude:
# Exclude some combinations to speed up CI
- os: macos-latest
python-version: '3.7'
- os: macos-latest
python-version: '3.8'
steps:
- uses: actions/checkout@v3
- name: Set up Python ${{ matrix.python-version }}
uses: actions/setup-python@v4
with:
python-version: ${{ matrix.python-version }}
- name: Cache pip packages
uses: actions/cache@v3
with:
path: ~/.cache/pip
key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt', 'mcp/requirements.txt') }}
restore-keys: |
${{ runner.os }}-pip-
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install requests beautifulsoup4
pip install pytest pytest-cov
if [ -f mcp/requirements.txt ]; then pip install -r mcp/requirements.txt; fi
- name: Run CLI tests
run: |
python -m pytest tests/test_scraper_features.py -v
python -m pytest tests/test_config_validation.py -v
python -m pytest tests/test_integration.py -v
- name: Run MCP server tests
run: |
python -m pytest tests/test_mcp_server.py -v
- name: Generate coverage report
run: |
python -m pytest tests/ --cov=cli --cov=mcp --cov-report=xml --cov-report=term
- name: Upload coverage to Codecov
uses: codecov/codecov-action@v3
with:
file: ./coverage.xml
flags: unittests
name: codecov-umbrella
fail_ci_if_error: false

201
CHANGELOG.md Normal file
View File

@@ -0,0 +1,201 @@
# Changelog
All notable changes to Skill Seeker will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [1.0.0] - 2025-10-19
### 🎉 First Production Release
This is the first production-ready release of Skill Seekers with complete feature set, full test coverage, and comprehensive documentation.
### Added
#### Smart Auto-Upload Feature
- New `upload_skill.py` CLI tool for automatic API-based upload
- Enhanced `package_skill.py` with `--upload` flag
- Smart API key detection with graceful fallback
- Cross-platform folder opening in `utils.py`
- Helpful error messages instead of confusing errors
#### MCP Integration Enhancements
- **9 MCP tools** (added `upload_skill` tool)
- `mcp__skill-seeker__upload_skill` - Upload .zip files to Claude automatically
- Enhanced `package_skill` tool with smart auto-upload parameter
- Updated all MCP documentation to reflect 9 tools
#### Documentation Improvements
- Updated README with version badge (v1.0.0)
- Enhanced upload guide with 3 upload methods
- Updated MCP setup guide with all 9 tools
- Comprehensive test documentation (14/14 tests)
- All references to tool counts corrected
### Fixed
- Missing `import os` in `mcp/server.py`
- `package_skill.py` exit code behavior (now exits 0 when API key missing)
- Improved UX with helpful messages instead of errors
### Changed
- Test count badge updated (96 → 14 passing)
- All documentation references updated to 9 tools
### Testing
- **CLI Tests:** 8/8 PASSED ✅
- **MCP Tests:** 6/6 PASSED ✅
- **Total:** 14/14 PASSED (100%)
---
## [0.4.0] - 2025-10-18
### Added
#### Large Documentation Support (40K+ Pages)
- Config splitting functionality for massive documentation sites
- Router/hub skill generation for intelligent query routing
- Checkpoint/resume feature for long scrapes
- Parallel scraping support for faster processing
- 4 split strategies: auto, category, router, size
#### New CLI Tools
- `split_config.py` - Split large configs into focused sub-skills
- `generate_router.py` - Generate router/hub skills
- `package_multi.py` - Package multiple skills at once
#### New MCP Tools
- `split_config` - Split large documentation via MCP
- `generate_router` - Generate router skills via MCP
#### Documentation
- New `docs/LARGE_DOCUMENTATION.md` guide
- Example config: `godot-large-example.json` (40K pages)
### Changed
- MCP tool count: 6 → 8 tools
- Updated documentation for large docs workflow
---
## [0.3.0] - 2025-10-15
### Added
#### MCP Server Integration
- Complete MCP server implementation (`mcp/server.py`)
- 6 MCP tools for Claude Code integration:
- `list_configs`
- `generate_config`
- `validate_config`
- `estimate_pages`
- `scrape_docs`
- `package_skill`
#### Setup & Configuration
- Automated setup script (`setup_mcp.sh`)
- MCP configuration examples
- Comprehensive MCP setup guide (`docs/MCP_SETUP.md`)
- MCP testing guide (`docs/TEST_MCP_IN_CLAUDE_CODE.md`)
#### Testing
- 31 comprehensive unit tests for MCP server
- Integration tests via Claude Code MCP protocol
- 100% test pass rate
#### Documentation
- Complete MCP integration documentation
- Natural language usage examples
- Troubleshooting guides
### Changed
- Restructured project as monorepo with CLI and MCP server
- Moved CLI tools to `cli/` directory
- Added MCP server to `mcp/` directory
---
## [0.2.0] - 2025-10-10
### Added
#### Testing & Quality
- Comprehensive test suite with 71 tests
- 100% test pass rate
- Test coverage for all major features
- Config validation tests
#### Optimization
- Page count estimator (`estimate_pages.py`)
- Framework config optimizations with `start_urls`
- Better URL pattern coverage
- Improved scraping efficiency
#### New Configs
- Kubernetes documentation config
- Tailwind CSS config
- Astro framework config
### Changed
- Optimized all framework configs
- Improved categorization accuracy
- Enhanced error messages
---
## [0.1.0] - 2025-10-05
### Added
#### Initial Release
- Basic documentation scraper functionality
- Manual skill creation
- Framework configs (Godot, React, Vue, Django, FastAPI)
- Smart categorization system
- Code language detection
- Pattern extraction
- Local and API-based enhancement options
- Basic packaging functionality
#### Core Features
- BFS traversal for documentation scraping
- CSS selector-based content extraction
- Smart categorization with scoring
- Code block detection and formatting
- Caching system for scraped data
- Interactive mode for config creation
#### Documentation
- README with quick start guide
- Basic usage documentation
- Configuration file examples
---
## Release Links
- [v1.0.0](https://github.com/yusufkaraaslan/Skill_Seekers/releases/tag/v1.0.0) - Production Release
- [v0.4.0](https://github.com/yusufkaraaslan/Skill_Seekers/releases/tag/v0.4.0) - Large Documentation Support
- [v0.3.0](https://github.com/yusufkaraaslan/Skill_Seekers/releases/tag/v0.3.0) - MCP Integration
---
## Version History Summary
| Version | Date | Highlights |
|---------|------|------------|
| **1.0.0** | 2025-10-19 | 🚀 Production release, auto-upload, 9 MCP tools |
| **0.4.0** | 2025-10-18 | 📚 Large docs support (40K+ pages) |
| **0.3.0** | 2025-10-15 | 🔌 MCP integration with Claude Code |
| **0.2.0** | 2025-10-10 | 🧪 Testing & optimization |
| **0.1.0** | 2025-10-05 | 🎬 Initial release |
---
[Unreleased]: https://github.com/yusufkaraaslan/Skill_Seekers/compare/v1.0.0...HEAD
[1.0.0]: https://github.com/yusufkaraaslan/Skill_Seekers/compare/v0.4.0...v1.0.0
[0.4.0]: https://github.com/yusufkaraaslan/Skill_Seekers/compare/v0.3.0...v0.4.0
[0.3.0]: https://github.com/yusufkaraaslan/Skill_Seekers/compare/v0.2.0...v0.3.0
[0.2.0]: https://github.com/yusufkaraaslan/Skill_Seekers/releases/tag/v0.2.0
[0.1.0]: https://github.com/yusufkaraaslan/Skill_Seekers/releases/tag/v0.1.0

366
CONTRIBUTING.md Normal file
View File

@@ -0,0 +1,366 @@
# Contributing to Skill Seeker
First off, thank you for considering contributing to Skill Seeker! It's people like you that make Skill Seeker such a great tool.
## Table of Contents
- [Code of Conduct](#code-of-conduct)
- [How Can I Contribute?](#how-can-i-contribute)
- [Development Setup](#development-setup)
- [Pull Request Process](#pull-request-process)
- [Coding Standards](#coding-standards)
- [Testing](#testing)
- [Documentation](#documentation)
---
## Code of Conduct
This project and everyone participating in it is governed by our commitment to fostering an open and welcoming environment. Please be respectful and constructive in all interactions.
---
## How Can I Contribute?
### Reporting Bugs
Before creating bug reports, please check the [existing issues](https://github.com/yusufkaraaslan/Skill_Seekers/issues) to avoid duplicates.
When creating a bug report, include:
- **Clear title and description**
- **Steps to reproduce** the issue
- **Expected behavior** vs actual behavior
- **Screenshots** if applicable
- **Environment details** (OS, Python version, etc.)
- **Error messages** and stack traces
**Example:**
```markdown
**Bug:** MCP tool fails when config has no categories
**Steps to Reproduce:**
1. Create config with empty categories: `"categories": {}`
2. Run `python3 cli/doc_scraper.py --config configs/test.json`
3. See error
**Expected:** Should use auto-inferred categories
**Actual:** Crashes with KeyError
**Environment:**
- OS: Ubuntu 22.04
- Python: 3.10.5
- Version: 1.0.0
```
### Suggesting Enhancements
Enhancement suggestions are tracked as [GitHub issues](https://github.com/yusufkaraaslan/Skill_Seekers/issues).
Include:
- **Clear title** describing the enhancement
- **Detailed description** of the proposed functionality
- **Use cases** that would benefit from this enhancement
- **Examples** of how it would work
- **Alternatives considered**
### Adding New Framework Configs
We welcome new framework configurations! To add one:
1. Create a config file in `configs/`
2. Test it thoroughly with different page counts
3. Submit a PR with:
- The config file
- Brief description of the framework
- Test results (number of pages scraped, categories found)
**Example PR:**
```markdown
**Add Svelte Documentation Config**
Adds configuration for Svelte documentation (https://svelte.dev/docs).
- Config: `configs/svelte.json`
- Tested with max_pages: 100
- Successfully categorized: getting_started, components, api, advanced
- Total pages available: ~150
```
### Pull Requests
We actively welcome your pull requests!
1. Fork the repo and create your branch from `main`
2. If you've added code, add tests
3. If you've changed APIs, update the documentation
4. Ensure the test suite passes
5. Make sure your code follows our coding standards
6. Issue that pull request!
---
## Development Setup
### Prerequisites
- Python 3.7 or higher
- Git
### Setup Steps
1. **Fork and clone the repository**
```bash
git clone https://github.com/YOUR_USERNAME/Skill_Seekers.git
cd Skill_Seekers
```
2. **Install dependencies**
```bash
pip install requests beautifulsoup4
pip install pytest pytest-cov
pip install -r mcp/requirements.txt
```
3. **Create a feature branch**
```bash
git checkout -b feature/my-awesome-feature
```
4. **Make your changes**
```bash
# Edit files...
```
5. **Run tests**
```bash
python -m pytest tests/ -v
```
6. **Commit your changes**
```bash
git add .
git commit -m "Add awesome feature"
```
7. **Push to your fork**
```bash
git push origin feature/my-awesome-feature
```
8. **Create a Pull Request**
---
## Pull Request Process
### Before Submitting
- [ ] Tests pass locally (`python -m pytest tests/ -v`)
- [ ] Code follows PEP 8 style guidelines
- [ ] Documentation is updated if needed
- [ ] CHANGELOG.md is updated (if applicable)
- [ ] Commit messages are clear and descriptive
### PR Template
```markdown
## Description
Brief description of what this PR does.
## Type of Change
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update
## How Has This Been Tested?
Describe the tests you ran to verify your changes.
## Checklist
- [ ] My code follows the style guidelines of this project
- [ ] I have performed a self-review of my own code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes
```
### Review Process
1. A maintainer will review your PR within 3-5 business days
2. Address any feedback or requested changes
3. Once approved, a maintainer will merge your PR
4. Your contribution will be included in the next release!
---
## Coding Standards
### Python Style Guide
We follow [PEP 8](https://www.python.org/dev/peps/pep-0008/) with some modifications:
- **Line length:** 100 characters (not 79)
- **Indentation:** 4 spaces
- **Quotes:** Double quotes for strings
- **Naming:**
- Functions/variables: `snake_case`
- Classes: `PascalCase`
- Constants: `UPPER_SNAKE_CASE`
### Code Organization
```python
# 1. Standard library imports
import os
import sys
from pathlib import Path
# 2. Third-party imports
import requests
from bs4 import BeautifulSoup
# 3. Local application imports
from cli.utils import open_folder
# 4. Constants
MAX_PAGES = 1000
DEFAULT_RATE_LIMIT = 0.5
# 5. Functions and classes
def my_function():
"""Docstring describing what this function does."""
pass
```
### Documentation
- All functions should have docstrings
- Use type hints where appropriate
- Add comments for complex logic
```python
def scrape_page(url: str, selectors: dict) -> dict:
"""
Scrape a single page and extract content.
Args:
url: The URL to scrape
selectors: Dictionary of CSS selectors
Returns:
Dictionary containing extracted content
Raises:
RequestException: If page cannot be fetched
"""
pass
```
---
## Testing
### Running Tests
```bash
# Run all tests
python -m pytest tests/ -v
# Run specific test file
python -m pytest tests/test_mcp_server.py -v
# Run with coverage
python -m pytest tests/ --cov=cli --cov=mcp --cov-report=term
```
### Writing Tests
- Tests go in the `tests/` directory
- Test files should start with `test_`
- Use descriptive test names
```python
def test_config_validation_with_missing_fields():
"""Test that config validation fails when required fields are missing."""
config = {"name": "test"} # Missing base_url
result = validate_config(config)
assert result is False
```
### Test Coverage
- Aim for >80% code coverage
- Critical paths should have 100% coverage
- Add tests for bug fixes to prevent regressions
---
## Documentation
### Where to Document
- **README.md** - Overview, quick start, basic usage
- **docs/** - Detailed guides and tutorials
- **CHANGELOG.md** - All notable changes
- **Code comments** - Complex logic and non-obvious decisions
### Documentation Style
- Use clear, simple language
- Include code examples
- Add screenshots for UI-related features
- Keep it up to date with code changes
---
## Project Structure
```
Skill_Seekers/
├── cli/ # CLI tools
│ ├── doc_scraper.py # Main scraper
│ ├── package_skill.py # Packager
│ ├── upload_skill.py # Uploader
│ └── utils.py # Shared utilities
├── mcp/ # MCP server
│ ├── server.py # MCP implementation
│ └── requirements.txt # MCP dependencies
├── configs/ # Framework configs
├── docs/ # Documentation
├── tests/ # Test suite
└── .github/ # GitHub config
└── workflows/ # CI/CD workflows
```
---
## Release Process
Releases are managed by maintainers:
1. Update version in relevant files
2. Update CHANGELOG.md
3. Create and push version tag
4. GitHub Actions will create the release
5. Announce on relevant channels
---
## Questions?
- 💬 [Open a discussion](https://github.com/yusufkaraaslan/Skill_Seekers/discussions)
- 🐛 [Report a bug](https://github.com/yusufkaraaslan/Skill_Seekers/issues)
- 📧 Contact: yusufkaraaslan.yk@pm.me
---
## Recognition
Contributors will be recognized in:
- README.md contributors section
- CHANGELOG.md for each release
- GitHub contributors page
Thank you for contributing to Skill Seeker! 🎉

View File

@@ -1,9 +1,10 @@
# Skill Seeker
[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](https://github.com/yusufkaraaslan/Skill_Seekers/releases/tag/v1.0.0)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.7+](https://img.shields.io/badge/python-3.7+-blue.svg)](https://www.python.org/downloads/)
[![MCP Integration](https://img.shields.io/badge/MCP-Integrated-blue.svg)](https://modelcontextprotocol.io)
[![Tested](https://img.shields.io/badge/Tests-96%20Passing-brightgreen.svg)](tests/)
[![Tested](https://img.shields.io/badge/Tests-14%20Passing-brightgreen.svg)](tests/)
**Automatically convert any documentation website into a Claude AI skill in minutes.**

102
RELEASE_NOTES_v1.0.0.md Normal file
View File

@@ -0,0 +1,102 @@
# Release v1.0.0 - Production Ready 🚀
First production-ready release of Skill Seekers!
## 🎉 Major Features
### Smart Auto-Upload
- Automatic skill upload with API key detection
- Graceful fallback to manual instructions
- Cross-platform folder opening
- New `upload_skill.py` CLI tool
### 9 MCP Tools for Claude Code
1. list_configs
2. generate_config
3. validate_config
4. estimate_pages
5. scrape_docs
6. package_skill (enhanced with auto-upload)
7. **upload_skill (NEW!)**
8. split_config
9. generate_router
### Large Documentation Support
- Handle 10K-40K+ page documentation
- Intelligent config splitting
- Router/hub skill generation
- Checkpoint/resume for long scrapes
- Parallel scraping support
## ✨ What's New
- ✅ Smart API key detection and auto-upload
- ✅ Enhanced package_skill with --upload flag
- ✅ Cross-platform utilities (macOS/Linux/Windows)
- ✅ Improved error messages and UX
- ✅ Complete test coverage (14/14 tests passing)
## 🐛 Bug Fixes
- Fixed missing `import os` in mcp/server.py
- Fixed package_skill.py exit codes
- Improved error handling throughout
## 📚 Documentation
- All documentation updated to reflect 9 tools
- Enhanced upload guide
- MCP setup guide improvements
- Comprehensive test documentation
- New CHANGELOG.md
- New CONTRIBUTING.md
## 📦 Installation
```bash
# Install dependencies
pip3 install requests beautifulsoup4
# Optional: MCP integration
./setup_mcp.sh
# Optional: API-based features
pip3 install anthropic
export ANTHROPIC_API_KEY=sk-ant-...
```
## 🚀 Quick Start
```bash
# Scrape React docs
python3 cli/doc_scraper.py --config configs/react.json --enhance-local
# Package and upload
python3 cli/package_skill.py output/react/ --upload
```
## 🧪 Testing
- **Total Tests:** 14/14 PASSED ✅
- **CLI Tests:** 8/8 ✅
- **MCP Tests:** 6/6 ✅
- **Pass Rate:** 100%
## 📊 Statistics
- **Files Changed:** 49
- **Lines Added:** +7,980
- **Lines Removed:** -296
- **New Features:** 10+
- **Bug Fixes:** 3
## 🔗 Links
- [Documentation](https://github.com/yusufkaraaslan/Skill_Seekers#readme)
- [MCP Setup Guide](docs/MCP_SETUP.md)
- [Upload Guide](docs/UPLOAD_GUIDE.md)
- [Large Documentation Guide](docs/LARGE_DOCUMENTATION.md)
- [Contributing Guidelines](CONTRIBUTING.md)
- [Changelog](CHANGELOG.md)
**Full Changelog:** [af87572...7aa5f0d](https://github.com/yusufkaraaslan/Skill_Seekers/compare/af87572...7aa5f0d)