firefrost-gaming/skill-seekers-reference
3
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

Release v2.5.0 - Multi-Platform Feature Parity

Browse Source 
Merge development branch for v2.5.0 release.

This release adds complete multi-platform support for Claude AI,
Google Gemini, OpenAI ChatGPT, and Generic Markdown with full
feature parity across all platforms and skill modes.

Major Features:
- 4 LLM platforms supported
- Platform-specific adaptors architecture
- 18 MCP tools with multi-platform support
- Complete feature parity implementation
- Comprehensive platform documentation
- 700 tests passing

See CHANGELOG.md for detailed release notes.
This commit is contained in:
yusyus
2025-12-28 22:21:32 +03:00
parent 74bae4b49f 7e1fd3fbac
commit 5abb21c207
38 changed files with 7239 additions and 576 deletions
Download Patch File Download Diff File Expand all files Collapse all files

239
CHANGELOG.md
View File

@@ -17,6 +17,245 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
---
## [2.5.0] - 2025-12-28
### 🚀 Multi-Platform Feature Parity - 4 LLM Platforms Supported
This **major feature release** adds complete multi-platform support for Claude AI, Google Gemini, OpenAI ChatGPT, and Generic Markdown export. All features now work across all platforms with full feature parity.
### 🎯 Major Features
#### Multi-LLM Platform Support
- **4 platforms supported**: Claude AI, Google Gemini, OpenAI ChatGPT, Generic Markdown
- **Complete feature parity**: All skill modes work with all platforms
- **Platform adaptors**: Clean architecture with platform-specific implementations
- **Unified workflow**: Same scraping output works for all platforms
- **Smart enhancement**: Platform-specific AI models (Claude Sonnet 4, Gemini 2.0 Flash, GPT-4o)
#### Platform-Specific Capabilities
**Claude AI (Default):**
- Format: ZIP with YAML frontmatter + markdown
- Upload: Anthropic Skills API
- Enhancement: Claude Sonnet 4 (local or API)
- MCP integration: Full support
**Google Gemini:**
- Format: tar.gz with plain markdown
- Upload: Google Files API + Grounding
- Enhancement: Gemini 2.0 Flash
- Long context: 1M tokens supported
**OpenAI ChatGPT:**
- Format: ZIP with assistant instructions
- Upload: Assistants API + Vector Store
- Enhancement: GPT-4o
- File search: Semantic search enabled
**Generic Markdown:**
- Format: ZIP with pure markdown
- Upload: Manual distribution
- Universal compatibility: Works with any LLM
#### Complete Feature Parity
**All skill modes work with all platforms:**
- Documentation scraping → All 4 platforms
- GitHub repository analysis → All 4 platforms
- PDF extraction → All 4 platforms
- Unified multi-source → All 4 platforms
- Local repository analysis → All 4 platforms
**18 MCP tools with multi-platform support:**
- `package_skill` - Now accepts `target` parameter (claude, gemini, openai, markdown)
- `upload_skill` - Now accepts `target` parameter (claude, gemini, openai)
- `enhance_skill` - NEW standalone tool with `target` parameter
- `install_skill` - Full multi-platform workflow automation
### Added
#### Core Infrastructure
- **Platform Adaptors** (`src/skill_seekers/cli/adaptors/`)
- `base_adaptor.py` - Abstract base class for all adaptors
- `claude_adaptor.py` - Claude AI implementation
- `gemini_adaptor.py` - Google Gemini implementation
- `openai_adaptor.py` - OpenAI ChatGPT implementation
- `markdown_adaptor.py` - Generic Markdown export
- `__init__.py` - Factory function `get_adaptor(target)`
#### CLI Tools
- **Multi-platform packaging**: `skill-seekers package output/skill/ --target gemini`
- **Multi-platform upload**: `skill-seekers upload skill.zip --target openai`
- **Multi-platform enhancement**: `skill-seekers enhance output/skill/ --target gemini --mode api`
- **Target parameter**: All packaging tools now accept `--target` flag
#### MCP Tools
- **`enhance_skill`** (NEW) - Standalone AI enhancement tool
- Supports local mode (Claude Code Max, no API key)
- Supports API mode (platform-specific APIs)
- Works with Claude, Gemini, OpenAI
- Creates SKILL.md.backup before enhancement
- **`package_skill`** (UPDATED) - Multi-platform packaging
- New `target` parameter (claude, gemini, openai, markdown)
- Creates ZIP for Claude/OpenAI/Markdown
- Creates tar.gz for Gemini
- Shows platform-specific output messages
- **`upload_skill`** (UPDATED) - Multi-platform upload
- New `target` parameter (claude, gemini, openai)
- Platform-specific API key validation
- Returns skill ID and platform URL
- Graceful error for markdown (no upload)
#### Documentation
- **`docs/FEATURE_MATRIX.md`** (NEW) - Comprehensive feature matrix
- Platform support comparison table
- Skill mode support across platforms
- CLI command support matrix
- MCP tool support matrix
- Platform-specific examples
- Verification checklist
- **`docs/UPLOAD_GUIDE.md`** (REWRITTEN) - Multi-platform upload guide
- Complete guide for all 4 platforms
- Platform selection table
- API key setup instructions
- Platform comparison matrices
- Complete workflow examples
- **`docs/ENHANCEMENT.md`** (UPDATED)
- Multi-platform enhancement section
- Platform-specific model information
- Cost comparison across platforms
- **`docs/MCP_SETUP.md`** (UPDATED)
- Added enhance_skill to tool listings
- Multi-platform usage examples
- Updated tool count (10 → 18 tools)
- **`src/skill_seekers/mcp/README.md`** (UPDATED)
- Corrected tool count (18 tools)
- Added enhance_skill documentation
- Updated package_skill with target parameter
- Updated upload_skill with target parameter
#### Optional Dependencies
- **`[gemini]`** extra: `pip install skill-seekers[gemini]`
- google-generativeai>=0.8.3
- Required for Gemini enhancement and upload
- **`[openai]`** extra: `pip install skill-seekers[openai]`
- openai>=1.59.6
- Required for OpenAI enhancement and upload
- **`[all-llms]`** extra: `pip install skill-seekers[all-llms]`
- Includes both Gemini and OpenAI dependencies
#### Tests
- **`tests/test_adaptors.py`** - Comprehensive adaptor tests
- **`tests/test_multi_llm_integration.py`** - E2E multi-platform tests
- **`tests/test_install_multiplatform.py`** - Multi-platform install_skill tests
- **700 total tests passing** (up from 427 in v2.4.0)
### Changed
#### CLI Architecture
- **Package command**: Now routes through platform adaptors
- **Upload command**: Now supports all 3 upload platforms
- **Enhancement command**: Now supports platform-specific models
- **Unified workflow**: All commands respect `--target` parameter
#### MCP Architecture
- **Tool modularity**: Cleaner separation with adaptor pattern
- **Error handling**: Platform-specific error messages
- **API key validation**: Per-platform validation logic
- **TextContent fallback**: Graceful degradation when MCP not installed
#### Documentation
- All platform documentation updated for multi-LLM support
- Consistent terminology across all docs
- Platform comparison tables added
- Examples updated to show all platforms
### Fixed
- **TextContent import error** in test environment (5 MCP tool files)
- Added fallback TextContent class when MCP not installed
- Prevents `TypeError: 'NoneType' object is not callable`
- Ensures tests pass without MCP library
- **UTF-8 encoding** issues on Windows (continued from v2.4.0)
- All file operations use explicit UTF-8 encoding
- CHANGELOG encoding handling improved
- **API key environment variables** - Clear documentation for all platforms
- ANTHROPIC_API_KEY for Claude
- GOOGLE_API_KEY for Gemini
- OPENAI_API_KEY for OpenAI
### Other Improvements
#### Smart Description Generation
- Automatically generates skill descriptions from documentation
- Analyzes reference files to suggest "When to Use" triggers
- Improves SKILL.md quality without manual editing
#### Smart Summarization
- Large skills (500+ lines) automatically summarized
- Preserves key examples and patterns
- Maintains quality while reducing token usage
### Deprecation Notice
None - All changes are backward compatible. Existing v2.4.0 workflows continue to work with default `target='claude'`.
### Migration Guide
**For users upgrading from v2.4.0:**
1. **No changes required** - Default behavior unchanged (targets Claude AI)
2. **To use other platforms:**
```bash
# Install platform dependencies
pip install skill-seekers[gemini] # For Gemini
pip install skill-seekers[openai] # For OpenAI
pip install skill-seekers[all-llms] # For all platforms
# Set API keys
export GOOGLE_API_KEY=AIzaSy... # For Gemini
export OPENAI_API_KEY=sk-proj-... # For OpenAI
# Use --target flag
skill-seekers package output/react/ --target gemini
skill-seekers upload react-gemini.tar.gz --target gemini
```
3. **MCP users** - New tools available:
- `enhance_skill` - Standalone enhancement (was only in install_skill)
- All packaging tools now accept `target` parameter
**See full documentation:**
- [Multi-Platform Guide](docs/UPLOAD_GUIDE.md)
- [Feature Matrix](docs/FEATURE_MATRIX.md)
- [Enhancement Guide](docs/ENHANCEMENT.md)
### Contributors
- @yusufkaraaslan - Multi-platform architecture, all platform adaptors, comprehensive testing
### Stats
- **16 commits** since v2.4.0
- **700 tests** (up from 427, +273 new tests)
- **4 platforms** supported (was 1)
- **18 MCP tools** (up from 17)
- **5 documentation guides** updated/created
- **29 files changed**, 6,349 insertions(+), 253 deletions(-)
---
## [2.4.0] - 2025-12-25
### 🚀 MCP 2025 Upgrade - Multi-Agent Support & HTTP Transport

84
README.md
View File

@@ -2,11 +2,11 @@
# Skill Seeker
[![Version](https://img.shields.io/badge/version-2.4.0-blue.svg)](https://github.com/yusufkaraaslan/Skill_Seekers/releases/tag/v2.4.0)
[![Version](https://img.shields.io/badge/version-2.5.0-blue.svg)](https://github.com/yusufkaraaslan/Skill_Seekers/releases/tag/v2.5.0)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-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-427%20Passing-brightgreen.svg)](tests/)
[![Tested](https://img.shields.io/badge/Tests-700%20Passing-brightgreen.svg)](tests/)
[![Project Board](https://img.shields.io/badge/Project-Board-purple.svg)](https://github.com/users/yusufkaraaslan/projects/2)
[![PyPI version](https://badge.fury.io/py/skill-seekers.svg)](https://pypi.org/project/skill-seekers/)
[![PyPI - Downloads](https://img.shields.io/pypi/dm/skill-seekers.svg)](https://pypi.org/project/skill-seekers/)
@@ -72,6 +72,53 @@ Skill Seeker is an automated tool that transforms documentation websites, GitHub
- ✅ **Single Source of Truth** - One skill showing both intent (docs) and reality (code)
- ✅ **Backward Compatible** - Legacy single-source configs still work
### 🤖 Multi-LLM Platform Support (**NEW - v2.5.0**)
- ✅ **4 LLM Platforms** - Claude AI, Google Gemini, OpenAI ChatGPT, Generic Markdown
- ✅ **Universal Scraping** - Same documentation works for all platforms
- ✅ **Platform-Specific Packaging** - Optimized formats for each LLM
- ✅ **One-Command Export** - `--target` flag selects platform
- ✅ **Optional Dependencies** - Install only what you need
- ✅ **100% Backward Compatible** - Existing Claude workflows unchanged
| Platform | Format | Upload | Enhancement | API Key |
|----------|--------|--------|-------------|---------|
| **Claude AI** | ZIP + YAML | ✅ Auto | ✅ Yes | ANTHROPIC_API_KEY |
| **Google Gemini** | tar.gz | ✅ Auto | ✅ Yes | GOOGLE_API_KEY |
| **OpenAI ChatGPT** | ZIP + Vector Store | ✅ Auto | ✅ Yes | OPENAI_API_KEY |
| **Generic Markdown** | ZIP | ❌ Manual | ❌ No | None |
```bash
# Claude (default - no changes needed!)
skill-seekers package output/react/
skill-seekers upload react.zip
# Google Gemini
pip install skill-seekers[gemini]
skill-seekers package output/react/ --target gemini
skill-seekers upload react-gemini.tar.gz --target gemini
# OpenAI ChatGPT
pip install skill-seekers[openai]
skill-seekers package output/react/ --target openai
skill-seekers upload react-openai.zip --target openai
# Generic Markdown (universal export)
skill-seekers package output/react/ --target markdown
# Use the markdown files directly in any LLM
```
**Installation:**
```bash
# Install with Gemini support
pip install skill-seekers[gemini]
# Install with OpenAI support
pip install skill-seekers[openai]
# Install with all LLM platforms
pip install skill-seekers[all-llms]
```
### 🔐 Private Config Repositories (**NEW - v2.2.0**)
- ✅ **Git-Based Config Sources** - Fetch configs from private/team git repositories
- ✅ **Multi-Source Management** - Register unlimited GitHub, GitLab, Bitbucket repos
@@ -256,6 +303,39 @@ skill-seekers install --config react
---
## 📊 Feature Matrix
Skill Seekers supports **4 platforms** and **5 skill modes** with full feature parity.
**Platforms:** Claude AI, Google Gemini, OpenAI ChatGPT, Generic Markdown
**Skill Modes:** Documentation, GitHub, PDF, Unified Multi-Source, Local Repository
See [Complete Feature Matrix](docs/FEATURE_MATRIX.md) for detailed platform and feature support.
### Quick Platform Comparison
| Feature | Claude | Gemini | OpenAI | Markdown |
|---------|--------|--------|--------|----------|
| Format | ZIP + YAML | tar.gz | ZIP + Vector | ZIP |
| Upload | ✅ API | ✅ API | ✅ API | ❌ Manual |
| Enhancement | ✅ Sonnet 4 | ✅ 2.0 Flash | ✅ GPT-4o | ❌ None |
| All Skill Modes | ✅ | ✅ | ✅ | ✅ |
**Examples:**
```bash
# Package for all platforms (same skill)
skill-seekers package output/react/ --target claude
skill-seekers package output/react/ --target gemini
skill-seekers package output/react/ --target openai
skill-seekers package output/react/ --target markdown
# Install for specific platform
skill-seekers install --config django --target gemini
skill-seekers install --config fastapi --target openai
```
---
## Usage Examples
### Documentation Scraping

53
docs/CLAUDE.md
View File

@@ -2,6 +2,21 @@
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## 🎯 Current Status (December 28, 2025)
**Version:** v2.5.0 (Production Ready - Multi-Platform Feature Parity!)
**Active Development:** Multi-platform support complete
### Recent Updates (December 2025):
**🎉 MAJOR RELEASE: Multi-Platform Feature Parity! (v2.5.0)**
- **🌐 Multi-LLM Support**: Full support for 4 platforms - Claude AI, Google Gemini, OpenAI ChatGPT, Generic Markdown
- **🔄 Complete Feature Parity**: All skill modes work with all platforms
- **🏗️ Platform Adaptors**: Clean architecture with platform-specific implementations
- **✨ 18 MCP Tools**: Enhanced with multi-platform support (package, upload, enhance)
- **📚 Comprehensive Documentation**: Complete guides for all platforms
- **🧪 Test Coverage**: 700 tests passing, extensive platform compatibility testing
## Overview
This is a Python-based documentation scraper that converts ANY documentation website into a Claude skill. It's a single-file tool (`doc_scraper.py`) that scrapes documentation, extracts code patterns, detects programming languages, and generates structured skill files ready for use with Claude.
@@ -94,11 +109,47 @@ The LOCAL enhancement option (`--enhance-local` or `enhance_skill_local.py`) ope
"Package skill at output/react/"
```
9 MCP tools available: list_configs, generate_config, validate_config, estimate_pages, scrape_docs, package_skill, upload_skill, split_config, generate_router
18 MCP tools available with multi-platform support: list_configs, generate_config, validate_config, fetch_config, estimate_pages, scrape_docs, scrape_github, scrape_pdf, package_skill, upload_skill, enhance_skill (NEW), install_skill, split_config, generate_router, add_config_source, list_config_sources, remove_config_source, submit_config
### Test with limited pages (edit config first)
Set `"max_pages": 20` in the config file to test with fewer pages.
## Multi-Platform Support (v2.5.0+)
**4 Platforms Fully Supported:**
- **Claude AI** (default) - ZIP format, Skills API, MCP integration
- **Google Gemini** - tar.gz format, Files API, 1M token context
- **OpenAI ChatGPT** - ZIP format, Assistants API, Vector Store
- **Generic Markdown** - ZIP format, universal compatibility
**All skill modes work with all platforms:**
- Documentation scraping
- GitHub repository analysis
- PDF extraction
- Unified multi-source
- Local repository analysis
**Use the `--target` parameter for packaging, upload, and enhancement:**
```bash
# Package for different platforms
skill-seekers package output/react/ --target claude # Default
skill-seekers package output/react/ --target gemini
skill-seekers package output/react/ --target openai
skill-seekers package output/react/ --target markdown
# Upload to platforms (requires API keys)
skill-seekers upload output/react.zip --target claude
skill-seekers upload output/react-gemini.tar.gz --target gemini
skill-seekers upload output/react-openai.zip --target openai
# Enhance with platform-specific AI
skill-seekers enhance output/react/ --target claude # Sonnet 4
skill-seekers enhance output/react/ --target gemini --mode api # Gemini 2.0
skill-seekers enhance output/react/ --target openai --mode api # GPT-4o
```
See [Multi-Platform Guide](UPLOAD_GUIDE.md) and [Feature Matrix](FEATURE_MATRIX.md) for complete details.
## Architecture
### Single-File Design

78
docs/ENHANCEMENT.md
View File

@@ -243,8 +243,86 @@ ADDITIONAL REQUIREMENTS:
"""
```
## Multi-Platform Enhancement
Skill Seekers supports enhancement for Claude AI, Google Gemini, and OpenAI ChatGPT using platform-specific AI models.
### Claude AI (Default)
**Local Mode (Recommended - No API Key):**
```bash
# Uses Claude Code Max (no API costs)
skill-seekers enhance output/react/
```
**API Mode:**
```bash
# Requires ANTHROPIC_API_KEY
export ANTHROPIC_API_KEY=sk-ant-...
skill-seekers enhance output/react/ --mode api
```
**Model:** Claude Sonnet 4
**Format:** Maintains YAML frontmatter
---
### Google Gemini
```bash
# Install Gemini support
pip install skill-seekers[gemini]
# Set API key
export GOOGLE_API_KEY=AIzaSy...
# Enhance with Gemini
skill-seekers enhance output/react/ --target gemini --mode api
```
**Model:** Gemini 2.0 Flash
**Format:** Converts to plain markdown (no frontmatter)
**Output:** Updates `system_instructions.md` for Gemini compatibility
---
### OpenAI ChatGPT
```bash
# Install OpenAI support
pip install skill-seekers[openai]
# Set API key
export OPENAI_API_KEY=sk-proj-...
# Enhance with GPT-4o
skill-seekers enhance output/react/ --target openai --mode api
```
**Model:** GPT-4o
**Format:** Converts to plain text assistant instructions
**Output:** Updates `assistant_instructions.txt` for OpenAI Assistants API
---
### Platform Comparison
| Feature | Claude | Gemini | OpenAI |
|---------|--------|--------|--------|
| **Local Mode** | ✅ Yes (Claude Code Max) | ❌ No | ❌ No |
| **API Mode** | ✅ Yes | ✅ Yes | ✅ Yes |
| **Model** | Sonnet 4 | Gemini 2.0 Flash | GPT-4o |
| **Format** | YAML + MD | Plain MD | Plain Text |
| **Cost (API)** | ~$0.15-0.30 | ~$0.10-0.25 | ~$0.20-0.35 |
**Note:** Local mode (Claude Code Max) is FREE and only available for Claude AI platform.
---
## See Also
- [README.md](../README.md) - Main documentation
- [FEATURE_MATRIX.md](FEATURE_MATRIX.md) - Complete platform feature matrix
- [MULTI_LLM_SUPPORT.md](MULTI_LLM_SUPPORT.md) - Multi-platform guide
- [CLAUDE.md](CLAUDE.md) - Architecture guide
- [doc_scraper.py](../doc_scraper.py) - Main scraping tool

321
docs/FEATURE_MATRIX.md Normal file
View File

@@ -0,0 +1,321 @@
# Skill Seekers Feature Matrix
Complete feature support across all platforms and skill modes.
## Platform Support
| Platform | Package Format | Upload | Enhancement | API Key Required |
|----------|---------------|--------|-------------|------------------|
| **Claude AI** | ZIP | ✅ Anthropic API | ✅ Sonnet 4 | ANTHROPIC_API_KEY |
| **Google Gemini** | tar.gz | ✅ Files API | ✅ Gemini 2.0 | GOOGLE_API_KEY |
| **OpenAI ChatGPT** | ZIP | ✅ Assistants API | ✅ GPT-4o | OPENAI_API_KEY |
| **Generic Markdown** | ZIP | ❌ Manual | ❌ None | None |
## Skill Mode Support
| Mode | Description | Platforms | Example Configs |
|------|-------------|-----------|-----------------|
| **Documentation** | Scrape HTML docs | All 4 | react.json, django.json (14 total) |
| **GitHub** | Analyze repositories | All 4 | react_github.json, godot_github.json |
| **PDF** | Extract from PDFs | All 4 | example_pdf.json |
| **Unified** | Multi-source (docs+GitHub+PDF) | All 4 | react_unified.json (5 total) |
| **Local Repo** | Unlimited local analysis | All 4 | deck_deck_go_local.json |
## CLI Command Support
| Command | Platforms | Skill Modes | Multi-Platform Flag |
|---------|-----------|-------------|---------------------|
| `scrape` | All | Docs only | No (output is universal) |
| `github` | All | GitHub only | No (output is universal) |
| `pdf` | All | PDF only | No (output is universal) |
| `unified` | All | Unified only | No (output is universal) |
| `enhance` | Claude, Gemini, OpenAI | All | ✅ `--target` |
| `package` | All | All | ✅ `--target` |
| `upload` | Claude, Gemini, OpenAI | All | ✅ `--target` |
| `estimate` | All | Docs only | No (estimation is universal) |
| `install` | All | All | ✅ `--target` |
| `install-agent` | All | All | No (agent-specific paths) |
## MCP Tool Support
| Tool | Platforms | Skill Modes | Multi-Platform Param |
|------|-----------|-------------|----------------------|
| **Config Tools** |
| `generate_config` | All | All | No (creates generic JSON) |
| `list_configs` | All | All | No |
| `validate_config` | All | All | No |
| `fetch_config` | All | All | No |
| **Scraping Tools** |
| `estimate_pages` | All | Docs only | No |
| `scrape_docs` | All | Docs + Unified | No (output is universal) |
| `scrape_github` | All | GitHub only | No (output is universal) |
| `scrape_pdf` | All | PDF only | No (output is universal) |
| **Packaging Tools** |
| `package_skill` | All | All | ✅ `target` parameter |
| `upload_skill` | Claude, Gemini, OpenAI | All | ✅ `target` parameter |
| `enhance_skill` | Claude, Gemini, OpenAI | All | ✅ `target` parameter |
| `install_skill` | All | All | ✅ `target` parameter |
| **Splitting Tools** |
| `split_config` | All | Docs + Unified | No |
| `generate_router` | All | Docs only | No |
## Feature Comparison by Platform
### Claude AI (Default)
- **Format:** YAML frontmatter + markdown
- **Package:** ZIP with SKILL.md, references/, scripts/, assets/
- **Upload:** POST to https://api.anthropic.com/v1/skills
- **Enhancement:** Claude Sonnet 4 (local or API)
- **Unique Features:** MCP integration, Skills API
- **Limitations:** No vector store, no file search
### Google Gemini
- **Format:** Plain markdown (no frontmatter)
- **Package:** tar.gz with system_instructions.md, references/, metadata
- **Upload:** Google Files API
- **Enhancement:** Gemini 2.0 Flash
- **Unique Features:** Grounding support, long context (1M tokens)
- **Limitations:** tar.gz format only
### OpenAI ChatGPT
- **Format:** Assistant instructions (plain text)
- **Package:** ZIP with assistant_instructions.txt, vector_store_files/, metadata
- **Upload:** Assistants API + Vector Store creation
- **Enhancement:** GPT-4o
- **Unique Features:** Vector store, file_search tool, semantic search
- **Limitations:** Requires Assistants API structure
### Generic Markdown
- **Format:** Pure markdown (universal)
- **Package:** ZIP with README.md, DOCUMENTATION.md, references/
- **Upload:** None (manual distribution)
- **Enhancement:** None
- **Unique Features:** Works with any LLM, no API dependencies
- **Limitations:** No upload, no enhancement
## Workflow Coverage
### Single-Source Workflow
```
Config → Scrape → Build → [Enhance] → Package --target X → [Upload --target X]
```
**Platforms:** All 4
**Modes:** Docs, GitHub, PDF
### Unified Multi-Source Workflow
```
Config → Scrape All → Detect Conflicts → Merge → Build → [Enhance] → Package --target X → [Upload --target X]
```
**Platforms:** All 4
**Modes:** Unified only
### Complete Installation Workflow
```
install --target X → Fetch → Scrape → Enhance → Package → Upload
```
**Platforms:** All 4
**Modes:** All (via config type detection)
## API Key Requirements
| Platform | Environment Variable | Key Format | Required For |
|----------|---------------------|------------|--------------|
| Claude | `ANTHROPIC_API_KEY` | `sk-ant-*` | Upload, API Enhancement |
| Gemini | `GOOGLE_API_KEY` | `AIza*` | Upload, API Enhancement |
| OpenAI | `OPENAI_API_KEY` | `sk-*` | Upload, API Enhancement |
| Markdown | None | N/A | Nothing |
**Note:** Local enhancement (Claude Code Max) requires no API key for any platform.
## Installation Options
```bash
# Core package (Claude only)
pip install skill-seekers
# With Gemini support
pip install skill-seekers[gemini]
# With OpenAI support
pip install skill-seekers[openai]
# With all platforms
pip install skill-seekers[all-llms]
```
## Examples
### Package for Multiple Platforms (Same Skill)
```bash
# Scrape once (platform-agnostic)
skill-seekers scrape --config configs/react.json
# Package for all platforms
skill-seekers package output/react/ --target claude
skill-seekers package output/react/ --target gemini
skill-seekers package output/react/ --target openai
skill-seekers package output/react/ --target markdown
# Result:
# - react.zip (Claude)
# - react-gemini.tar.gz (Gemini)
# - react-openai.zip (OpenAI)
# - react-markdown.zip (Universal)
```
### Upload to Multiple Platforms
```bash
export ANTHROPIC_API_KEY=sk-ant-...
export GOOGLE_API_KEY=AIzaSy...
export OPENAI_API_KEY=sk-proj-...
skill-seekers upload react.zip --target claude
skill-seekers upload react-gemini.tar.gz --target gemini
skill-seekers upload react-openai.zip --target openai
```
### Use MCP Tools for Any Platform
```python
# In Claude Code or any MCP client
# Package for Gemini
package_skill(skill_dir="output/react", target="gemini")
# Upload to OpenAI
upload_skill(skill_zip="output/react-openai.zip", target="openai")
# Enhance with Gemini
enhance_skill(skill_dir="output/react", target="gemini", mode="api")
```
### Complete Workflow with Different Platforms
```bash
# Install React skill for Claude (default)
skill-seekers install --config react
# Install Django skill for Gemini
skill-seekers install --config django --target gemini
# Install FastAPI skill for OpenAI
skill-seekers install --config fastapi --target openai
# Install Vue skill as generic markdown
skill-seekers install --config vue --target markdown
```
### Split Unified Config by Source
```bash
# Split multi-source config into separate configs
skill-seekers split --config configs/react_unified.json --strategy source
# Creates:
# - react-documentation.json (docs only)
# - react-github.json (GitHub only)
# Then scrape each separately
skill-seekers unified --config react-documentation.json
skill-seekers unified --config react-github.json
# Or scrape in parallel for speed
skill-seekers unified --config react-documentation.json &
skill-seekers unified --config react-github.json &
wait
```
## Verification Checklist
Before release, verify all combinations:
### CLI Commands × Platforms
- [ ] scrape → package claude → upload claude
- [ ] scrape → package gemini → upload gemini
- [ ] scrape → package openai → upload openai
- [ ] scrape → package markdown
- [ ] github → package (all platforms)
- [ ] pdf → package (all platforms)
- [ ] unified → package (all platforms)
- [ ] enhance claude
- [ ] enhance gemini
- [ ] enhance openai
### MCP Tools × Platforms
- [ ] package_skill target=claude
- [ ] package_skill target=gemini
- [ ] package_skill target=openai
- [ ] package_skill target=markdown
- [ ] upload_skill target=claude
- [ ] upload_skill target=gemini
- [ ] upload_skill target=openai
- [ ] enhance_skill target=claude
- [ ] enhance_skill target=gemini
- [ ] enhance_skill target=openai
- [ ] install_skill target=claude
- [ ] install_skill target=gemini
- [ ] install_skill target=openai
### Skill Modes × Platforms
- [ ] Docs → Claude
- [ ] Docs → Gemini
- [ ] Docs → OpenAI
- [ ] Docs → Markdown
- [ ] GitHub → All platforms
- [ ] PDF → All platforms
- [ ] Unified → All platforms
- [ ] Local Repo → All platforms
## Platform-Specific Notes
### Claude AI
- **Best for:** General-purpose skills, MCP integration
- **When to use:** Default choice, best MCP support
- **File size limit:** 25 MB per skill package
### Google Gemini
- **Best for:** Large context skills, grounding support
- **When to use:** Need long context (1M tokens), grounding features
- **File size limit:** 100 MB per upload
### OpenAI ChatGPT
- **Best for:** Vector search, semantic retrieval
- **When to use:** Need semantic search across documentation
- **File size limit:** 512 MB per vector store
### Generic Markdown
- **Best for:** Universal compatibility, no API dependencies
- **When to use:** Using non-Claude/Gemini/OpenAI LLMs, offline use
- **Distribution:** Manual - share ZIP file directly
## Frequently Asked Questions
**Q: Can I package once and upload to multiple platforms?**
A: No. Each platform requires a platform-specific package format. You must:
1. Scrape once (universal)
2. Package separately for each platform (`--target` flag)
3. Upload each platform-specific package
**Q: Do I need to scrape separately for each platform?**
A: No! Scraping is platform-agnostic. Scrape once, then package for multiple platforms.
**Q: Which platform should I choose?**
A:
- **Claude:** Best default choice, excellent MCP integration
- **Gemini:** Choose if you need long context (1M tokens) or grounding
- **OpenAI:** Choose if you need vector search and semantic retrieval
- **Markdown:** Choose for universal compatibility or offline use
**Q: Can I enhance a skill for different platforms?**
A: Yes! Enhancement adds platform-specific formatting:
- Claude: YAML frontmatter + markdown
- Gemini: Plain markdown with system instructions
- OpenAI: Plain text assistant instructions
**Q: Do all skill modes work with all platforms?**
A: Yes! All 5 skill modes (Docs, GitHub, PDF, Unified, Local Repo) work with all 4 platforms.
## See Also
- **[README.md](../README.md)** - Complete user documentation
- **[UNIFIED_SCRAPING.md](UNIFIED_SCRAPING.md)** - Multi-source scraping guide
- **[ENHANCEMENT.md](ENHANCEMENT.md)** - AI enhancement guide
- **[UPLOAD_GUIDE.md](UPLOAD_GUIDE.md)** - Upload instructions
- **[MCP_SETUP.md](MCP_SETUP.md)** - MCP server setup

435
docs/GEMINI_INTEGRATION.md Normal file
View File

@@ -0,0 +1,435 @@
# Google Gemini Integration Guide
Complete guide for creating and deploying skills to Google Gemini using Skill Seekers.
## Overview
Skill Seekers packages documentation into Gemini-compatible formats optimized for:
- **Gemini 2.0 Flash** for enhancement
- **Files API** for document upload
- **Grounding** for accurate, source-based responses
## Setup
### 1. Install Gemini Support
```bash
# Install with Gemini dependencies
pip install skill-seekers[gemini]
# Verify installation
pip list | grep google-generativeai
```
### 2. Get Google API Key
1. Visit [Google AI Studio](https://aistudio.google.com/)
2. Click "Get API Key"
3. Create new API key or use existing
4. Copy the key (starts with `AIza`)
### 3. Configure API Key
```bash
# Set as environment variable (recommended)
export GOOGLE_API_KEY=AIzaSy...
# Or pass directly to commands
skill-seekers upload --target gemini --api-key AIzaSy...
```
## Complete Workflow
### Step 1: Scrape Documentation
```bash
# Use any config (scraping is platform-agnostic)
skill-seekers scrape --config configs/react.json
# Or use a unified config for multi-source
skill-seekers unified --config configs/react_unified.json
```
**Result:** `output/react/` skill directory with references
### Step 2: Enhance with Gemini (Optional but Recommended)
```bash
# Enhance SKILL.md using Gemini 2.0 Flash
skill-seekers enhance output/react/ --target gemini
# With API key specified
skill-seekers enhance output/react/ --target gemini --api-key AIzaSy...
```
**What it does:**
- Analyzes all reference documentation
- Extracts 5-10 best code examples
- Creates comprehensive quick reference
- Adds key concepts and usage guidance
- Generates plain markdown (no YAML frontmatter)
**Time:** 20-40 seconds
**Cost:** ~$0.01-0.05 (using Gemini 2.0 Flash)
**Quality boost:** 3/10 → 9/10
### Step 3: Package for Gemini
```bash
# Create tar.gz package for Gemini
skill-seekers package output/react/ --target gemini
# Result: react-gemini.tar.gz
```
**Package structure:**
```
react-gemini.tar.gz/
├── system_instructions.md # Main documentation (plain markdown)
├── references/ # Individual reference files
│ ├── getting_started.md
│ ├── hooks.md
│ ├── components.md
│ └── ...
└── gemini_metadata.json # Platform metadata
```
### Step 4: Upload to Gemini
```bash
# Upload to Google AI Studio
skill-seekers upload react-gemini.tar.gz --target gemini
# With API key
skill-seekers upload react-gemini.tar.gz --target gemini --api-key AIzaSy...
```
**Output:**
```
✅ Upload successful!
Skill ID: files/abc123xyz
URL: https://aistudio.google.com/app/files/abc123xyz
Files uploaded: 15 files
```
### Step 5: Use in Gemini
Access your uploaded files in Google AI Studio:
1. Go to [Google AI Studio](https://aistudio.google.com/)
2. Navigate to **Files** section
3. Find your uploaded skill files
4. Use with Gemini API or AI Studio
## What Makes Gemini Different?
### Format: Plain Markdown (No YAML)
**Claude format:**
```markdown
---
name: react
description: React framework
---
# React Documentation
...
```
**Gemini format:**
```markdown
# React Documentation
**Description:** React framework for building user interfaces
## Quick Reference
...
```
No YAML frontmatter - Gemini uses plain markdown for better compatibility.
### Package: tar.gz Instead of ZIP
Gemini uses `.tar.gz` compression for better Unix compatibility and smaller file sizes.
### Upload: Files API + Grounding
Files are uploaded to Google's Files API and made available for grounding in Gemini responses.
## Using Your Gemini Skill
### Option 1: Google AI Studio (Web UI)
1. Go to [Google AI Studio](https://aistudio.google.com/)
2. Create new chat or app
3. Reference your uploaded files in prompts:
```
Using the React documentation files, explain hooks
```
### Option 2: Gemini API (Python)
```python
import google.generativeai as genai
# Configure with your API key
genai.configure(api_key='AIzaSy...')
# Create model
model = genai.GenerativeModel('gemini-2.0-flash-exp')
# Use with uploaded files (automatic grounding)
response = model.generate_content(
"How do I use React hooks?",
# Files automatically available via grounding
)
print(response.text)
```
### Option 3: Gemini API with File Reference
```python
import google.generativeai as genai
# Configure
genai.configure(api_key='AIzaSy...')
# Get your uploaded file
files = genai.list_files()
react_file = next(f for f in files if 'react' in f.display_name.lower())
# Use file in generation
model = genai.GenerativeModel('gemini-2.0-flash-exp')
response = model.generate_content([
"Explain React hooks in detail",
react_file
])
print(response.text)
```
## Advanced Usage
### Enhance with Custom Prompt
The enhancement process can be customized by modifying the adaptor:
```python
from skill_seekers.cli.adaptors import get_adaptor
from pathlib import Path
# Get Gemini adaptor
adaptor = get_adaptor('gemini')
# Enhance with custom parameters
success = adaptor.enhance(
skill_dir=Path('output/react'),
api_key='AIzaSy...'
)
```
### Programmatic Upload
```python
from skill_seekers.cli.adaptors import get_adaptor
from pathlib import Path
# Get adaptor
gemini = get_adaptor('gemini')
# Package skill
package_path = gemini.package(
skill_dir=Path('output/react'),
output_path=Path('output/react-gemini.tar.gz')
)
# Upload
result = gemini.upload(
package_path=package_path,
api_key='AIzaSy...'
)
if result['success']:
print(f"✅ Uploaded to: {result['url']}")
print(f"Skill ID: {result['skill_id']}")
else:
print(f"❌ Upload failed: {result['message']}")
```
### Manual Package Extraction
If you want to inspect or modify the package:
```bash
# Extract tar.gz
tar -xzf react-gemini.tar.gz -C extracted/
# View structure
tree extracted/
# Modify files if needed
nano extracted/system_instructions.md
# Re-package
tar -czf react-gemini-modified.tar.gz -C extracted .
```
## Gemini-Specific Features
### 1. Grounding Support
Gemini automatically grounds responses in your uploaded documentation files, providing:
- Source attribution
- Accurate citations
- Reduced hallucination
### 2. Multimodal Capabilities
Gemini can process:
- Text documentation
- Code examples
- Images (if included in PDFs)
- Tables and diagrams
### 3. Long Context Window
Gemini 2.0 Flash supports:
- Up to 1M token context
- Entire documentation sets in single context
- Better understanding of cross-references
## Troubleshooting
### Issue: `google-generativeai not installed`
**Solution:**
```bash
pip install skill-seekers[gemini]
```
### Issue: `Invalid API key format`
**Error:** API key doesn't start with `AIza`
**Solution:**
- Get new key from [Google AI Studio](https://aistudio.google.com/)
- Verify you're using Google API key, not GCP service account
### Issue: `Not a tar.gz file`
**Error:** Wrong package format
**Solution:**
```bash
# Use --target gemini for tar.gz format
skill-seekers package output/react/ --target gemini
# NOT:
skill-seekers package output/react/ # Creates .zip (Claude format)
```
### Issue: `File upload failed`
**Possible causes:**
- API key lacks permissions
- File too large (check limits)
- Network connectivity
**Solution:**
```bash
# Verify API key works
python3 -c "import google.generativeai as genai; genai.configure(api_key='AIza...'); print(list(genai.list_models())[:2])"
# Check file size
ls -lh react-gemini.tar.gz
# Try with verbose output
skill-seekers upload react-gemini.tar.gz --target gemini --verbose
```
### Issue: Enhancement fails
**Solution:**
```bash
# Check API quota
# Visit: https://aistudio.google.com/apikey
# Try with smaller skill
skill-seekers enhance output/react/ --target gemini --max-files 5
# Use without enhancement
skill-seekers package output/react/ --target gemini
# (Skip enhancement step)
```
## Best Practices
### 1. Organize Documentation
Structure your SKILL.md clearly:
- Start with overview
- Add quick reference section
- Group related concepts
- Include practical examples
### 2. Optimize File Count
- Combine related topics into single files
- Use clear file naming
- Keep total under 100 files for best performance
### 3. Test with Gemini
After upload, test with sample questions:
```
1. How do I get started with [topic]?
2. What are the core concepts?
3. Show me a practical example
4. What are common pitfalls?
```
### 4. Update Regularly
```bash
# Re-scrape updated documentation
skill-seekers scrape --config configs/react.json
# Re-enhance and upload
skill-seekers enhance output/react/ --target gemini
skill-seekers package output/react/ --target gemini
skill-seekers upload react-gemini.tar.gz --target gemini
```
## Cost Estimation
**Gemini 2.0 Flash pricing:**
- Input: $0.075 per 1M tokens
- Output: $0.30 per 1M tokens
**Typical skill enhancement:**
- Input: ~50K-200K tokens (docs)
- Output: ~5K-10K tokens (enhanced SKILL.md)
- Cost: $0.01-0.05 per skill
**File upload:** Free (no per-file charges)
## Next Steps
1. ✅ Install Gemini support: `pip install skill-seekers[gemini]`
2. ✅ Get API key from Google AI Studio
3. ✅ Scrape your documentation
4. ✅ Enhance with Gemini
5. ✅ Package for Gemini
6. ✅ Upload and test
## Resources
- [Google AI Studio](https://aistudio.google.com/)
- [Gemini API Documentation](https://ai.google.dev/docs)
- [Gemini Pricing](https://ai.google.dev/pricing)
- [Multi-LLM Support Guide](MULTI_LLM_SUPPORT.md)
## Feedback
Found an issue or have suggestions? [Open an issue](https://github.com/yusufkaraaslan/Skill_Seekers/issues)

56
docs/MCP_SETUP.md
View File

@@ -64,10 +64,11 @@ Step-by-step guide to set up the Skill Seeker MCP server with 5 supported AI cod
- `scrape_github` - Scrape GitHub repositories
- `scrape_pdf` - Extract content from PDF files
**Packaging Tools (3):**
- `package_skill` - Package skill into .zip file
- `upload_skill` - Upload .zip to Claude AI (NEW)
- `install_skill` - Install skill to AI coding agents (NEW)
**Packaging Tools (4):**
- `package_skill` - Package skill (supports multi-platform via `target` parameter)
- `upload_skill` - Upload to LLM platform (claude, gemini, openai)
- `enhance_skill` - AI-enhance SKILL.md (NEW - local or API mode)
- `install_skill` - Complete install workflow
**Splitting Tools (2):**
- `split_config` - Split large documentation configs
@@ -603,9 +604,10 @@ You should see **17 Skill Seeker tools**:
- `scrape_pdf` - Extract PDF content
**Packaging Tools:**
- `package_skill` - Package skill into .zip
- `upload_skill` - Upload to Claude AI
- `install_skill` - Install to AI agents
- `package_skill` - Package skill (multi-platform support)
- `upload_skill` - Upload to LLM platform
- `enhance_skill` - AI-enhance SKILL.md
- `install_skill` - Complete install workflow
**Splitting Tools:**
- `split_config` - Split large configs
@@ -743,6 +745,46 @@ User: Scrape docs using configs/internal-api.json
Agent: [Scraping internal documentation...]
```
### Example 4: Multi-Platform Support
Skill Seekers supports packaging and uploading to 4 LLM platforms: Claude AI, Google Gemini, OpenAI ChatGPT, and Generic Markdown.
```
User: Scrape docs using configs/react.json
Agent: ✅ Skill created at output/react/
User: Package skill at output/react/ with target gemini
Agent: ✅ Packaged for Google Gemini
Saved to: output/react-gemini.tar.gz
Format: tar.gz (Gemini-specific format)
User: Package skill at output/react/ with target openai
Agent: ✅ Packaged for OpenAI ChatGPT
Saved to: output/react-openai.zip
Format: ZIP with vector store
User: Enhance skill at output/react/ with target gemini and mode api
Agent: ✅ Enhanced with Gemini 2.0 Flash
Backup: output/react/SKILL.md.backup
Enhanced: output/react/SKILL.md
User: Upload output/react-gemini.tar.gz with target gemini
Agent: ✅ Uploaded to Google Gemini
Skill ID: gemini_12345
Access at: https://aistudio.google.com/
```
**Available platforms:**
- `claude` (default) - ZIP format, Anthropic Skills API
- `gemini` - tar.gz format, Google Files API
- `openai` - ZIP format, OpenAI Assistants API + Vector Store
- `markdown` - ZIP format, generic export (no upload)
---
## Troubleshooting

407
docs/MULTI_LLM_SUPPORT.md Normal file
View File

@@ -0,0 +1,407 @@
# Multi-LLM Platform Support Guide
Skill Seekers supports multiple LLM platforms through a clean adaptor system. The core scraping and content organization remains universal, while packaging and upload are platform-specific.
## Supported Platforms
| Platform | Status | Format | Upload | Enhancement | API Key Required |
|----------|--------|--------|--------|-------------|------------------|
| **Claude AI** | ✅ Full Support | ZIP + YAML | ✅ Automatic | ✅ Yes | ANTHROPIC_API_KEY |
| **Google Gemini** | ✅ Full Support | tar.gz | ✅ Automatic | ✅ Yes | GOOGLE_API_KEY |
| **OpenAI ChatGPT** | ✅ Full Support | ZIP + Vector Store | ✅ Automatic | ✅ Yes | OPENAI_API_KEY |
| **Generic Markdown** | ✅ Export Only | ZIP | ❌ Manual | ❌ No | None |
## Quick Start
### Claude AI (Default)
No changes needed! All existing workflows continue to work:
```bash
# Scrape documentation
skill-seekers scrape --config configs/react.json
# Package for Claude (default)
skill-seekers package output/react/
# Upload to Claude
skill-seekers upload react.zip
```
### Google Gemini
```bash
# Install Gemini support
pip install skill-seekers[gemini]
# Set API key
export GOOGLE_API_KEY=AIzaSy...
# Scrape documentation (same as always)
skill-seekers scrape --config configs/react.json
# Package for Gemini
skill-seekers package output/react/ --target gemini
# Upload to Gemini
skill-seekers upload react-gemini.tar.gz --target gemini
# Optional: Enhance with Gemini
skill-seekers enhance output/react/ --target gemini
```
**Output:** `react-gemini.tar.gz` ready for Google AI Studio
### OpenAI ChatGPT
```bash
# Install OpenAI support
pip install skill-seekers[openai]
# Set API key
export OPENAI_API_KEY=sk-proj-...
# Scrape documentation (same as always)
skill-seekers scrape --config configs/react.json
# Package for OpenAI
skill-seekers package output/react/ --target openai
# Upload to OpenAI (creates Assistant + Vector Store)
skill-seekers upload react-openai.zip --target openai
# Optional: Enhance with GPT-4o
skill-seekers enhance output/react/ --target openai
```
**Output:** OpenAI Assistant created with file search enabled
### Generic Markdown (Universal Export)
```bash
# Package as generic markdown (no dependencies)
skill-seekers package output/react/ --target markdown
# Output: react-markdown.zip with:
# - README.md
# - references/*.md
# - DOCUMENTATION.md (combined)
```
**Use case:** Export for any LLM, documentation hosting, or manual distribution
## Installation Options
### Install Core Package Only
```bash
# Default installation (Claude support only)
pip install skill-seekers
```
### Install with Specific Platform Support
```bash
# Google Gemini support
pip install skill-seekers[gemini]
# OpenAI ChatGPT support
pip install skill-seekers[openai]
# All LLM platforms
pip install skill-seekers[all-llms]
# Development dependencies (includes testing)
pip install skill-seekers[dev]
```
### Install from Source
```bash
git clone https://github.com/yusufkaraaslan/Skill_Seekers.git
cd Skill_Seekers
# Editable install with all platforms
pip install -e .[all-llms]
```
## Platform Comparison
### Format Differences
**Claude AI:**
- Format: ZIP archive
- SKILL.md: YAML frontmatter + markdown
- Structure: `SKILL.md`, `references/`, `scripts/`, `assets/`
- API: Anthropic Skills API
- Enhancement: Claude Sonnet 4
**Google Gemini:**
- Format: tar.gz archive
- SKILL.md → `system_instructions.md` (plain markdown, no frontmatter)
- Structure: `system_instructions.md`, `references/`, `gemini_metadata.json`
- API: Google Files API + grounding
- Enhancement: Gemini 2.0 Flash
**OpenAI ChatGPT:**
- Format: ZIP archive
- SKILL.md → `assistant_instructions.txt` (plain text)
- Structure: `assistant_instructions.txt`, `vector_store_files/`, `openai_metadata.json`
- API: Assistants API + Vector Store
- Enhancement: GPT-4o
**Generic Markdown:**
- Format: ZIP archive
- Structure: `README.md`, `references/`, `DOCUMENTATION.md` (combined)
- No API integration
- No enhancement support
- Universal compatibility
### API Key Configuration
**Claude AI:**
```bash
export ANTHROPIC_API_KEY=sk-ant-...
```
**Google Gemini:**
```bash
export GOOGLE_API_KEY=AIzaSy...
```
**OpenAI ChatGPT:**
```bash
export OPENAI_API_KEY=sk-proj-...
```
## Complete Workflow Examples
### Workflow 1: Claude AI (Default)
```bash
# 1. Scrape
skill-seekers scrape --config configs/react.json
# 2. Enhance (optional but recommended)
skill-seekers enhance output/react/
# 3. Package
skill-seekers package output/react/
# 4. Upload
skill-seekers upload react.zip
# Access at: https://claude.ai/skills
```
### Workflow 2: Google Gemini
```bash
# Setup (one-time)
pip install skill-seekers[gemini]
export GOOGLE_API_KEY=AIzaSy...
# 1. Scrape (universal)
skill-seekers scrape --config configs/react.json
# 2. Enhance for Gemini
skill-seekers enhance output/react/ --target gemini
# 3. Package for Gemini
skill-seekers package output/react/ --target gemini
# 4. Upload to Gemini
skill-seekers upload react-gemini.tar.gz --target gemini
# Access at: https://aistudio.google.com/files/
```
### Workflow 3: OpenAI ChatGPT
```bash
# Setup (one-time)
pip install skill-seekers[openai]
export OPENAI_API_KEY=sk-proj-...
# 1. Scrape (universal)
skill-seekers scrape --config configs/react.json
# 2. Enhance with GPT-4o
skill-seekers enhance output/react/ --target openai
# 3. Package for OpenAI
skill-seekers package output/react/ --target openai
# 4. Upload (creates Assistant + Vector Store)
skill-seekers upload react-openai.zip --target openai
# Access at: https://platform.openai.com/assistants/
```
### Workflow 4: Export to All Platforms
```bash
# Install all platforms
pip install skill-seekers[all-llms]
# Scrape once
skill-seekers scrape --config configs/react.json
# Package for all platforms
skill-seekers package output/react/ --target claude
skill-seekers package output/react/ --target gemini
skill-seekers package output/react/ --target openai
skill-seekers package output/react/ --target markdown
# Result:
# - react.zip (Claude)
# - react-gemini.tar.gz (Gemini)
# - react-openai.zip (OpenAI)
# - react-markdown.zip (Universal)
```
## Advanced Usage
### Custom Enhancement Models
Each platform uses its default enhancement model, but you can customize:
```bash
# Use specific model for enhancement (if supported)
skill-seekers enhance output/react/ --target gemini --model gemini-2.0-flash-exp
skill-seekers enhance output/react/ --target openai --model gpt-4o
```
### Programmatic Usage
```python
from skill_seekers.cli.adaptors import get_adaptor
# Get platform-specific adaptor
gemini = get_adaptor('gemini')
openai = get_adaptor('openai')
claude = get_adaptor('claude')
# Package for specific platform
gemini_package = gemini.package(skill_dir, output_path)
openai_package = openai.package(skill_dir, output_path)
# Upload with API key
result = gemini.upload(gemini_package, api_key)
print(f"Uploaded to: {result['url']}")
```
### Platform Detection
Check which platforms are available:
```python
from skill_seekers.cli.adaptors import list_platforms, is_platform_available
# List all registered platforms
platforms = list_platforms()
print(platforms) # ['claude', 'gemini', 'openai', 'markdown']
# Check if platform is available
if is_platform_available('gemini'):
print("Gemini adaptor is available")
```
## Backward Compatibility
**100% backward compatible** with existing workflows:
- All existing Claude commands work unchanged
- Default behavior remains Claude-focused
- Optional `--target` flag adds multi-platform support
- No breaking changes to existing configs or workflows
## Platform-Specific Guides
For detailed platform-specific instructions, see:
- [Claude AI Integration](CLAUDE_INTEGRATION.md) (default)
- [Google Gemini Integration](GEMINI_INTEGRATION.md)
- [OpenAI ChatGPT Integration](OPENAI_INTEGRATION.md)
## Troubleshooting
### Missing Dependencies
**Error:** `ModuleNotFoundError: No module named 'google.generativeai'`
**Solution:**
```bash
pip install skill-seekers[gemini]
```
**Error:** `ModuleNotFoundError: No module named 'openai'`
**Solution:**
```bash
pip install skill-seekers[openai]
```
### API Key Issues
**Error:** `Invalid API key format`
**Solution:** Check your API key format:
- Claude: `sk-ant-...`
- Gemini: `AIza...`
- OpenAI: `sk-proj-...` or `sk-...`
### Package Format Errors
**Error:** `Not a tar.gz file: react.zip`
**Solution:** Use correct --target flag:
```bash
# Gemini requires tar.gz
skill-seekers package output/react/ --target gemini
# OpenAI and Claude use ZIP
skill-seekers package output/react/ --target openai
```
## FAQ
**Q: Can I use the same scraped data for all platforms?**
A: Yes! The scraping phase is universal. Only packaging and upload are platform-specific.
**Q: Do I need separate API keys for each platform?**
A: Yes, each platform requires its own API key. Set them as environment variables.
**Q: Can I enhance with different models?**
A: Yes, each platform uses its own enhancement model:
- Claude: Claude Sonnet 4
- Gemini: Gemini 2.0 Flash
- OpenAI: GPT-4o
**Q: What if I don't want to upload automatically?**
A: Use the `package` command without `upload`. You'll get the packaged file to upload manually.
**Q: Is the markdown export compatible with all LLMs?**
A: Yes! The generic markdown export creates universal documentation that works with any LLM or documentation system.
**Q: Can I contribute a new platform adaptor?**
A: Absolutely! See the [Contributing Guide](../CONTRIBUTING.md) for how to add new platform adaptors.
## Next Steps
1. Choose your target platform
2. Install optional dependencies if needed
3. Set up API keys
4. Follow the platform-specific workflow
5. Upload and test your skill
For more help, see:
- [Quick Start Guide](../QUICKSTART.md)
- [Troubleshooting Guide](../TROUBLESHOOTING.md)
- [Platform-Specific Guides](.)

515
docs/OPENAI_INTEGRATION.md Normal file
View File

@@ -0,0 +1,515 @@
# OpenAI ChatGPT Integration Guide
Complete guide for creating and deploying skills to OpenAI ChatGPT using Skill Seekers.
## Overview
Skill Seekers packages documentation into OpenAI-compatible formats optimized for:
- **Assistants API** for custom AI assistants
- **Vector Store + File Search** for accurate retrieval
- **GPT-4o** for enhancement and responses
## Setup
### 1. Install OpenAI Support
```bash
# Install with OpenAI dependencies
pip install skill-seekers[openai]
# Verify installation
pip list | grep openai
```
### 2. Get OpenAI API Key
1. Visit [OpenAI Platform](https://platform.openai.com/)
2. Navigate to **API keys** section
3. Click "Create new secret key"
4. Copy the key (starts with `sk-proj-` or `sk-`)
### 3. Configure API Key
```bash
# Set as environment variable (recommended)
export OPENAI_API_KEY=sk-proj-...
# Or pass directly to commands
skill-seekers upload --target openai --api-key sk-proj-...
```
## Complete Workflow
### Step 1: Scrape Documentation
```bash
# Use any config (scraping is platform-agnostic)
skill-seekers scrape --config configs/react.json
# Or use a unified config for multi-source
skill-seekers unified --config configs/react_unified.json
```
**Result:** `output/react/` skill directory with references
### Step 2: Enhance with GPT-4o (Optional but Recommended)
```bash
# Enhance SKILL.md using GPT-4o
skill-seekers enhance output/react/ --target openai
# With API key specified
skill-seekers enhance output/react/ --target openai --api-key sk-proj-...
```
**What it does:**
- Analyzes all reference documentation
- Extracts 5-10 best code examples
- Creates comprehensive assistant instructions
- Adds response guidelines and search strategy
- Formats as plain text (no YAML frontmatter)
**Time:** 20-40 seconds
**Cost:** ~$0.15-0.30 (using GPT-4o)
**Quality boost:** 3/10 → 9/10
### Step 3: Package for OpenAI
```bash
# Create ZIP package for OpenAI Assistants
skill-seekers package output/react/ --target openai
# Result: react-openai.zip
```
**Package structure:**
```
react-openai.zip/
├── assistant_instructions.txt # Main instructions for Assistant
├── vector_store_files/ # Files for Vector Store + file_search
│ ├── getting_started.md
│ ├── hooks.md
│ ├── components.md
│ └── ...
└── openai_metadata.json # Platform metadata
```
### Step 4: Upload to OpenAI (Creates Assistant)
```bash
# Upload and create Assistant with Vector Store
skill-seekers upload react-openai.zip --target openai
# With API key
skill-seekers upload react-openai.zip --target openai --api-key sk-proj-...
```
**What it does:**
1. Creates Vector Store for documentation
2. Uploads reference files to Vector Store
3. Creates Assistant with file_search tool
4. Links Vector Store to Assistant
**Output:**
```
✅ Upload successful!
Assistant ID: asst_abc123xyz
URL: https://platform.openai.com/assistants/asst_abc123xyz
Message: Assistant created with 15 knowledge files
```
### Step 5: Use Your Assistant
Access your assistant in the OpenAI Platform:
1. Go to [OpenAI Platform](https://platform.openai.com/assistants)
2. Find your assistant in the list
3. Test in Playground or use via API
## What Makes OpenAI Different?
### Format: Assistant Instructions (Plain Text)
**Claude format:**
```markdown
---
name: react
---
# React Documentation
...
```
**OpenAI format:**
```text
You are an expert assistant for React.
Your Knowledge Base:
- Getting started guide
- React hooks reference
- Component API
When users ask questions about React:
1. Search the knowledge files
2. Provide code examples
...
```
Plain text instructions optimized for Assistant API.
### Architecture: Assistant + Vector Store
OpenAI uses a two-part system:
1. **Assistant** - The AI agent with instructions and tools
2. **Vector Store** - Embedded documentation for semantic search
### Tool: file_search
The Assistant uses the `file_search` tool to:
- Semantically search documentation
- Find relevant code examples
- Provide accurate, source-based answers
## Using Your OpenAI Assistant
### Option 1: OpenAI Playground (Web UI)
1. Go to [OpenAI Platform](https://platform.openai.com/assistants)
2. Select your assistant
3. Click "Test in Playground"
4. Ask questions about your documentation
### Option 2: Assistants API (Python)
```python
from openai import OpenAI
# Initialize client
client = OpenAI(api_key='sk-proj-...')
# Create thread
thread = client.beta.threads.create()
# Send message
message = client.beta.threads.messages.create(
thread_id=thread.id,
role="user",
content="How do I use React hooks?"
)
# Run assistant
run = client.beta.threads.runs.create(
thread_id=thread.id,
assistant_id='asst_abc123xyz' # Your assistant ID
)
# Wait for completion
while run.status != 'completed':
run = client.beta.threads.runs.retrieve(thread_id=thread.id, run_id=run.id)
# Get response
messages = client.beta.threads.messages.list(thread_id=thread.id)
print(messages.data[0].content[0].text.value)
```
### Option 3: Streaming Responses
```python
from openai import OpenAI
client = OpenAI(api_key='sk-proj-...')
# Create thread and message
thread = client.beta.threads.create()
client.beta.threads.messages.create(
thread_id=thread.id,
role="user",
content="Explain React hooks"
)
# Stream response
with client.beta.threads.runs.stream(
thread_id=thread.id,
assistant_id='asst_abc123xyz'
) as stream:
for event in stream:
if event.event == 'thread.message.delta':
print(event.data.delta.content[0].text.value, end='')
```
## Advanced Usage
### Update Assistant Instructions
```python
from openai import OpenAI
client = OpenAI(api_key='sk-proj-...')
# Update assistant
client.beta.assistants.update(
assistant_id='asst_abc123xyz',
instructions="""
You are an expert React assistant.
Focus on modern best practices using:
- React 18+ features
- Functional components
- Hooks-based patterns
When answering:
1. Search knowledge files first
2. Provide working code examples
3. Explain the "why" not just the "what"
"""
)
```
### Add More Files to Vector Store
```python
from openai import OpenAI
client = OpenAI(api_key='sk-proj-...')
# Upload new file
with open('new_guide.md', 'rb') as f:
file = client.files.create(file=f, purpose='assistants')
# Add to vector store
client.beta.vector_stores.files.create(
vector_store_id='vs_abc123',
file_id=file.id
)
```
### Programmatic Package and Upload
```python
from skill_seekers.cli.adaptors import get_adaptor
from pathlib import Path
# Get adaptor
openai_adaptor = get_adaptor('openai')
# Package skill
package_path = openai_adaptor.package(
skill_dir=Path('output/react'),
output_path=Path('output/react-openai.zip')
)
# Upload (creates Assistant + Vector Store)
result = openai_adaptor.upload(
package_path=package_path,
api_key='sk-proj-...'
)
if result['success']:
print(f"✅ Assistant created!")
print(f"ID: {result['skill_id']}")
print(f"URL: {result['url']}")
else:
print(f"❌ Upload failed: {result['message']}")
```
## OpenAI-Specific Features
### 1. Semantic Search (file_search)
The Assistant uses embeddings to:
- Find semantically similar content
- Understand intent vs. keywords
- Surface relevant examples automatically
### 2. Citations and Sources
Assistants can provide:
- Source attribution
- File references
- Quote extraction
### 3. Function Calling (Optional)
Extend your assistant with custom tools:
```python
client.beta.assistants.update(
assistant_id='asst_abc123xyz',
tools=[
{"type": "file_search"},
{"type": "function", "function": {
"name": "run_code_example",
"description": "Execute React code examples",
"parameters": {...}
}}
]
)
```
### 4. Multi-Modal Support
Include images in your documentation:
- Screenshots
- Diagrams
- Architecture charts
## Troubleshooting
### Issue: `openai not installed`
**Solution:**
```bash
pip install skill-seekers[openai]
```
### Issue: `Invalid API key format`
**Error:** API key doesn't start with `sk-`
**Solution:**
- Get new key from [OpenAI Platform](https://platform.openai.com/api-keys)
- Verify you're using API key, not organization ID
### Issue: `Not a ZIP file`
**Error:** Wrong package format
**Solution:**
```bash
# Use --target openai for ZIP format
skill-seekers package output/react/ --target openai
# NOT:
skill-seekers package output/react/ --target gemini # Creates .tar.gz
```
### Issue: `Assistant creation failed`
**Possible causes:**
- API key lacks permissions
- Rate limit exceeded
- File too large
**Solution:**
```bash
# Verify API key
python3 -c "from openai import OpenAI; print(OpenAI(api_key='sk-proj-...').models.list())"
# Check rate limits
# Visit: https://platform.openai.com/account/limits
# Reduce file count
skill-seekers package output/react/ --target openai --max-files 20
```
### Issue: Enhancement fails
**Solution:**
```bash
# Check API quota and billing
# Visit: https://platform.openai.com/account/billing
# Try with smaller skill
skill-seekers enhance output/react/ --target openai --max-files 5
# Use without enhancement
skill-seekers package output/react/ --target openai
# (Skip enhancement step)
```
### Issue: file_search not working
**Symptoms:** Assistant doesn't reference documentation
**Solution:**
- Verify Vector Store has files
- Check Assistant tool configuration
- Test with explicit instructions: "Search the knowledge files for information about hooks"
## Best Practices
### 1. Write Clear Assistant Instructions
Focus on:
- Role definition
- Knowledge base description
- Response guidelines
- Search strategy
### 2. Organize Vector Store Files
- Keep files under 512KB each
- Use clear, descriptive filenames
- Structure content with headings
- Include code examples
### 3. Test Assistant Behavior
Test with varied questions:
```
1. Simple facts: "What is React?"
2. How-to questions: "How do I create a component?"
3. Best practices: "What's the best way to manage state?"
4. Troubleshooting: "Why isn't my hook working?"
```
### 4. Monitor Token Usage
```python
# Track tokens in API responses
run = client.beta.threads.runs.retrieve(thread_id=thread.id, run_id=run.id)
print(f"Input tokens: {run.usage.prompt_tokens}")
print(f"Output tokens: {run.usage.completion_tokens}")
```
### 5. Update Regularly
```bash
# Re-scrape updated documentation
skill-seekers scrape --config configs/react.json
# Re-enhance and upload (creates new Assistant)
skill-seekers enhance output/react/ --target openai
skill-seekers package output/react/ --target openai
skill-seekers upload react-openai.zip --target openai
```
## Cost Estimation
**GPT-4o pricing (as of 2024):**
- Input: $2.50 per 1M tokens
- Output: $10.00 per 1M tokens
**Typical skill enhancement:**
- Input: ~50K-200K tokens (docs)
- Output: ~5K-10K tokens (enhanced instructions)
- Cost: $0.15-0.30 per skill
**Vector Store:**
- $0.10 per GB per day (storage)
- Typical skill: < 100MB = ~$0.01/day
**API usage:**
- Varies by question volume
- ~$0.01-0.05 per conversation
## Next Steps
1. ✅ Install OpenAI support: `pip install skill-seekers[openai]`
2. ✅ Get API key from OpenAI Platform
3. ✅ Scrape your documentation
4. ✅ Enhance with GPT-4o
5. ✅ Package for OpenAI
6. ✅ Upload and create Assistant
7. ✅ Test in Playground
## Resources
- [OpenAI Platform](https://platform.openai.com/)
- [Assistants API Documentation](https://platform.openai.com/docs/assistants/overview)
- [OpenAI Pricing](https://openai.com/pricing)
- [Multi-LLM Support Guide](MULTI_LLM_SUPPORT.md)
## Feedback
Found an issue or have suggestions? [Open an issue](https://github.com/yusufkaraaslan/Skill_Seekers/issues)

683
docs/UPLOAD_GUIDE.md
View File

@@ -1,351 +1,446 @@
# How to Upload Skills to Claude
# Multi-Platform Upload Guide
## Quick Answer
Skill Seekers supports uploading to **4 LLM platforms**: Claude AI, Google Gemini, OpenAI ChatGPT, and Generic Markdown export.
**You have 3 options to upload the `.zip` file:**
## Quick Platform Selection
### Option 1: Automatic Upload (Recommended for CLI)
```bash
# Set your API key (one-time setup)
export ANTHROPIC_API_KEY=sk-ant-...
# Package and upload automatically
python3 cli/package_skill.py output/react/ --upload
# OR upload existing .zip
python3 cli/upload_skill.py output/react.zip
```
✅ **Fully automatic** | No manual steps | Requires API key
### Option 2: Manual Upload (No API Key)
```bash
# Package the skill
python3 cli/package_skill.py output/react/
# This will:
# 1. Create output/react.zip
# 2. Open output/ folder automatically
# 3. Show clear upload instructions
# Then upload manually to https://claude.ai/skills
```
✅ **No API key needed** | Works for everyone | Simple
### Option 3: Claude Code MCP (Easiest)
```
In Claude Code, just say:
"Package and upload the React skill"
# Automatically packages and uploads!
```
✅ **Natural language** | Fully automatic | Best UX
| Platform | Best For | Upload Method | API Key Required |
|----------|----------|---------------|------------------|
| **Claude AI** | General use, MCP integration | API or Manual | ANTHROPIC_API_KEY |
| **Google Gemini** | Long context (1M tokens) | API | GOOGLE_API_KEY |
| **OpenAI ChatGPT** | Vector search, Assistants API | API | OPENAI_API_KEY |
| **Generic Markdown** | Universal compatibility, offline | Manual distribution | None |
---
## What's Inside the Zip?
## Claude AI (Default)
The `.zip` file contains:
### Prerequisites
```
steam-economy.zip
├── SKILL.md ← Main skill file (Claude reads this first)
└── references/ ← Reference documentation
├── index.md ← Category index
├── api_reference.md ← API docs
├── pricing.md ← Pricing docs
├── trading.md ← Trading docs
└── ... ← Other categorized docs
```
**Note:** The zip only includes what Claude needs. It excludes:
- `.backup` files
- Build artifacts
- Temporary files
## What Does package_skill.py Do?
The package script:
1. **Finds your skill directory** (e.g., `output/steam-economy/`)
2. **Validates SKILL.md exists** (required!)
3. **Creates a .zip file** with the same name
4. **Includes all files** except backups
5. **Saves to** `output/` directory
**Example:**
```bash
python3 cli/package_skill.py output/steam-economy/
# Option 1: Set API key for automatic upload
export ANTHROPIC_API_KEY=sk-ant-...
📦 Packaging skill: steam-economy
Source: output/steam-economy
Output: output/steam-economy.zip
+ SKILL.md
+ references/api_reference.md
+ references/pricing.md
+ references/trading.md
+ ...
✅ Package created: output/steam-economy.zip
Size: 14,290 bytes (14.0 KB)
# Option 2: No API key (manual upload)
# No setup needed - just package and upload manually
```
### Package for Claude
```bash
# Claude uses ZIP format (default)
skill-seekers package output/react/
```
**Output:** `output/react.zip`
### Upload to Claude
**Option 1: Automatic (with API key)**
```bash
skill-seekers upload output/react.zip
```
**Option 2: Manual (no API key)**
1. Go to https://claude.ai/skills
2. Click "Upload Skill" or "Add Skill"
3. Select `output/react.zip`
4. Done!
**Option 3: MCP (easiest)**
```
In Claude Code, just say:
"Package and upload the React skill"
```
**What's inside the ZIP:**
```
react.zip
├── SKILL.md ← Main skill file (YAML frontmatter + markdown)
└── references/ ← Reference documentation
├── index.md
├── api.md
└── ...
```
---
## Google Gemini
### Prerequisites
```bash
# Install Gemini support
pip install skill-seekers[gemini]
# Set API key
export GOOGLE_API_KEY=AIzaSy...
```
### Package for Gemini
```bash
# Gemini uses tar.gz format
skill-seekers package output/react/ --target gemini
```
**Output:** `output/react-gemini.tar.gz`
### Upload to Gemini
```bash
skill-seekers upload output/react-gemini.tar.gz --target gemini
```
**What happens:**
- Uploads to Google Files API
- Creates grounding resource
- Available in Google AI Studio
**Access your skill:**
- Go to https://aistudio.google.com/
- Your skill is available as grounding data
**What's inside the tar.gz:**
```
react-gemini.tar.gz
├── system_instructions.md ← Main skill file (plain markdown, no frontmatter)
├── references/ ← Reference documentation
│ ├── index.md
│ ├── api.md
│ └── ...
└── gemini_metadata.json ← Gemini-specific metadata
```
**Format differences:**
- No YAML frontmatter (Gemini uses plain markdown)
- `SKILL.md` → `system_instructions.md`
- Includes `gemini_metadata.json` for platform integration
---
## OpenAI ChatGPT
### Prerequisites
```bash
# Install OpenAI support
pip install skill-seekers[openai]
# Set API key
export OPENAI_API_KEY=sk-proj-...
```
### Package for OpenAI
```bash
# OpenAI uses ZIP format with vector store
skill-seekers package output/react/ --target openai
```
**Output:** `output/react-openai.zip`
### Upload to OpenAI
```bash
skill-seekers upload output/react-openai.zip --target openai
```
**What happens:**
- Creates OpenAI Assistant via Assistants API
- Creates Vector Store for semantic search
- Uploads reference files to vector store
- Enables `file_search` tool automatically
**Access your assistant:**
- Go to https://platform.openai.com/assistants/
- Your assistant is listed with name based on skill
- Includes file search enabled
**What's inside the ZIP:**
```
react-openai.zip
├── assistant_instructions.txt ← Main skill file (plain text, no YAML)
├── vector_store_files/ ← Files for vector store
│ ├── index.md
│ ├── api.md
│ └── ...
└── openai_metadata.json ← OpenAI-specific metadata
```
**Format differences:**
- No YAML frontmatter (OpenAI uses plain text)
- `SKILL.md` → `assistant_instructions.txt`
- Reference files packaged separately for Vector Store
- Includes `openai_metadata.json` for assistant configuration
**Unique features:**
- ✅ Semantic search across documentation
- ✅ Vector Store for efficient retrieval
- ✅ File search tool enabled by default
---
## Generic Markdown (Universal Export)
### Package for Markdown
```bash
# Generic markdown for manual distribution
skill-seekers package output/react/ --target markdown
```
**Output:** `output/react-markdown.zip`
### Distribution
**No upload API available** - Use for manual distribution:
- Share ZIP file directly
- Upload to documentation hosting
- Include in git repositories
- Use with any LLM that accepts markdown
**What's inside the ZIP:**
```
react-markdown.zip
├── README.md ← Getting started guide
├── DOCUMENTATION.md ← Combined documentation
├── references/ ← Separate reference files
│ ├── index.md
│ ├── api.md
│ └── ...
└── manifest.json ← Skill metadata
```
**Format differences:**
- No platform-specific formatting
- Pure markdown - works anywhere
- Combined `DOCUMENTATION.md` for easy reading
- Separate `references/` for modular access
**Use cases:**
- Works with **any LLM** (local models, other platforms)
- Documentation website hosting
- Offline documentation
- Share via git/email
- Include in project repositories
---
## Complete Workflow
### Step 1: Scrape & Build
### Single Platform (Claude)
```bash
python3 cli/doc_scraper.py --config configs/steam-economy.json
# 1. Scrape documentation
skill-seekers scrape --config configs/react.json
# 2. Enhance (recommended)
skill-seekers enhance output/react/
# 3. Package for Claude (default)
skill-seekers package output/react/
# 4. Upload to Claude
skill-seekers upload output/react.zip
```
**Output:**
- `output/steam-economy_data/` (raw scraped data)
- `output/steam-economy/` (skill directory)
### Multi-Platform (Same Skill)
### Step 2: Enhance (Recommended)
```bash
python3 cli/enhance_skill_local.py output/steam-economy/
# 1. Scrape once (universal)
skill-seekers scrape --config configs/react.json
# 2. Enhance once (or per-platform if desired)
skill-seekers enhance output/react/
# 3. Package for ALL platforms
skill-seekers package output/react/ --target claude
skill-seekers package output/react/ --target gemini
skill-seekers package output/react/ --target openai
skill-seekers package output/react/ --target markdown
# 4. Upload to platforms
export ANTHROPIC_API_KEY=sk-ant-...
export GOOGLE_API_KEY=AIzaSy...
export OPENAI_API_KEY=sk-proj-...
skill-seekers upload output/react.zip --target claude
skill-seekers upload output/react-gemini.tar.gz --target gemini
skill-seekers upload output/react-openai.zip --target openai
# Result:
# - react.zip (Claude)
# - react-gemini.tar.gz (Gemini)
# - react-openai.zip (OpenAI)
# - react-markdown.zip (Universal)
```
**What it does:**
- Analyzes reference files
- Creates comprehensive SKILL.md
- Backs up original to SKILL.md.backup
**Output:**
- `output/steam-economy/SKILL.md` (enhanced)
- `output/steam-economy/SKILL.md.backup` (original)
### Step 3: Package
```bash
python3 cli/package_skill.py output/steam-economy/
```
**Output:**
- `output/steam-economy.zip` ← **THIS IS WHAT YOU UPLOAD**
### Step 4: Upload to Claude
1. Go to Claude (claude.ai)
2. Click "Add Skill" or skill upload button
3. Select `output/steam-economy.zip`
4. Done!
## What Files Are Required?
**Minimum required structure:**
```
your-skill/
└── SKILL.md ← Required! Claude reads this first
```
**Recommended structure:**
```
your-skill/
├── SKILL.md ← Main skill file (required)
└── references/ ← Reference docs (highly recommended)
├── index.md
└── *.md ← Category files
```
**Optional (can add manually):**
```
your-skill/
├── SKILL.md
├── references/
├── scripts/ ← Helper scripts
│ └── *.py
└── assets/ ← Templates, examples
└── *.txt
```
---
## File Size Limits
The package script shows size after packaging:
```
✅ Package created: output/steam-economy.zip
Size: 14,290 bytes (14.0 KB)
### Platform Limits
| Platform | File Size Limit | Typical Skill Size |
|----------|----------------|-------------------|
| Claude AI | ~25 MB per skill | 10-500 KB |
| Google Gemini | ~100 MB per file | 10-500 KB |
| OpenAI ChatGPT | ~512 MB vector store | 10-500 KB |
| Generic Markdown | No limit | 10-500 KB |
**Check package size:**
```bash
ls -lh output/react.zip
```
**Typical sizes:**
**Most skills are small:**
- Small skill: 5-20 KB
- Medium skill: 20-100 KB
- Large skill: 100-500 KB
Claude has generous size limits, so most documentation-based skills fit easily.
## Quick Reference
### Package a Skill
```bash
python3 cli/package_skill.py output/steam-economy/
```
### Package Multiple Skills
```bash
# Package all skills in output/
for dir in output/*/; do
if [ -f "$dir/SKILL.md" ]; then
python3 cli/package_skill.py "$dir"
fi
done
```
### Check What's in a Zip
```bash
unzip -l output/steam-economy.zip
```
### Test a Packaged Skill Locally
```bash
# Extract to temp directory
mkdir temp-test
unzip output/steam-economy.zip -d temp-test/
cat temp-test/SKILL.md
```
---
## Troubleshooting
### "SKILL.md not found"
```bash
# Make sure you scraped and built first
python3 cli/doc_scraper.py --config configs/steam-economy.json
# Then package
python3 cli/package_skill.py output/steam-economy/
Make sure you scraped and built first:
```bash
skill-seekers scrape --config configs/react.json
skill-seekers package output/react/
```
### "Directory not found"
```bash
# Check what skills are available
ls output/
### "Invalid target platform"
# Use correct path
python3 cli/package_skill.py output/YOUR-SKILL-NAME/
Use valid platform names:
```bash
# Valid
--target claude
--target gemini
--target openai
--target markdown
# Invalid
--target anthropic ❌
--target google ❌
```
### Zip is Too Large
Most skills are small, but if yours is large:
```bash
# Check size
ls -lh output/steam-economy.zip
# If needed, check what's taking space
unzip -l output/steam-economy.zip | sort -k1 -rn | head -20
```
Reference files are usually small. Large sizes often mean:
- Many images (skills typically don't need images)
- Large code examples (these are fine, just be aware)
## What Does Claude Do With the Zip?
When you upload a skill zip:
1. **Claude extracts it**
2. **Reads SKILL.md first** - This tells Claude:
- When to activate this skill
- What the skill does
- Quick reference examples
- How to navigate the references
3. **Indexes reference files** - Claude can search through:
- `references/*.md` files
- Find specific APIs, examples, concepts
4. **Activates automatically** - When you ask about topics matching the skill
## Example: Using the Packaged Skill
After uploading `steam-economy.zip`:
**You ask:** "How do I implement microtransactions in my Steam game?"
### "API key not set"
**Claude:**
- Recognizes this matches steam-economy skill
- Reads SKILL.md for quick reference
- Searches references/microtransactions.md
- Provides detailed answer with code examples
## API-Based Automatic Upload
### Setup (One-Time)
```bash
# Get your API key from https://console.anthropic.com/
export ANTHROPIC_API_KEY=sk-ant-...
# Add to your shell profile to persist
echo 'export ANTHROPIC_API_KEY=sk-ant-...' >> ~/.bashrc # or ~/.zshrc
```
### Usage
```bash
# Upload existing .zip
python3 cli/upload_skill.py output/react.zip
# OR package and upload in one command
python3 cli/package_skill.py output/react/ --upload
```
### How It Works
The upload tool uses the Anthropic `/v1/skills` API endpoint to:
1. Read your .zip file
2. Authenticate with your API key
3. Upload to Claude's skill storage
4. Verify upload success
### Troubleshooting
**"ANTHROPIC_API_KEY not set"**
```bash
# Check if set
echo $ANTHROPIC_API_KEY
# If empty, set it
export ANTHROPIC_API_KEY=sk-ant-...
```
**"Authentication failed"**
- Verify your API key is correct
- Check https://console.anthropic.com/ for valid keys
**Gemini:**
```bash
export GOOGLE_API_KEY=AIzaSy...
pip install skill-seekers[gemini]
```
**"Upload timed out"**
- Check your internet connection
- Try again or use manual upload
**OpenAI:**
```bash
export OPENAI_API_KEY=sk-proj-...
pip install skill-seekers[openai]
```
**Upload fails with error**
- Falls back to showing manual upload instructions
- You can still upload via https://claude.ai/skills
### Upload fails
If API upload fails, you can always use manual upload:
- **Claude:** https://claude.ai/skills
- **Gemini:** https://aistudio.google.com/
- **OpenAI:** https://platform.openai.com/assistants/
### Wrong file format
Each platform requires specific format:
- Claude/OpenAI/Markdown: `.zip` file
- Gemini: `.tar.gz` file
Make sure to use `--target` parameter when packaging.
---
## Summary
## Platform Comparison
**What you need to do:**
### Format Comparison
### With API Key (Automatic):
1. ✅ Scrape: `python3 cli/doc_scraper.py --config configs/YOUR-CONFIG.json`
2. ✅ Enhance: `python3 cli/enhance_skill_local.py output/YOUR-SKILL/`
3. ✅ Package & Upload: `python3 cli/package_skill.py output/YOUR-SKILL/ --upload`
4. ✅ Done! Skill is live in Claude
| Feature | Claude | Gemini | OpenAI | Markdown |
|---------|--------|--------|--------|----------|
| **File Format** | ZIP | tar.gz | ZIP | ZIP |
| **Main File** | SKILL.md | system_instructions.md | assistant_instructions.txt | README.md + DOCUMENTATION.md |
| **Frontmatter** | ✅ YAML | ❌ Plain MD | ❌ Plain Text | ❌ Plain MD |
| **References** | references/ | references/ | vector_store_files/ | references/ |
| **Metadata** | In frontmatter | gemini_metadata.json | openai_metadata.json | manifest.json |
### Without API Key (Manual):
1. ✅ Scrape: `python3 cli/doc_scraper.py --config configs/YOUR-CONFIG.json`
2. ✅ Enhance: `python3 cli/enhance_skill_local.py output/YOUR-SKILL/`
3. ✅ Package: `python3 cli/package_skill.py output/YOUR-SKILL/`
4. ✅ Upload: Go to https://claude.ai/skills and upload the `.zip`
### Upload Comparison
**What you upload:**
- The `.zip` file from `output/` directory
- Example: `output/steam-economy.zip`
| Feature | Claude | Gemini | OpenAI | Markdown |
|---------|--------|--------|--------|----------|
| **API Upload** | ✅ Yes | ✅ Yes | ✅ Yes | ❌ Manual only |
| **Manual Upload** | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes (distribute) |
| **MCP Support** | ✅ Full | ✅ Full | ✅ Full | ✅ Package only |
| **Web Interface** | claude.ai/skills | aistudio.google.com | platform.openai.com/assistants | N/A |
**What's in the zip:**
- `SKILL.md` (required)
- `references/*.md` (recommended)
- Any scripts/assets you added (optional)
### Enhancement Comparison
That's it! 🚀
| Feature | Claude | Gemini | OpenAI | Markdown |
|---------|--------|--------|--------|----------|
| **AI Enhancement** | ✅ Sonnet 4 | ✅ Gemini 2.0 | ✅ GPT-4o | ❌ No |
| **Local Mode** | ✅ Yes (free) | ❌ No | ❌ No | ❌ N/A |
| **API Mode** | ✅ Yes | ✅ Yes | ✅ Yes | ❌ N/A |
| **Format Changes** | Keeps YAML | → Plain MD | → Plain Text | N/A |
---
## API Key Setup
### Get API Keys
**Claude (Anthropic):**
1. Go to https://console.anthropic.com/
2. Create API key
3. Copy key (starts with `sk-ant-`)
4. `export ANTHROPIC_API_KEY=sk-ant-...`
**Gemini (Google):**
1. Go to https://aistudio.google.com/
2. Get API key
3. Copy key (starts with `AIza`)
4. `export GOOGLE_API_KEY=AIzaSy...`
**OpenAI:**
1. Go to https://platform.openai.com/
2. Create API key
3. Copy key (starts with `sk-proj-`)
4. `export OPENAI_API_KEY=sk-proj-...`
### Persist API Keys
Add to shell profile to keep them set:
```bash
# macOS/Linux (bash)
echo 'export ANTHROPIC_API_KEY=sk-ant-...' >> ~/.bashrc
echo 'export GOOGLE_API_KEY=AIzaSy...' >> ~/.bashrc
echo 'export OPENAI_API_KEY=sk-proj-...' >> ~/.bashrc
# macOS (zsh)
echo 'export ANTHROPIC_API_KEY=sk-ant-...' >> ~/.zshrc
echo 'export GOOGLE_API_KEY=AIzaSy...' >> ~/.zshrc
echo 'export OPENAI_API_KEY=sk-proj-...' >> ~/.zshrc
```
Then restart your terminal or run:
```bash
source ~/.bashrc # or ~/.zshrc
```
---
## See Also
- [FEATURE_MATRIX.md](FEATURE_MATRIX.md) - Complete feature comparison
- [MULTI_LLM_SUPPORT.md](MULTI_LLM_SUPPORT.md) - Multi-platform guide
- [ENHANCEMENT.md](ENHANCEMENT.md) - AI enhancement guide
- [README.md](../README.md) - Main documentation

21
pyproject.toml
View File

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
[project]
name = "skill-seekers"
version = "2.4.0"
version = "2.5.0"
description = "Convert documentation websites, GitHub repositories, and PDFs into Claude AI skills"
readme = "README.md"
requires-python = ">=3.10"
@@ -76,6 +76,23 @@ mcp = [
"sse-starlette>=3.0.2",
]
# LLM platform-specific dependencies
# Google Gemini support
gemini = [
"google-generativeai>=0.8.0",
]
# OpenAI ChatGPT support
openai = [
"openai>=1.0.0",
]
# All LLM platforms combined
all-llms = [
"google-generativeai>=0.8.0",
"openai>=1.0.0",
]
# All optional dependencies combined
all = [
"pytest>=8.4.2",
@@ -88,6 +105,8 @@ all = [
"uvicorn>=0.38.0",
"starlette>=0.48.0",
"sse-starlette>=3.0.2",
"google-generativeai>=0.8.0",
"openai>=1.0.0",
]
[project.urls]

124
src/skill_seekers/cli/adaptors/__init__.py Normal file
View File

@@ -0,0 +1,124 @@
#!/usr/bin/env python3
"""
Multi-LLM Adaptor Registry
Provides factory function to get platform-specific adaptors for skill generation.
Supports Claude AI, Google Gemini, OpenAI ChatGPT, and generic Markdown export.
"""
from typing import Dict, Type
from .base import SkillAdaptor, SkillMetadata
# Import adaptors (some may not be implemented yet)
try:
from .claude import ClaudeAdaptor
except ImportError:
ClaudeAdaptor = None
try:
from .gemini import GeminiAdaptor
except ImportError:
GeminiAdaptor = None
try:
from .openai import OpenAIAdaptor
except ImportError:
OpenAIAdaptor = None
try:
from .markdown import MarkdownAdaptor
except ImportError:
MarkdownAdaptor = None
# Registry of available adaptors
ADAPTORS: Dict[str, Type[SkillAdaptor]] = {}
# Register adaptors that are implemented
if ClaudeAdaptor:
ADAPTORS['claude'] = ClaudeAdaptor
if GeminiAdaptor:
ADAPTORS['gemini'] = GeminiAdaptor
if OpenAIAdaptor:
ADAPTORS['openai'] = OpenAIAdaptor
if MarkdownAdaptor:
ADAPTORS['markdown'] = MarkdownAdaptor
def get_adaptor(platform: str, config: dict = None) -> SkillAdaptor:
"""
Factory function to get platform-specific adaptor instance.
Args:
platform: Platform identifier ('claude', 'gemini', 'openai', 'markdown')
config: Optional platform-specific configuration
Returns:
SkillAdaptor instance for the specified platform
Raises:
ValueError: If platform is not supported or not yet implemented
Examples:
>>> adaptor = get_adaptor('claude')
>>> adaptor = get_adaptor('gemini', {'api_version': 'v1beta'})
"""
if platform not in ADAPTORS:
available = ', '.join(ADAPTORS.keys())
if not ADAPTORS:
raise ValueError(
f"No adaptors are currently implemented. "
f"Platform '{platform}' is not available."
)
raise ValueError(
f"Platform '{platform}' is not supported or not yet implemented. "
f"Available platforms: {available}"
)
adaptor_class = ADAPTORS[platform]
return adaptor_class(config)
def list_platforms() -> list[str]:
"""
List all supported platforms.
Returns:
List of platform identifiers
Examples:
>>> list_platforms()
['claude', 'gemini', 'openai', 'markdown']
"""
return list(ADAPTORS.keys())
def is_platform_available(platform: str) -> bool:
"""
Check if a platform adaptor is available.
Args:
platform: Platform identifier to check
Returns:
True if platform is available
Examples:
>>> is_platform_available('claude')
True
>>> is_platform_available('unknown')
False
"""
return platform in ADAPTORS
# Export public interface
__all__ = [
'SkillAdaptor',
'SkillMetadata',
'get_adaptor',
'list_platforms',
'is_platform_available',
'ADAPTORS',
]

220
src/skill_seekers/cli/adaptors/base.py Normal file
View File

@@ -0,0 +1,220 @@
#!/usr/bin/env python3
"""
Base Adaptor for Multi-LLM Support
Defines the abstract interface that all platform-specific adaptors must implement.
This enables Skill Seekers to generate skills for multiple LLM platforms (Claude, Gemini, ChatGPT).
"""
from abc import ABC, abstractmethod
from pathlib import Path
from typing import Dict, Any, Optional
from dataclasses import dataclass, field
@dataclass
class SkillMetadata:
"""Universal skill metadata used across all platforms"""
name: str
description: str
version: str = "1.0.0"
author: Optional[str] = None
tags: list[str] = field(default_factory=list)
class SkillAdaptor(ABC):
"""
Abstract base class for platform-specific skill adaptors.
Each platform (Claude, Gemini, OpenAI) implements this interface to handle:
- Platform-specific SKILL.md formatting
- Platform-specific package structure (ZIP, tar.gz, etc.)
- Platform-specific upload endpoints and authentication
- Optional AI enhancement capabilities
"""
# Platform identifiers (override in subclasses)
PLATFORM: str = "unknown" # e.g., "claude", "gemini", "openai"
PLATFORM_NAME: str = "Unknown" # e.g., "Claude AI (Anthropic)"
DEFAULT_API_ENDPOINT: Optional[str] = None
def __init__(self, config: Optional[Dict[str, Any]] = None):
"""
Initialize adaptor with optional configuration.
Args:
config: Platform-specific configuration options
"""
self.config = config or {}
@abstractmethod
def format_skill_md(self, skill_dir: Path, metadata: SkillMetadata) -> str:
"""
Format SKILL.md content with platform-specific frontmatter/structure.
Different platforms require different formats:
- Claude: YAML frontmatter + markdown
- Gemini: Plain markdown (no frontmatter)
- OpenAI: Assistant instructions format
Args:
skill_dir: Path to skill directory containing references/
metadata: Skill metadata (name, description, version, etc.)
Returns:
Formatted SKILL.md content as string
"""
pass
@abstractmethod
def package(self, skill_dir: Path, output_path: Path) -> Path:
"""
Package skill for platform (ZIP, tar.gz, etc.).
Different platforms require different package formats:
- Claude: .zip with SKILL.md, references/, scripts/, assets/
- Gemini: .tar.gz with system_instructions.md, references/
- OpenAI: .zip with assistant_instructions.txt, vector_store_files/
Args:
skill_dir: Path to skill directory to package
output_path: Path for output package (file or directory)
Returns:
Path to created package file
"""
pass
@abstractmethod
def upload(self, package_path: Path, api_key: str, **kwargs) -> Dict[str, Any]:
"""
Upload packaged skill to platform.
Returns a standardized response dictionary for all platforms.
Args:
package_path: Path to packaged skill file
api_key: Platform API key
**kwargs: Additional platform-specific arguments
Returns:
Dictionary with keys:
- success (bool): Whether upload succeeded
- skill_id (str|None): Platform-specific skill/assistant ID
- url (str|None): URL to view/manage skill
- message (str): Success or error message
"""
pass
def validate_api_key(self, api_key: str) -> bool:
"""
Validate API key format for this platform.
Default implementation just checks if key is non-empty.
Override for platform-specific validation.
Args:
api_key: API key to validate
Returns:
True if key format is valid
"""
return bool(api_key and api_key.strip())
def get_env_var_name(self) -> str:
"""
Get expected environment variable name for API key.
Returns:
Environment variable name (e.g., "ANTHROPIC_API_KEY", "GOOGLE_API_KEY")
"""
return f"{self.PLATFORM.upper()}_API_KEY"
def supports_enhancement(self) -> bool:
"""
Whether this platform supports AI-powered SKILL.md enhancement.
Returns:
True if platform can enhance skills
"""
return False
def enhance(self, skill_dir: Path, api_key: str) -> bool:
"""
Optionally enhance SKILL.md using platform's AI.
Only called if supports_enhancement() returns True.
Args:
skill_dir: Path to skill directory
api_key: Platform API key
Returns:
True if enhancement succeeded
"""
return False
def _read_existing_content(self, skill_dir: Path) -> str:
"""
Helper to read existing SKILL.md content (without frontmatter).
Args:
skill_dir: Path to skill directory
Returns:
SKILL.md content without YAML frontmatter
"""
skill_md_path = skill_dir / "SKILL.md"
if not skill_md_path.exists():
return ""
content = skill_md_path.read_text(encoding='utf-8')
# Strip YAML frontmatter if present
if content.startswith('---'):
parts = content.split('---', 2)
if len(parts) >= 3:
return parts[2].strip()
return content
def _extract_quick_reference(self, skill_dir: Path) -> str:
"""
Helper to extract quick reference section from references.
Args:
skill_dir: Path to skill directory
Returns:
Quick reference content as markdown string
"""
index_path = skill_dir / "references" / "index.md"
if not index_path.exists():
return "See references/ directory for documentation."
# Read index and extract relevant sections
content = index_path.read_text(encoding='utf-8')
return content[:500] + "..." if len(content) > 500 else content
def _generate_toc(self, skill_dir: Path) -> str:
"""
Helper to generate table of contents from references.
Args:
skill_dir: Path to skill directory
Returns:
Table of contents as markdown string
"""
refs_dir = skill_dir / "references"
if not refs_dir.exists():
return ""
toc_lines = []
for ref_file in sorted(refs_dir.glob("*.md")):
if ref_file.name == "index.md":
continue
title = ref_file.stem.replace('_', ' ').title()
toc_lines.append(f"- [{title}](references/{ref_file.name})")
return "\n".join(toc_lines)

501
src/skill_seekers/cli/adaptors/claude.py Normal file
View File

@@ -0,0 +1,501 @@
#!/usr/bin/env python3
"""
Claude AI Adaptor
Implements platform-specific handling for Claude AI (Anthropic) skills.
Refactored from upload_skill.py and enhance_skill.py.
"""
import os
import zipfile
from pathlib import Path
from typing import Dict, Any
from .base import SkillAdaptor, SkillMetadata
class ClaudeAdaptor(SkillAdaptor):
"""
Claude AI platform adaptor.
Handles:
- YAML frontmatter format for SKILL.md
- ZIP packaging with standard Claude skill structure
- Upload to Anthropic Skills API
- AI enhancement using Claude API
"""
PLATFORM = "claude"
PLATFORM_NAME = "Claude AI (Anthropic)"
DEFAULT_API_ENDPOINT = "https://api.anthropic.com/v1/skills"
def format_skill_md(self, skill_dir: Path, metadata: SkillMetadata) -> str:
"""
Format SKILL.md with Claude's YAML frontmatter.
Args:
skill_dir: Path to skill directory
metadata: Skill metadata
Returns:
Formatted SKILL.md content with YAML frontmatter
"""
# Read existing content (if any)
existing_content = self._read_existing_content(skill_dir)
# If existing content already has proper structure, use it
if existing_content and len(existing_content) > 100:
content_body = existing_content
else:
# Generate default content
content_body = f"""# {metadata.name.title()} Documentation Skill
{metadata.description}
## When to use this skill
Use this skill when the user asks about {metadata.name} documentation, including API references, tutorials, examples, and best practices.
## What's included
This skill contains comprehensive documentation organized into categorized reference files.
{self._generate_toc(skill_dir)}
## Quick Reference
{self._extract_quick_reference(skill_dir)}
## Navigation
See `references/index.md` for complete documentation structure.
"""
# Format with YAML frontmatter
return f"""---
name: {metadata.name}
description: {metadata.description}
version: {metadata.version}
---
{content_body}
"""
def package(self, skill_dir: Path, output_path: Path) -> Path:
"""
Package skill into ZIP file for Claude.
Creates standard Claude skill structure:
- SKILL.md
- references/*.md
- scripts/ (optional)
- assets/ (optional)
Args:
skill_dir: Path to skill directory
output_path: Output path/filename for ZIP
Returns:
Path to created ZIP file
"""
skill_dir = Path(skill_dir)
# Determine output filename
if output_path.is_dir() or str(output_path).endswith('/'):
output_path = Path(output_path) / f"{skill_dir.name}.zip"
elif not str(output_path).endswith('.zip'):
output_path = Path(str(output_path) + '.zip')
output_path = Path(output_path)
output_path.parent.mkdir(parents=True, exist_ok=True)
# Create ZIP file
with zipfile.ZipFile(output_path, 'w', zipfile.ZIP_DEFLATED) as zf:
# Add SKILL.md (required)
skill_md = skill_dir / "SKILL.md"
if skill_md.exists():
zf.write(skill_md, "SKILL.md")
# Add references directory (if exists)
refs_dir = skill_dir / "references"
if refs_dir.exists():
for ref_file in refs_dir.rglob("*"):
if ref_file.is_file() and not ref_file.name.startswith('.'):
arcname = ref_file.relative_to(skill_dir)
zf.write(ref_file, str(arcname))
# Add scripts directory (if exists)
scripts_dir = skill_dir / "scripts"
if scripts_dir.exists():
for script_file in scripts_dir.rglob("*"):
if script_file.is_file() and not script_file.name.startswith('.'):
arcname = script_file.relative_to(skill_dir)
zf.write(script_file, str(arcname))
# Add assets directory (if exists)
assets_dir = skill_dir / "assets"
if assets_dir.exists():
for asset_file in assets_dir.rglob("*"):
if asset_file.is_file() and not asset_file.name.startswith('.'):
arcname = asset_file.relative_to(skill_dir)
zf.write(asset_file, str(arcname))
return output_path
def upload(self, package_path: Path, api_key: str, **kwargs) -> Dict[str, Any]:
"""
Upload skill ZIP to Anthropic Skills API.
Args:
package_path: Path to skill ZIP file
api_key: Anthropic API key
**kwargs: Additional arguments (timeout, etc.)
Returns:
Dictionary with upload result
"""
# Check for requests library
try:
import requests
except ImportError:
return {
'success': False,
'skill_id': None,
'url': None,
'message': 'requests library not installed. Run: pip install requests'
}
# Validate ZIP file
package_path = Path(package_path)
if not package_path.exists():
return {
'success': False,
'skill_id': None,
'url': None,
'message': f'File not found: {package_path}'
}
if not package_path.suffix == '.zip':
return {
'success': False,
'skill_id': None,
'url': None,
'message': f'Not a ZIP file: {package_path}'
}
# Prepare API request
api_url = self.DEFAULT_API_ENDPOINT
headers = {
"x-api-key": api_key,
"anthropic-version": "2023-06-01",
"anthropic-beta": "skills-2025-10-02"
}
timeout = kwargs.get('timeout', 60)
try:
# Read ZIP file
with open(package_path, 'rb') as f:
zip_data = f.read()
# Upload skill
files = {
'files[]': (package_path.name, zip_data, 'application/zip')
}
response = requests.post(
api_url,
headers=headers,
files=files,
timeout=timeout
)
# Check response
if response.status_code == 200:
# Extract skill ID if available
try:
response_data = response.json()
skill_id = response_data.get('id')
except:
skill_id = None
return {
'success': True,
'skill_id': skill_id,
'url': 'https://claude.ai/skills',
'message': 'Skill uploaded successfully to Claude AI'
}
elif response.status_code == 401:
return {
'success': False,
'skill_id': None,
'url': None,
'message': 'Authentication failed. Check your ANTHROPIC_API_KEY'
}
elif response.status_code == 400:
try:
error_msg = response.json().get('error', {}).get('message', 'Unknown error')
except:
error_msg = 'Invalid skill format'
return {
'success': False,
'skill_id': None,
'url': None,
'message': f'Invalid skill format: {error_msg}'
}
else:
try:
error_msg = response.json().get('error', {}).get('message', 'Unknown error')
except:
error_msg = f'HTTP {response.status_code}'
return {
'success': False,
'skill_id': None,
'url': None,
'message': f'Upload failed: {error_msg}'
}
except requests.exceptions.Timeout:
return {
'success': False,
'skill_id': None,
'url': None,
'message': 'Upload timed out. Try again or use manual upload'
}
except requests.exceptions.ConnectionError:
return {
'success': False,
'skill_id': None,
'url': None,
'message': 'Connection error. Check your internet connection'
}
except Exception as e:
return {
'success': False,
'skill_id': None,
'url': None,
'message': f'Unexpected error: {str(e)}'
}
def validate_api_key(self, api_key: str) -> bool:
"""
Validate Anthropic API key format.
Args:
api_key: API key to validate
Returns:
True if key starts with 'sk-ant-'
"""
return api_key.strip().startswith('sk-ant-')
def get_env_var_name(self) -> str:
"""
Get environment variable name for Anthropic API key.
Returns:
'ANTHROPIC_API_KEY'
"""
return "ANTHROPIC_API_KEY"
def supports_enhancement(self) -> bool:
"""
Claude supports AI enhancement via Anthropic API.
Returns:
True
"""
return True
def enhance(self, skill_dir: Path, api_key: str) -> bool:
"""
Enhance SKILL.md using Claude API.
Reads reference files, sends them to Claude, and generates
an improved SKILL.md with real examples and better organization.
Args:
skill_dir: Path to skill directory
api_key: Anthropic API key
Returns:
True if enhancement succeeded
"""
# Check for anthropic library
try:
import anthropic
except ImportError:
print("❌ Error: anthropic package not installed")
print("Install with: pip install anthropic")
return False
skill_dir = Path(skill_dir)
references_dir = skill_dir / "references"
skill_md_path = skill_dir / "SKILL.md"
# Read reference files
print("📖 Reading reference documentation...")
references = self._read_reference_files(references_dir)
if not references:
print("❌ No reference files found to analyze")
return False
print(f" ✓ Read {len(references)} reference files")
total_size = sum(len(c) for c in references.values())
print(f" ✓ Total size: {total_size:,} characters\n")
# Read current SKILL.md
current_skill_md = None
if skill_md_path.exists():
current_skill_md = skill_md_path.read_text(encoding='utf-8')
print(f" ℹ Found existing SKILL.md ({len(current_skill_md)} chars)")
else:
print(f" ℹ No existing SKILL.md, will create new one")
# Build enhancement prompt
prompt = self._build_enhancement_prompt(
skill_dir.name,
references,
current_skill_md
)
print("\n🤖 Asking Claude to enhance SKILL.md...")
print(f" Input: {len(prompt):,} characters")
try:
client = anthropic.Anthropic(api_key=api_key)
message = client.messages.create(
model="claude-sonnet-4-20250514",
max_tokens=4096,
temperature=0.3,
messages=[{
"role": "user",
"content": prompt
}]
)
enhanced_content = message.content[0].text
print(f" ✓ Generated enhanced SKILL.md ({len(enhanced_content)} chars)\n")
# Backup original
if skill_md_path.exists():
backup_path = skill_md_path.with_suffix('.md.backup')
skill_md_path.rename(backup_path)
print(f" 💾 Backed up original to: {backup_path.name}")
# Save enhanced version
skill_md_path.write_text(enhanced_content, encoding='utf-8')
print(f" ✅ Saved enhanced SKILL.md")
return True
except Exception as e:
print(f"❌ Error calling Claude API: {e}")
return False
def _read_reference_files(self, references_dir: Path, max_chars: int = 200000) -> Dict[str, str]:
"""
Read reference markdown files from skill directory.
Args:
references_dir: Path to references directory
max_chars: Maximum total characters to read
Returns:
Dictionary mapping filename to content
"""
if not references_dir.exists():
return {}
references = {}
total_chars = 0
# Read all .md files
for ref_file in sorted(references_dir.glob("*.md")):
if total_chars >= max_chars:
break
try:
content = ref_file.read_text(encoding='utf-8')
# Limit individual file size
if len(content) > 30000:
content = content[:30000] + "\n\n...(truncated)"
references[ref_file.name] = content
total_chars += len(content)
except Exception as e:
print(f" ⚠️ Could not read {ref_file.name}: {e}")
return references
def _build_enhancement_prompt(
self,
skill_name: str,
references: Dict[str, str],
current_skill_md: str = None
) -> str:
"""
Build Claude API prompt for enhancement.
Args:
skill_name: Name of the skill
references: Dictionary of reference content
current_skill_md: Existing SKILL.md content (optional)
Returns:
Enhancement prompt for Claude
"""
prompt = f"""You are enhancing a Claude skill's SKILL.md file. This skill is about: {skill_name}
I've scraped documentation and organized it into reference files. Your job is to create an EXCELLENT SKILL.md that will help Claude use this documentation effectively.
CURRENT SKILL.MD:
{'```markdown' if current_skill_md else '(none - create from scratch)'}
{current_skill_md or 'No existing SKILL.md'}
{'```' if current_skill_md else ''}
REFERENCE DOCUMENTATION:
"""
for filename, content in references.items():
prompt += f"\n\n## {filename}\n```markdown\n{content[:30000]}\n```\n"
prompt += """
YOUR TASK:
Create an enhanced SKILL.md that includes:
1. **Clear "When to Use This Skill" section** - Be specific about trigger conditions
2. **Excellent Quick Reference section** - Extract 5-10 of the BEST, most practical code examples from the reference docs
- Choose SHORT, clear examples that demonstrate common tasks
- Include both simple and intermediate examples
- Annotate examples with clear descriptions
- Use proper language tags (cpp, python, javascript, json, etc.)
3. **Detailed Reference Files description** - Explain what's in each reference file
4. **Practical "Working with This Skill" section** - Give users clear guidance on how to navigate the skill
5. **Key Concepts section** (if applicable) - Explain core concepts
6. **Keep the frontmatter** (---\nname: ...\n---) intact
IMPORTANT:
- Extract REAL examples from the reference docs, don't make them up
- Prioritize SHORT, clear examples (5-20 lines max)
- Make it actionable and practical
- Don't be too verbose - be concise but useful
- Maintain the markdown structure for Claude skills
- Keep code examples properly formatted with language tags
OUTPUT:
Return ONLY the complete SKILL.md content, starting with the frontmatter (---).
"""
return prompt

460
src/skill_seekers/cli/adaptors/gemini.py Normal file
View File

@@ -0,0 +1,460 @@
#!/usr/bin/env python3
"""
Google Gemini Adaptor
Implements platform-specific handling for Google Gemini skills.
Uses Gemini Files API for grounding and Gemini 2.0 Flash for enhancement.
"""
import os
import tarfile
import json
from pathlib import Path
from typing import Dict, Any
from .base import SkillAdaptor, SkillMetadata
class GeminiAdaptor(SkillAdaptor):
"""
Google Gemini platform adaptor.
Handles:
- Plain markdown format (no YAML frontmatter)
- tar.gz packaging for Gemini Files API
- Upload to Google AI Studio / Files API
- AI enhancement using Gemini 2.0 Flash
"""
PLATFORM = "gemini"
PLATFORM_NAME = "Google Gemini"
DEFAULT_API_ENDPOINT = "https://generativelanguage.googleapis.com/v1beta/files"
def format_skill_md(self, skill_dir: Path, metadata: SkillMetadata) -> str:
"""
Format SKILL.md with plain markdown (no frontmatter).
Gemini doesn't use YAML frontmatter - just clean markdown.
Args:
skill_dir: Path to skill directory
metadata: Skill metadata
Returns:
Formatted SKILL.md content (plain markdown)
"""
# Read existing content (if any)
existing_content = self._read_existing_content(skill_dir)
# If existing content is substantial, use it
if existing_content and len(existing_content) > 100:
content_body = existing_content
else:
# Generate default content
content_body = f"""# {metadata.name.title()} Documentation
**Description:** {metadata.description}
## Quick Reference
{self._extract_quick_reference(skill_dir)}
## Table of Contents
{self._generate_toc(skill_dir)}
## Documentation Structure
This skill contains comprehensive documentation organized into categorized reference files.
### Available References
{self._generate_toc(skill_dir)}
## How to Use This Skill
When asking questions about {metadata.name}:
1. Mention specific topics or features you need help with
2. Reference documentation sections will be automatically consulted
3. You'll receive detailed answers with code examples
## Navigation
See the references directory for complete documentation with examples and best practices.
"""
# Return plain markdown (NO frontmatter)
return content_body
def package(self, skill_dir: Path, output_path: Path) -> Path:
"""
Package skill into tar.gz file for Gemini.
Creates Gemini-compatible structure:
- system_instructions.md (main SKILL.md)
- references/*.md
- gemini_metadata.json (skill metadata)
Args:
skill_dir: Path to skill directory
output_path: Output path/filename for tar.gz
Returns:
Path to created tar.gz file
"""
skill_dir = Path(skill_dir)
# Determine output filename
if output_path.is_dir() or str(output_path).endswith('/'):
output_path = Path(output_path) / f"{skill_dir.name}-gemini.tar.gz"
elif not str(output_path).endswith('.tar.gz'):
# Replace .zip with .tar.gz if needed
output_str = str(output_path).replace('.zip', '.tar.gz')
if not output_str.endswith('.tar.gz'):
output_str += '.tar.gz'
output_path = Path(output_str)
output_path = Path(output_path)
output_path.parent.mkdir(parents=True, exist_ok=True)
# Create tar.gz file
with tarfile.open(output_path, 'w:gz') as tar:
# Add SKILL.md as system_instructions.md
skill_md = skill_dir / "SKILL.md"
if skill_md.exists():
tar.add(skill_md, arcname="system_instructions.md")
# Add references directory (if exists)
refs_dir = skill_dir / "references"
if refs_dir.exists():
for ref_file in refs_dir.rglob("*"):
if ref_file.is_file() and not ref_file.name.startswith('.'):
arcname = ref_file.relative_to(skill_dir)
tar.add(ref_file, arcname=str(arcname))
# Create and add metadata file
metadata = {
'platform': 'gemini',
'name': skill_dir.name,
'version': '1.0.0',
'created_with': 'skill-seekers'
}
# Write metadata to temp file and add to archive
import tempfile
with tempfile.NamedTemporaryFile(mode='w', suffix='.json', delete=False) as tmp:
json.dump(metadata, tmp, indent=2)
tmp_path = tmp.name
try:
tar.add(tmp_path, arcname="gemini_metadata.json")
finally:
os.unlink(tmp_path)
return output_path
def upload(self, package_path: Path, api_key: str, **kwargs) -> Dict[str, Any]:
"""
Upload skill tar.gz to Gemini Files API.
Args:
package_path: Path to skill tar.gz file
api_key: Google API key
**kwargs: Additional arguments
Returns:
Dictionary with upload result
"""
# Validate package file FIRST
package_path = Path(package_path)
if not package_path.exists():
return {
'success': False,
'skill_id': None,
'url': None,
'message': f'File not found: {package_path}'
}
if not package_path.suffix == '.gz':
return {
'success': False,
'skill_id': None,
'url': None,
'message': f'Not a tar.gz file: {package_path}'
}
# Check for google-generativeai library
try:
import google.generativeai as genai
except ImportError:
return {
'success': False,
'skill_id': None,
'url': None,
'message': 'google-generativeai library not installed. Run: pip install google-generativeai'
}
# Configure Gemini
try:
genai.configure(api_key=api_key)
# Extract tar.gz to temp directory
import tempfile
import shutil
with tempfile.TemporaryDirectory() as temp_dir:
# Extract archive
with tarfile.open(package_path, 'r:gz') as tar:
tar.extractall(temp_dir)
temp_path = Path(temp_dir)
# Upload main file (system_instructions.md)
main_file = temp_path / "system_instructions.md"
if not main_file.exists():
return {
'success': False,
'skill_id': None,
'url': None,
'message': 'Invalid package: system_instructions.md not found'
}
# Upload to Files API
uploaded_file = genai.upload_file(
path=str(main_file),
display_name=f"{package_path.stem}_instructions"
)
# Upload reference files (if any)
refs_dir = temp_path / "references"
uploaded_refs = []
if refs_dir.exists():
for ref_file in refs_dir.glob("*.md"):
ref_uploaded = genai.upload_file(
path=str(ref_file),
display_name=f"{package_path.stem}_{ref_file.stem}"
)
uploaded_refs.append(ref_uploaded.name)
return {
'success': True,
'skill_id': uploaded_file.name,
'url': f"https://aistudio.google.com/app/files/{uploaded_file.name}",
'message': f'Skill uploaded to Google AI Studio ({len(uploaded_refs) + 1} files)'
}
except Exception as e:
return {
'success': False,
'skill_id': None,
'url': None,
'message': f'Upload failed: {str(e)}'
}
def validate_api_key(self, api_key: str) -> bool:
"""
Validate Google API key format.
Args:
api_key: API key to validate
Returns:
True if key starts with 'AIza'
"""
return api_key.strip().startswith('AIza')
def get_env_var_name(self) -> str:
"""
Get environment variable name for Google API key.
Returns:
'GOOGLE_API_KEY'
"""
return "GOOGLE_API_KEY"
def supports_enhancement(self) -> bool:
"""
Gemini supports AI enhancement via Gemini 2.0 Flash.
Returns:
True
"""
return True
def enhance(self, skill_dir: Path, api_key: str) -> bool:
"""
Enhance SKILL.md using Gemini 2.0 Flash API.
Args:
skill_dir: Path to skill directory
api_key: Google API key
Returns:
True if enhancement succeeded
"""
# Check for google-generativeai library
try:
import google.generativeai as genai
except ImportError:
print("❌ Error: google-generativeai package not installed")
print("Install with: pip install google-generativeai")
return False
skill_dir = Path(skill_dir)
references_dir = skill_dir / "references"
skill_md_path = skill_dir / "SKILL.md"
# Read reference files
print("📖 Reading reference documentation...")
references = self._read_reference_files(references_dir)
if not references:
print("❌ No reference files found to analyze")
return False
print(f" ✓ Read {len(references)} reference files")
total_size = sum(len(c) for c in references.values())
print(f" ✓ Total size: {total_size:,} characters\n")
# Read current SKILL.md
current_skill_md = None
if skill_md_path.exists():
current_skill_md = skill_md_path.read_text(encoding='utf-8')
print(f" ℹ Found existing SKILL.md ({len(current_skill_md)} chars)")
else:
print(f" ℹ No existing SKILL.md, will create new one")
# Build enhancement prompt
prompt = self._build_enhancement_prompt(
skill_dir.name,
references,
current_skill_md
)
print("\n🤖 Asking Gemini to enhance SKILL.md...")
print(f" Input: {len(prompt):,} characters")
try:
genai.configure(api_key=api_key)
model = genai.GenerativeModel('gemini-2.0-flash-exp')
response = model.generate_content(prompt)
enhanced_content = response.text
print(f" ✓ Generated enhanced SKILL.md ({len(enhanced_content)} chars)\n")
# Backup original
if skill_md_path.exists():
backup_path = skill_md_path.with_suffix('.md.backup')
skill_md_path.rename(backup_path)
print(f" 💾 Backed up original to: {backup_path.name}")
# Save enhanced version
skill_md_path.write_text(enhanced_content, encoding='utf-8')
print(f" ✅ Saved enhanced SKILL.md")
return True
except Exception as e:
print(f"❌ Error calling Gemini API: {e}")
return False
def _read_reference_files(self, references_dir: Path, max_chars: int = 200000) -> Dict[str, str]:
"""
Read reference markdown files from skill directory.
Args:
references_dir: Path to references directory
max_chars: Maximum total characters to read
Returns:
Dictionary mapping filename to content
"""
if not references_dir.exists():
return {}
references = {}
total_chars = 0
# Read all .md files
for ref_file in sorted(references_dir.glob("*.md")):
if total_chars >= max_chars:
break
try:
content = ref_file.read_text(encoding='utf-8')
# Limit individual file size
if len(content) > 30000:
content = content[:30000] + "\n\n...(truncated)"
references[ref_file.name] = content
total_chars += len(content)
except Exception as e:
print(f" ⚠️ Could not read {ref_file.name}: {e}")
return references
def _build_enhancement_prompt(
self,
skill_name: str,
references: Dict[str, str],
current_skill_md: str = None
) -> str:
"""
Build Gemini API prompt for enhancement.
Args:
skill_name: Name of the skill
references: Dictionary of reference content
current_skill_md: Existing SKILL.md content (optional)
Returns:
Enhancement prompt for Gemini
"""
prompt = f"""You are enhancing a skill's documentation file for use with Google Gemini. This skill is about: {skill_name}
I've scraped documentation and organized it into reference files. Your job is to create an EXCELLENT markdown documentation file that will help Gemini use this documentation effectively.
CURRENT DOCUMENTATION:
{'```markdown' if current_skill_md else '(none - create from scratch)'}
{current_skill_md or 'No existing documentation'}
{'```' if current_skill_md else ''}
REFERENCE DOCUMENTATION:
"""
for filename, content in references.items():
prompt += f"\n\n## {filename}\n```markdown\n{content[:30000]}\n```\n"
prompt += """
YOUR TASK:
Create enhanced documentation that includes:
1. **Clear description** - What this skill covers and when to use it
2. **Excellent Quick Reference section** - Extract 5-10 of the BEST, most practical code examples from the reference docs
- Choose SHORT, clear examples that demonstrate common tasks
- Include both simple and intermediate examples
- Annotate examples with clear descriptions
- Use proper language tags (cpp, python, javascript, json, etc.)
3. **Table of Contents** - List all reference sections
4. **Practical usage guidance** - Help users navigate the documentation
5. **Key Concepts section** (if applicable) - Explain core concepts
6. **DO NOT use YAML frontmatter** - This is for Gemini, which uses plain markdown
IMPORTANT:
- Extract REAL examples from the reference docs, don't make them up
- Prioritize SHORT, clear examples (5-20 lines max)
- Make it actionable and practical
- Don't be too verbose - be concise but useful
- Use clean markdown formatting
- Keep code examples properly formatted with language tags
- NO YAML frontmatter (no --- blocks)
OUTPUT:
Return ONLY the complete markdown content, starting with the main title (#).
"""
return prompt

268
src/skill_seekers/cli/adaptors/markdown.py Normal file
View File

@@ -0,0 +1,268 @@
#!/usr/bin/env python3
"""
Generic Markdown Adaptor
Implements generic markdown export for universal LLM compatibility.
No platform-specific features, just clean markdown documentation.
"""
import zipfile
from pathlib import Path
from typing import Dict, Any
from .base import SkillAdaptor, SkillMetadata
class MarkdownAdaptor(SkillAdaptor):
"""
Generic Markdown platform adaptor.
Handles:
- Pure markdown format (no platform-specific formatting)
- ZIP packaging with combined or individual files
- No upload capability (manual use)
- No AI enhancement (generic export only)
"""
PLATFORM = "markdown"
PLATFORM_NAME = "Generic Markdown (Universal)"
DEFAULT_API_ENDPOINT = None # No upload endpoint
def format_skill_md(self, skill_dir: Path, metadata: SkillMetadata) -> str:
"""
Format SKILL.md as pure markdown.
Clean, universal markdown that works with any LLM or documentation system.
Args:
skill_dir: Path to skill directory
metadata: Skill metadata
Returns:
Formatted markdown content
"""
# Read existing content (if any)
existing_content = self._read_existing_content(skill_dir)
# If existing content is substantial, use it
if existing_content and len(existing_content) > 100:
content_body = existing_content
else:
# Generate clean markdown
content_body = f"""# {metadata.name.title()} Documentation
{metadata.description}
## Table of Contents
{self._generate_toc(skill_dir)}
## Quick Reference
{self._extract_quick_reference(skill_dir)}
## Documentation
This documentation package contains comprehensive reference materials organized into categorized sections.
### Available Sections
{self._generate_toc(skill_dir)}
## Usage
Browse the reference files for detailed information on each topic. All files are in standard markdown format and can be viewed with any markdown reader or text editor.
---
*Documentation generated by Skill Seekers*
"""
# Return pure markdown (no frontmatter, no special formatting)
return content_body
def package(self, skill_dir: Path, output_path: Path) -> Path:
"""
Package skill into ZIP file with markdown documentation.
Creates universal structure:
- README.md (combined documentation)
- references/*.md (individual reference files)
- metadata.json (skill information)
Args:
skill_dir: Path to skill directory
output_path: Output path/filename for ZIP
Returns:
Path to created ZIP file
"""
skill_dir = Path(skill_dir)
# Determine output filename
if output_path.is_dir() or str(output_path).endswith('/'):
output_path = Path(output_path) / f"{skill_dir.name}-markdown.zip"
elif not str(output_path).endswith('.zip'):
# Replace extension if needed
output_str = str(output_path).replace('.tar.gz', '.zip')
if not output_str.endswith('-markdown.zip'):
output_str = output_str.replace('.zip', '-markdown.zip')
if not output_str.endswith('.zip'):
output_str += '.zip'
output_path = Path(output_str)
output_path = Path(output_path)
output_path.parent.mkdir(parents=True, exist_ok=True)
# Create ZIP file
with zipfile.ZipFile(output_path, 'w', zipfile.ZIP_DEFLATED) as zf:
# Add SKILL.md as README.md
skill_md = skill_dir / "SKILL.md"
if skill_md.exists():
content = skill_md.read_text(encoding='utf-8')
zf.writestr("README.md", content)
# Add individual reference files
refs_dir = skill_dir / "references"
if refs_dir.exists():
for ref_file in refs_dir.rglob("*.md"):
if ref_file.is_file() and not ref_file.name.startswith('.'):
# Preserve directory structure under references/
arcname = ref_file.relative_to(skill_dir)
zf.write(ref_file, str(arcname))
# Create combined documentation file
combined = self._create_combined_doc(skill_dir)
if combined:
zf.writestr("DOCUMENTATION.md", combined)
# Add metadata file
import json
metadata = {
'platform': 'markdown',
'name': skill_dir.name,
'version': '1.0.0',
'created_with': 'skill-seekers',
'format': 'universal_markdown',
'usage': 'Use with any LLM or documentation system'
}
zf.writestr("metadata.json", json.dumps(metadata, indent=2))
return output_path
def upload(self, package_path: Path, api_key: str, **kwargs) -> Dict[str, Any]:
"""
Generic markdown export does not support upload.
Users should manually use the exported markdown files.
Args:
package_path: Path to package file
api_key: Not used
**kwargs: Not used
Returns:
Result indicating no upload capability
"""
return {
'success': False,
'skill_id': None,
'url': str(package_path.absolute()),
'message': (
'Generic markdown export does not support automatic upload. '
f'Your documentation is packaged at: {package_path.absolute()}'
)
}
def validate_api_key(self, api_key: str) -> bool:
"""
Markdown export doesn't use API keys.
Args:
api_key: Not used
Returns:
Always False (no API needed)
"""
return False
def get_env_var_name(self) -> str:
"""
No API key needed for markdown export.
Returns:
Empty string
"""
return ""
def supports_enhancement(self) -> bool:
"""
Markdown export doesn't support AI enhancement.
Returns:
False
"""
return False
def enhance(self, skill_dir: Path, api_key: str) -> bool:
"""
Markdown export doesn't support enhancement.
Args:
skill_dir: Not used
api_key: Not used
Returns:
False
"""
print("❌ Generic markdown export does not support AI enhancement")
print(" Use --target claude, --target gemini, or --target openai for enhancement")
return False
def _create_combined_doc(self, skill_dir: Path) -> str:
"""
Create a combined documentation file from all references.
Args:
skill_dir: Path to skill directory
Returns:
Combined markdown content
"""
skill_md = skill_dir / "SKILL.md"
refs_dir = skill_dir / "references"
combined_parts = []
# Add main content
if skill_md.exists():
content = skill_md.read_text(encoding='utf-8')
# Strip YAML frontmatter if present
if content.startswith('---'):
parts = content.split('---', 2)
if len(parts) >= 3:
content = parts[2].strip()
combined_parts.append(content)
# Add separator
combined_parts.append("\n\n---\n\n")
# Add all reference files
if refs_dir.exists():
# Sort for consistent ordering
ref_files = sorted(refs_dir.glob("*.md"))
for ref_file in ref_files:
if ref_file.name == "index.md":
continue # Skip index
try:
ref_content = ref_file.read_text(encoding='utf-8')
combined_parts.append(f"# {ref_file.stem.replace('_', ' ').title()}\n\n")
combined_parts.append(ref_content)
combined_parts.append("\n\n---\n\n")
except Exception:
pass # Skip files that can't be read
return "".join(combined_parts).strip()

524
src/skill_seekers/cli/adaptors/openai.py Normal file
View File

@@ -0,0 +1,524 @@
#!/usr/bin/env python3
"""
OpenAI ChatGPT Adaptor
Implements platform-specific handling for OpenAI ChatGPT Assistants.
Uses Assistants API with Vector Store for file search.
"""
import os
import zipfile
import json
from pathlib import Path
from typing import Dict, Any
from .base import SkillAdaptor, SkillMetadata
class OpenAIAdaptor(SkillAdaptor):
"""
OpenAI ChatGPT platform adaptor.
Handles:
- Assistant instructions format (not YAML frontmatter)
- ZIP packaging for Assistants API
- Upload creates Assistant + Vector Store
- AI enhancement using GPT-4o
"""
PLATFORM = "openai"
PLATFORM_NAME = "OpenAI ChatGPT"
DEFAULT_API_ENDPOINT = "https://api.openai.com/v1/assistants"
def format_skill_md(self, skill_dir: Path, metadata: SkillMetadata) -> str:
"""
Format SKILL.md as Assistant instructions.
OpenAI Assistants use instructions rather than markdown docs.
Args:
skill_dir: Path to skill directory
metadata: Skill metadata
Returns:
Formatted instructions for OpenAI Assistant
"""
# Read existing content (if any)
existing_content = self._read_existing_content(skill_dir)
# If existing content is substantial, adapt it to instructions format
if existing_content and len(existing_content) > 100:
content_body = f"""You are an expert assistant for {metadata.name}.
{metadata.description}
Use the attached knowledge files to provide accurate, detailed answers about {metadata.name}.
{existing_content}
## How to Assist Users
When users ask questions:
1. Search the knowledge files for relevant information
2. Provide clear, practical answers with code examples
3. Reference specific documentation sections when helpful
4. Be concise but thorough
Always prioritize accuracy by consulting the knowledge base before responding."""
else:
# Generate default instructions
content_body = f"""You are an expert assistant for {metadata.name}.
{metadata.description}
## Your Knowledge Base
You have access to comprehensive documentation files about {metadata.name}. Use these files to provide accurate answers to user questions.
{self._generate_toc(skill_dir)}
## Quick Reference
{self._extract_quick_reference(skill_dir)}
## How to Assist Users
When users ask questions about {metadata.name}:
1. **Search the knowledge files** - Use file_search to find relevant information
2. **Provide code examples** - Include practical, working code snippets
3. **Reference documentation** - Cite specific sections when helpful
4. **Be practical** - Focus on real-world usage and best practices
5. **Stay accurate** - Always verify information against the knowledge base
## Response Guidelines
- Keep answers clear and concise
- Use proper code formatting with language tags
- Provide both simple and detailed explanations as needed
- Suggest related topics when relevant
- Admit when information isn't in the knowledge base
Always prioritize accuracy by consulting the attached documentation files before responding."""
# Return plain text instructions (NO frontmatter)
return content_body
def package(self, skill_dir: Path, output_path: Path) -> Path:
"""
Package skill into ZIP file for OpenAI Assistants.
Creates OpenAI-compatible structure:
- assistant_instructions.txt (main instructions)
- vector_store_files/*.md (reference files for vector store)
- openai_metadata.json (skill metadata)
Args:
skill_dir: Path to skill directory
output_path: Output path/filename for ZIP
Returns:
Path to created ZIP file
"""
skill_dir = Path(skill_dir)
# Determine output filename
if output_path.is_dir() or str(output_path).endswith('/'):
output_path = Path(output_path) / f"{skill_dir.name}-openai.zip"
elif not str(output_path).endswith('.zip'):
# Keep .zip extension
if not str(output_path).endswith('-openai.zip'):
output_str = str(output_path).replace('.zip', '-openai.zip')
if not output_str.endswith('.zip'):
output_str += '.zip'
output_path = Path(output_str)
output_path = Path(output_path)
output_path.parent.mkdir(parents=True, exist_ok=True)
# Create ZIP file
with zipfile.ZipFile(output_path, 'w', zipfile.ZIP_DEFLATED) as zf:
# Add SKILL.md as assistant_instructions.txt
skill_md = skill_dir / "SKILL.md"
if skill_md.exists():
instructions = skill_md.read_text(encoding='utf-8')
zf.writestr("assistant_instructions.txt", instructions)
# Add references directory as vector_store_files/
refs_dir = skill_dir / "references"
if refs_dir.exists():
for ref_file in refs_dir.rglob("*.md"):
if ref_file.is_file() and not ref_file.name.startswith('.'):
# Place all reference files in vector_store_files/
arcname = f"vector_store_files/{ref_file.name}"
zf.write(ref_file, arcname)
# Create and add metadata file
metadata = {
'platform': 'openai',
'name': skill_dir.name,
'version': '1.0.0',
'created_with': 'skill-seekers',
'model': 'gpt-4o',
'tools': ['file_search']
}
zf.writestr("openai_metadata.json", json.dumps(metadata, indent=2))
return output_path
def upload(self, package_path: Path, api_key: str, **kwargs) -> Dict[str, Any]:
"""
Upload skill ZIP to OpenAI Assistants API.
Creates:
1. Vector Store with reference files
2. Assistant with file_search tool
Args:
package_path: Path to skill ZIP file
api_key: OpenAI API key
**kwargs: Additional arguments (model, etc.)
Returns:
Dictionary with upload result
"""
# Validate package file FIRST
package_path = Path(package_path)
if not package_path.exists():
return {
'success': False,
'skill_id': None,
'url': None,
'message': f'File not found: {package_path}'
}
if not package_path.suffix == '.zip':
return {
'success': False,
'skill_id': None,
'url': None,
'message': f'Not a ZIP file: {package_path}'
}
# Check for openai library
try:
from openai import OpenAI
except ImportError:
return {
'success': False,
'skill_id': None,
'url': None,
'message': 'openai library not installed. Run: pip install openai'
}
# Configure OpenAI client
try:
client = OpenAI(api_key=api_key)
# Extract package to temp directory
import tempfile
import shutil
with tempfile.TemporaryDirectory() as temp_dir:
# Extract ZIP
with zipfile.ZipFile(package_path, 'r') as zf:
zf.extractall(temp_dir)
temp_path = Path(temp_dir)
# Read instructions
instructions_file = temp_path / "assistant_instructions.txt"
if not instructions_file.exists():
return {
'success': False,
'skill_id': None,
'url': None,
'message': 'Invalid package: assistant_instructions.txt not found'
}
instructions = instructions_file.read_text(encoding='utf-8')
# Read metadata
metadata_file = temp_path / "openai_metadata.json"
skill_name = package_path.stem
model = kwargs.get('model', 'gpt-4o')
if metadata_file.exists():
with open(metadata_file, 'r') as f:
metadata = json.load(f)
skill_name = metadata.get('name', skill_name)
model = metadata.get('model', model)
# Create vector store
vector_store = client.beta.vector_stores.create(
name=f"{skill_name} Documentation"
)
# Upload reference files to vector store
vector_files_dir = temp_path / "vector_store_files"
file_ids = []
if vector_files_dir.exists():
for ref_file in vector_files_dir.glob("*.md"):
# Upload file
with open(ref_file, 'rb') as f:
uploaded_file = client.files.create(
file=f,
purpose='assistants'
)
file_ids.append(uploaded_file.id)
# Attach files to vector store
if file_ids:
client.beta.vector_stores.files.create_batch(
vector_store_id=vector_store.id,
file_ids=file_ids
)
# Create assistant
assistant = client.beta.assistants.create(
name=skill_name,
instructions=instructions,
model=model,
tools=[{"type": "file_search"}],
tool_resources={
"file_search": {
"vector_store_ids": [vector_store.id]
}
}
)
return {
'success': True,
'skill_id': assistant.id,
'url': f"https://platform.openai.com/assistants/{assistant.id}",
'message': f'Assistant created with {len(file_ids)} knowledge files'
}
except Exception as e:
return {
'success': False,
'skill_id': None,
'url': None,
'message': f'Upload failed: {str(e)}'
}
def validate_api_key(self, api_key: str) -> bool:
"""
Validate OpenAI API key format.
Args:
api_key: API key to validate
Returns:
True if key starts with 'sk-'
"""
return api_key.strip().startswith('sk-')
def get_env_var_name(self) -> str:
"""
Get environment variable name for OpenAI API key.
Returns:
'OPENAI_API_KEY'
"""
return "OPENAI_API_KEY"
def supports_enhancement(self) -> bool:
"""
OpenAI supports AI enhancement via GPT-4o.
Returns:
True
"""
return True
def enhance(self, skill_dir: Path, api_key: str) -> bool:
"""
Enhance SKILL.md using GPT-4o API.
Args:
skill_dir: Path to skill directory
api_key: OpenAI API key
Returns:
True if enhancement succeeded
"""
# Check for openai library
try:
from openai import OpenAI
except ImportError:
print("❌ Error: openai package not installed")
print("Install with: pip install openai")
return False
skill_dir = Path(skill_dir)
references_dir = skill_dir / "references"
skill_md_path = skill_dir / "SKILL.md"
# Read reference files
print("📖 Reading reference documentation...")
references = self._read_reference_files(references_dir)
if not references:
print("❌ No reference files found to analyze")
return False
print(f" ✓ Read {len(references)} reference files")
total_size = sum(len(c) for c in references.values())
print(f" ✓ Total size: {total_size:,} characters\n")
# Read current SKILL.md
current_skill_md = None
if skill_md_path.exists():
current_skill_md = skill_md_path.read_text(encoding='utf-8')
print(f" ℹ Found existing SKILL.md ({len(current_skill_md)} chars)")
else:
print(f" ℹ No existing SKILL.md, will create new one")
# Build enhancement prompt
prompt = self._build_enhancement_prompt(
skill_dir.name,
references,
current_skill_md
)
print("\n🤖 Asking GPT-4o to enhance SKILL.md...")
print(f" Input: {len(prompt):,} characters")
try:
client = OpenAI(api_key=api_key)
response = client.chat.completions.create(
model="gpt-4o",
messages=[
{
"role": "system",
"content": "You are an expert technical writer creating Assistant instructions for OpenAI ChatGPT."
},
{
"role": "user",
"content": prompt
}
],
temperature=0.3,
max_tokens=4096
)
enhanced_content = response.choices[0].message.content
print(f" ✓ Generated enhanced SKILL.md ({len(enhanced_content)} chars)\n")
# Backup original
if skill_md_path.exists():
backup_path = skill_md_path.with_suffix('.md.backup')
skill_md_path.rename(backup_path)
print(f" 💾 Backed up original to: {backup_path.name}")
# Save enhanced version
skill_md_path.write_text(enhanced_content, encoding='utf-8')
print(f" ✅ Saved enhanced SKILL.md")
return True
except Exception as e:
print(f"❌ Error calling OpenAI API: {e}")
return False
def _read_reference_files(self, references_dir: Path, max_chars: int = 200000) -> Dict[str, str]:
"""
Read reference markdown files from skill directory.
Args:
references_dir: Path to references directory
max_chars: Maximum total characters to read
Returns:
Dictionary mapping filename to content
"""
if not references_dir.exists():
return {}
references = {}
total_chars = 0
# Read all .md files
for ref_file in sorted(references_dir.glob("*.md")):
if total_chars >= max_chars:
break
try:
content = ref_file.read_text(encoding='utf-8')
# Limit individual file size
if len(content) > 30000:
content = content[:30000] + "\n\n...(truncated)"
references[ref_file.name] = content
total_chars += len(content)
except Exception as e:
print(f" ⚠️ Could not read {ref_file.name}: {e}")
return references
def _build_enhancement_prompt(
self,
skill_name: str,
references: Dict[str, str],
current_skill_md: str = None
) -> str:
"""
Build OpenAI API prompt for enhancement.
Args:
skill_name: Name of the skill
references: Dictionary of reference content
current_skill_md: Existing SKILL.md content (optional)
Returns:
Enhancement prompt for GPT-4o
"""
prompt = f"""You are creating Assistant instructions for an OpenAI ChatGPT Assistant about: {skill_name}
I've scraped documentation and organized it into reference files. Your job is to create EXCELLENT Assistant instructions that will help the Assistant use this documentation effectively.
CURRENT INSTRUCTIONS:
{'```' if current_skill_md else '(none - create from scratch)'}
{current_skill_md or 'No existing instructions'}
{'```' if current_skill_md else ''}
REFERENCE DOCUMENTATION:
"""
for filename, content in references.items():
prompt += f"\n\n## {filename}\n```markdown\n{content[:30000]}\n```\n"
prompt += """
YOUR TASK:
Create enhanced Assistant instructions that include:
1. **Clear role definition** - "You are an expert assistant for [topic]"
2. **Knowledge base description** - What documentation is attached
3. **Excellent Quick Reference** - Extract 5-10 of the BEST, most practical code examples from the reference docs
- Choose SHORT, clear examples that demonstrate common tasks
- Include both simple and intermediate examples
- Annotate examples with clear descriptions
- Use proper language tags (cpp, python, javascript, json, etc.)
4. **Response guidelines** - How the Assistant should help users
5. **Search strategy** - When to use file_search, how to find information
6. **DO NOT use YAML frontmatter** - This is plain text instructions for OpenAI
IMPORTANT:
- Extract REAL examples from the reference docs, don't make them up
- Prioritize SHORT, clear examples (5-20 lines max)
- Make it actionable and practical for the Assistant
- Write clear, direct instructions
- Focus on how the Assistant should behave and respond
- NO YAML frontmatter (no --- blocks)
OUTPUT:
Return ONLY the complete Assistant instructions as plain text.
"""
return prompt

89
src/skill_seekers/cli/enhance_skill.py
View File

@@ -1,12 +1,18 @@
#!/usr/bin/env python3
"""
SKILL.md Enhancement Script
Uses Claude API to improve SKILL.md by analyzing reference documentation.
Uses platform AI APIs to improve SKILL.md by analyzing reference documentation.
Usage:
skill-seekers enhance output/steam-inventory/
# Claude (default)
skill-seekers enhance output/react/
skill-seekers enhance output/godot/ --api-key YOUR_API_KEY
skill-seekers enhance output/react/ --api-key sk-ant-...
# Gemini
skill-seekers enhance output/react/ --target gemini --api-key AIzaSy...
# OpenAI
skill-seekers enhance output/react/ --target openai --api-key sk-proj-...
"""
import os
@@ -195,18 +201,26 @@ Return ONLY the complete SKILL.md content, starting with the frontmatter (---).
def main():
parser = argparse.ArgumentParser(
description='Enhance SKILL.md using Claude API',
description='Enhance SKILL.md using platform AI APIs',
formatter_class=argparse.RawDescriptionHelpFormatter,
epilog="""
Examples:
# Using ANTHROPIC_API_KEY environment variable
# Claude (default)
export ANTHROPIC_API_KEY=sk-ant-...
skill-seekers enhance output/steam-inventory/
skill-seekers enhance output/react/
# Providing API key directly
# Gemini
export GOOGLE_API_KEY=AIzaSy...
skill-seekers enhance output/react/ --target gemini
# OpenAI
export OPENAI_API_KEY=sk-proj-...
skill-seekers enhance output/react/ --target openai
# With explicit API key
skill-seekers enhance output/react/ --api-key sk-ant-...
# Show what would be done (dry run)
# Dry run
skill-seekers enhance output/godot/ --dry-run
"""
)
@@ -214,7 +228,11 @@ Examples:
parser.add_argument('skill_dir', type=str,
help='Path to skill directory (e.g., output/steam-inventory/)')
parser.add_argument('--api-key', type=str,
help='Anthropic API key (or set ANTHROPIC_API_KEY env var)')
help='Platform API key (or set environment variable)')
parser.add_argument('--target',
choices=['claude', 'gemini', 'openai'],
default='claude',
help='Target LLM platform (default: claude)')
parser.add_argument('--dry-run', action='store_true',
help='Show what would be done without calling API')
@@ -249,18 +267,57 @@ Examples:
print(f" skill-seekers enhance {skill_dir}")
return
# Create enhancer and run
# Check if platform supports enhancement
try:
enhancer = SkillEnhancer(skill_dir, api_key=args.api_key)
success = enhancer.run()
from skill_seekers.cli.adaptors import get_adaptor
adaptor = get_adaptor(args.target)
if not adaptor.supports_enhancement():
print(f"❌ Error: {adaptor.PLATFORM_NAME} does not support AI enhancement")
print(f"\nSupported platforms for enhancement:")
print(" - Claude AI (Anthropic)")
print(" - Google Gemini")
print(" - OpenAI ChatGPT")
sys.exit(1)
# Get API key
api_key = args.api_key
if not api_key:
api_key = os.environ.get(adaptor.get_env_var_name(), '').strip()
if not api_key:
print(f"❌ Error: {adaptor.get_env_var_name()} not set")
print(f"\nSet your API key for {adaptor.PLATFORM_NAME}:")
print(f" export {adaptor.get_env_var_name()}=...")
print("Or provide it directly:")
print(f" skill-seekers enhance {skill_dir} --target {args.target} --api-key ...")
sys.exit(1)
# Run enhancement using adaptor
print(f"\n{'='*60}")
print(f"ENHANCING SKILL: {skill_dir}")
print(f"Platform: {adaptor.PLATFORM_NAME}")
print(f"{'='*60}\n")
success = adaptor.enhance(Path(skill_dir), api_key)
if success:
print(f"\n✅ Enhancement complete!")
print(f"\nNext steps:")
print(f" 1. Review: {Path(skill_dir) / 'SKILL.md'}")
print(f" 2. If you don't like it, restore backup: {Path(skill_dir) / 'SKILL.md.backup'}")
print(f" 3. Package your skill:")
print(f" skill-seekers package {skill_dir}/ --target {args.target}")
sys.exit(0 if success else 1)
except ImportError as e:
print(f"❌ Error: {e}")
print("\nAdaptor system not available. Reinstall skill-seekers.")
sys.exit(1)
except ValueError as e:
print(f"❌ Error: {e}")
print("\nSet your API key:")
print(" export ANTHROPIC_API_KEY=sk-ant-...")
print("Or provide it directly:")
print(f" skill-seekers enhance {skill_dir} --api-key sk-ant-...")
sys.exit(1)
except Exception as e:
print(f"❌ Unexpected error: {e}")

23
src/skill_seekers/cli/install_skill.py
View File

@@ -60,17 +60,24 @@ Examples:
# Preview workflow (dry run)
skill-seekers install --config react --dry-run
# Install for Gemini instead of Claude
skill-seekers install --config react --target gemini
# Install for OpenAI ChatGPT
skill-seekers install --config fastapi --target openai
Important:
- Enhancement is MANDATORY (30-60 sec) for quality (3/10→9/10)
- Total time: 20-45 minutes (mostly scraping)
- Auto-uploads to Claude if ANTHROPIC_API_KEY is set
- Multi-platform support: claude (default), gemini, openai, markdown
- Auto-uploads if API key is set (ANTHROPIC_API_KEY, GOOGLE_API_KEY, or OPENAI_API_KEY)
Phases:
1. Fetch config (if config name provided)
2. Scrape documentation
3. AI Enhancement (MANDATORY - no skip option)
4. Package to .zip
5. Upload to Claude (optional)
4. Package for target platform (ZIP or tar.gz)
5. Upload to target platform (optional)
"""
)
@@ -104,6 +111,13 @@ Phases:
help="Preview workflow without executing"
)
parser.add_argument(
"--target",
choices=['claude', 'gemini', 'openai', 'markdown'],
default='claude',
help="Target LLM platform (default: claude)"
)
args = parser.parse_args()
# Determine if config is a name or path
@@ -124,7 +138,8 @@ Phases:
"destination": args.destination,
"auto_upload": not args.no_upload,
"unlimited": args.unlimited,
"dry_run": args.dry_run
"dry_run": args.dry_run,
"target": args.target
}
# Run async tool

142
src/skill_seekers/cli/package_skill.py
View File

@@ -36,17 +36,18 @@ except ImportError:
from quality_checker import SkillQualityChecker, print_report
def package_skill(skill_dir, open_folder_after=True, skip_quality_check=False):
def package_skill(skill_dir, open_folder_after=True, skip_quality_check=False, target='claude'):
"""
Package a skill directory into a .zip file
Package a skill directory into platform-specific format
Args:
skill_dir: Path to skill directory
open_folder_after: Whether to open the output folder after packaging
skip_quality_check: Skip quality checks before packaging
target: Target LLM platform ('claude', 'gemini', 'openai', 'markdown')
Returns:
tuple: (success, zip_path) where success is bool and zip_path is Path or None
tuple: (success, package_path) where success is bool and package_path is Path or None
"""
skill_path = Path(skill_dir)
@@ -80,40 +81,43 @@ def package_skill(skill_dir, open_folder_after=True, skip_quality_check=False):
print("=" * 60)
print()
# Create zip filename
# Get platform-specific adaptor
try:
from skill_seekers.cli.adaptors import get_adaptor
adaptor = get_adaptor(target)
except (ImportError, ValueError) as e:
print(f"❌ Error: {e}")
return False, None
# Create package using adaptor
skill_name = skill_path.name
zip_path = skill_path.parent / f"{skill_name}.zip"
output_dir = skill_path.parent
print(f"📦 Packaging skill: {skill_name}")
print(f" Target: {adaptor.PLATFORM_NAME}")
print(f" Source: {skill_path}")
print(f" Output: {zip_path}")
# Create zip file
with zipfile.ZipFile(zip_path, 'w', zipfile.ZIP_DEFLATED) as zf:
for root, dirs, files in os.walk(skill_path):
# Skip backup files
files = [f for f in files if not f.endswith('.backup')]
try:
package_path = adaptor.package(skill_path, output_dir)
print(f" Output: {package_path}")
except Exception as e:
print(f"❌ Error creating package: {e}")
return False, None
for file in files:
file_path = Path(root) / file
arcname = file_path.relative_to(skill_path)
zf.write(file_path, arcname)
print(f" + {arcname}")
# Get zip size
zip_size = zip_path.stat().st_size
print(f"\n✅ Package created: {zip_path}")
print(f" Size: {zip_size:,} bytes ({format_file_size(zip_size)})")
# Get package size
package_size = package_path.stat().st_size
print(f"\n✅ Package created: {package_path}")
print(f" Size: {package_size:,} bytes ({format_file_size(package_size)})")
# Open folder in file browser
if open_folder_after:
print(f"\n📂 Opening folder: {zip_path.parent}")
open_folder(zip_path.parent)
print(f"\n📂 Opening folder: {package_path.parent}")
open_folder(package_path.parent)
# Print upload instructions
print_upload_instructions(zip_path)
print_upload_instructions(package_path)
return True, zip_path
return True, package_path
def main():
@@ -156,18 +160,26 @@ Examples:
help='Skip quality checks before packaging'
)
parser.add_argument(
'--target',
choices=['claude', 'gemini', 'openai', 'markdown'],
default='claude',
help='Target LLM platform (default: claude)'
)
parser.add_argument(
'--upload',
action='store_true',
help='Automatically upload to Claude after packaging (requires ANTHROPIC_API_KEY)'
help='Automatically upload after packaging (requires platform API key)'
)
args = parser.parse_args()
success, zip_path = package_skill(
success, package_path = package_skill(
args.skill_dir,
open_folder_after=not args.no_open,
skip_quality_check=args.skip_quality_check
skip_quality_check=args.skip_quality_check,
target=args.target
)
if not success:
@@ -175,42 +187,58 @@ Examples:
# Auto-upload if requested
if args.upload:
# Check if API key is set BEFORE attempting upload
api_key = os.environ.get('ANTHROPIC_API_KEY', '').strip()
if not api_key:
# No API key - show helpful message but DON'T fail
print("\n" + "="*60)
print("💡 Automatic Upload")
print("="*60)
print()
print("To enable automatic upload:")
print(" 1. Get API key from https://console.anthropic.com/")
print(" 2. Set: export ANTHROPIC_API_KEY=sk-ant-...")
print(" 3. Run package_skill.py with --upload flag")
print()
print("For now, use manual upload (instructions above) ☝️")
print("="*60)
# Exit successfully - packaging worked!
sys.exit(0)
# API key exists - try upload
try:
from upload_skill import upload_skill_api
from skill_seekers.cli.adaptors import get_adaptor
# Get adaptor for target platform
adaptor = get_adaptor(args.target)
# Get API key from environment
api_key = os.environ.get(adaptor.get_env_var_name(), '').strip()
if not api_key:
# No API key - show helpful message but DON'T fail
print("\n" + "="*60)
print("💡 Automatic Upload")
print("="*60)
print()
print(f"To enable automatic upload to {adaptor.PLATFORM_NAME}:")
print(f" 1. Get API key from the platform")
print(f" 2. Set: export {adaptor.get_env_var_name()}=...")
print(f" 3. Run package command with --upload flag")
print()
print("For now, use manual upload (instructions above) ☝️")
print("="*60)
# Exit successfully - packaging worked!
sys.exit(0)
# API key exists - try upload
print("\n" + "="*60)
upload_success, message = upload_skill_api(zip_path)
if not upload_success:
print(f"❌ Upload failed: {message}")
print(f"📤 Uploading to {adaptor.PLATFORM_NAME}...")
print("="*60)
result = adaptor.upload(package_path, api_key)
if result['success']:
print(f"\n✅ {result['message']}")
if result['url']:
print(f" View at: {result['url']}")
print("="*60)
sys.exit(0)
else:
print(f"\n❌ Upload failed: {result['message']}")
print()
print("💡 Try manual upload instead (instructions above) ☝️")
print("="*60)
# Exit successfully - packaging worked even if upload failed
sys.exit(0)
else:
print("="*60)
sys.exit(0)
except ImportError:
print("\n❌ Error: upload_skill.py not found")
except ImportError as e:
print(f"\n❌ Error: {e}")
print("Install required dependencies for this platform")
sys.exit(1)
except Exception as e:
print(f"\n❌ Upload error: {e}")
sys.exit(1)
sys.exit(0)

82
src/skill_seekers/cli/split_config.py
View File

@@ -36,15 +36,37 @@ class ConfigSplitter:
print(f"❌ Error: Invalid JSON in config file: {e}")
sys.exit(1)
def is_unified_config(self) -> bool:
"""Check if this is a unified multi-source config"""
return 'sources' in self.config
def get_split_strategy(self) -> str:
"""Determine split strategy"""
# Check if strategy is defined in config
# For unified configs, default to source-based splitting
if self.is_unified_config():
if self.strategy == "auto":
num_sources = len(self.config.get('sources', []))
if num_sources <= 1:
print(f"ℹ️ Single source unified config - no splitting needed")
return "none"
else:
print(f"ℹ️ Multi-source unified config ({num_sources} sources) - source split recommended")
return "source"
# For unified configs, only 'source' and 'none' strategies are valid
elif self.strategy in ['source', 'none']:
return self.strategy
else:
print(f"⚠️ Warning: Strategy '{self.strategy}' not supported for unified configs")
print(f"ℹ️ Using 'source' strategy instead")
return "source"
# Check if strategy is defined in config (documentation configs)
if 'split_strategy' in self.config:
config_strategy = self.config['split_strategy']
if config_strategy != "none":
return config_strategy
# Use provided strategy or auto-detect
# Use provided strategy or auto-detect (documentation configs)
if self.strategy == "auto":
max_pages = self.config.get('max_pages', 500)
@@ -147,6 +169,46 @@ class ConfigSplitter:
print(f"✅ Created {len(configs)} size-based configs ({self.target_pages} pages each)")
return configs
def split_by_source(self) -> List[Dict[str, Any]]:
"""Split unified config by source type"""
if not self.is_unified_config():
print("❌ Error: Config is not a unified config (missing 'sources' key)")
sys.exit(1)
sources = self.config.get('sources', [])
if not sources:
print("❌ Error: No sources defined in unified config")
sys.exit(1)
configs = []
source_type_counts = defaultdict(int)
for source in sources:
source_type = source.get('type', 'unknown')
source_type_counts[source_type] += 1
count = source_type_counts[source_type]
# Create new config for this source
new_config = {
'name': f"{self.base_name}-{source_type}" + (f"-{count}" if count > 1 else ""),
'description': f"{self.base_name.capitalize()} - {source_type.title()} source. {self.config.get('description', '')}",
'sources': [source] # Single source per config
}
# Copy merge_mode if it exists
if 'merge_mode' in self.config:
new_config['merge_mode'] = self.config['merge_mode']
configs.append(new_config)
print(f"✅ Created {len(configs)} source-based configs")
# Show breakdown by source type
for source_type, count in source_type_counts.items():
print(f" 📄 {count}x {source_type}")
return configs
def create_router_config(self, sub_configs: List[Dict[str, Any]]) -> Dict[str, Any]:
"""Create a router config that references sub-skills"""
router_name = self.config.get('split_config', {}).get('router_name', self.base_name)
@@ -173,17 +235,22 @@ class ConfigSplitter:
"""Execute split based on strategy"""
strategy = self.get_split_strategy()
config_type = "UNIFIED" if self.is_unified_config() else "DOCUMENTATION"
print(f"\n{'='*60}")
print(f"CONFIG SPLITTER: {self.base_name}")
print(f"CONFIG SPLITTER: {self.base_name} ({config_type})")
print(f"{'='*60}")
print(f"Strategy: {strategy}")
print(f"Target pages per skill: {self.target_pages}")
if not self.is_unified_config():
print(f"Target pages per skill: {self.target_pages}")
print("")
if strategy == "none":
print("ℹ️ No splitting required")
return [self.config]
elif strategy == "source":
return self.split_by_source()
elif strategy == "category":
return self.split_by_category(create_router=False)
@@ -245,9 +312,14 @@ Examples:
Split Strategies:
none - No splitting (single skill)
auto - Automatically choose best strategy
source - Split unified configs by source type (docs, github, pdf)
category - Split by categories defined in config
router - Create router + category-based sub-skills
size - Split by page count
Config Types:
Documentation - Single base_url config (supports: category, router, size)
Unified - Multi-source config (supports: source)
"""
)
@@ -258,7 +330,7 @@ Split Strategies:
parser.add_argument(
'--strategy',
choices=['auto', 'none', 'category', 'router', 'size'],
choices=['auto', 'none', 'source', 'category', 'router', 'size'],
default='auto',
help='Splitting strategy (default: auto)'
)

170
src/skill_seekers/cli/upload_skill.py
View File

@@ -1,15 +1,20 @@
#!/usr/bin/env python3
"""
Automatic Skill Uploader
Uploads a skill .zip file to Claude using the Anthropic API
Uploads a skill package to LLM platforms (Claude, Gemini, OpenAI, etc.)
Usage:
# Set API key (one-time)
# Claude (default)
export ANTHROPIC_API_KEY=sk-ant-...
skill-seekers upload output/react.zip
# Upload skill
python3 upload_skill.py output/react.zip
python3 upload_skill.py output/godot.zip
# Gemini
export GOOGLE_API_KEY=AIzaSy...
skill-seekers upload output/react-gemini.tar.gz --target gemini
# OpenAI
export OPENAI_API_KEY=sk-proj-...
skill-seekers upload output/react-openai.zip --target openai
"""
import os
@@ -21,108 +26,84 @@ from pathlib import Path
# Import utilities
try:
from utils import (
get_api_key,
get_upload_url,
print_upload_instructions,
validate_zip_file
)
except ImportError:
sys.path.insert(0, str(Path(__file__).parent))
from utils import (
get_api_key,
get_upload_url,
print_upload_instructions,
validate_zip_file
)
def upload_skill_api(zip_path):
def upload_skill_api(package_path, target='claude', api_key=None):
"""
Upload skill to Claude via Anthropic API
Upload skill package to LLM platform
Args:
zip_path: Path to skill .zip file
package_path: Path to skill package file
target: Target platform ('claude', 'gemini', 'openai')
api_key: Optional API key (otherwise read from environment)
Returns:
tuple: (success, message)
"""
# Check for requests library
try:
import requests
from skill_seekers.cli.adaptors import get_adaptor
except ImportError:
return False, "requests library not installed. Run: pip install requests"
return False, "Adaptor system not available. Reinstall skill-seekers."
# Validate zip file
is_valid, error_msg = validate_zip_file(zip_path)
if not is_valid:
return False, error_msg
# Get platform-specific adaptor
try:
adaptor = get_adaptor(target)
except ValueError as e:
return False, str(e)
# Get API key
api_key = get_api_key()
if not api_key:
return False, "ANTHROPIC_API_KEY not set. Run: export ANTHROPIC_API_KEY=sk-ant-..."
api_key = os.environ.get(adaptor.get_env_var_name(), '').strip()
zip_path = Path(zip_path)
skill_name = zip_path.stem
if not api_key:
return False, f"{adaptor.get_env_var_name()} not set. Export your API key first."
# Validate API key format
if not adaptor.validate_api_key(api_key):
return False, f"Invalid API key format for {adaptor.PLATFORM_NAME}"
package_path = Path(package_path)
# Basic file validation
if not package_path.exists():
return False, f"File not found: {package_path}"
skill_name = package_path.stem
print(f"📤 Uploading skill: {skill_name}")
print(f" Source: {zip_path}")
print(f" Size: {zip_path.stat().st_size:,} bytes")
print(f" Target: {adaptor.PLATFORM_NAME}")
print(f" Source: {package_path}")
print(f" Size: {package_path.stat().st_size:,} bytes")
print()
# Prepare API request
api_url = "https://api.anthropic.com/v1/skills"
headers = {
"x-api-key": api_key,
"anthropic-version": "2023-06-01",
"anthropic-beta": "skills-2025-10-02"
}
# Upload using adaptor
print(f"⏳ Uploading to {adaptor.PLATFORM_NAME}...")
try:
# Read zip file
with open(zip_path, 'rb') as f:
zip_data = f.read()
result = adaptor.upload(package_path, api_key)
# Upload skill
print("⏳ Uploading to Anthropic API...")
files = {
'files[]': (zip_path.name, zip_data, 'application/zip')
}
response = requests.post(
api_url,
headers=headers,
files=files,
timeout=60
)
# Check response
if response.status_code == 200:
if result['success']:
print()
print("✅ Skill uploaded successfully!")
print(f"✅ {result['message']}")
print()
print("Your skill is now available in Claude at:")
print(f" {get_upload_url()}")
if result['url']:
print("Your skill is now available at:")
print(f" {result['url']}")
if result['skill_id']:
print(f" Skill ID: {result['skill_id']}")
print()
return True, "Upload successful"
elif response.status_code == 401:
return False, "Authentication failed. Check your ANTHROPIC_API_KEY"
elif response.status_code == 400:
error_msg = response.json().get('error', {}).get('message', 'Unknown error')
return False, f"Invalid skill format: {error_msg}"
else:
error_msg = response.json().get('error', {}).get('message', 'Unknown error')
return False, f"Upload failed ({response.status_code}): {error_msg}"
except requests.exceptions.Timeout:
return False, "Upload timed out. Try again or use manual upload"
except requests.exceptions.ConnectionError:
return False, "Connection error. Check your internet connection"
return False, result['message']
except Exception as e:
return False, f"Unexpected error: {str(e)}"
@@ -130,36 +111,55 @@ def upload_skill_api(zip_path):
def main():
parser = argparse.ArgumentParser(
description="Upload a skill .zip file to Claude via Anthropic API",
description="Upload a skill package to LLM platforms",
formatter_class=argparse.RawDescriptionHelpFormatter,
epilog="""
Setup:
1. Get your Anthropic API key from https://console.anthropic.com/
2. Set the API key:
export ANTHROPIC_API_KEY=sk-ant-...
Claude:
export ANTHROPIC_API_KEY=sk-ant-...
Gemini:
export GOOGLE_API_KEY=AIzaSy...
OpenAI:
export OPENAI_API_KEY=sk-proj-...
Examples:
# Upload skill
python3 upload_skill.py output/react.zip
# Upload to Claude (default)
skill-seekers upload output/react.zip
# Upload with explicit path
python3 upload_skill.py /path/to/skill.zip
# Upload to Gemini
skill-seekers upload output/react-gemini.tar.gz --target gemini
Requirements:
- ANTHROPIC_API_KEY environment variable must be set
- requests library (pip install requests)
# Upload to OpenAI
skill-seekers upload output/react-openai.zip --target openai
# Upload with explicit API key
skill-seekers upload output/react.zip --api-key sk-ant-...
"""
)
parser.add_argument(
'zip_file',
help='Path to skill .zip file (e.g., output/react.zip)'
'package_file',
help='Path to skill package file (e.g., output/react.zip)'
)
parser.add_argument(
'--target',
choices=['claude', 'gemini', 'openai'],
default='claude',
help='Target LLM platform (default: claude)'
)
parser.add_argument(
'--api-key',
help='Platform API key (or set environment variable)'
)
args = parser.parse_args()
# Upload skill
success, message = upload_skill_api(args.zip_file)
success, message = upload_skill_api(args.package_file, args.target, args.api_key)
if success:
sys.exit(0)
@@ -167,7 +167,7 @@ Requirements:
print(f"\n❌ Upload failed: {message}")
print()
print("📝 Manual upload instructions:")
print_upload_instructions(args.zip_file)
print_upload_instructions(args.package_file)
sys.exit(1)

63
src/skill_seekers/mcp/README.md
View File

@@ -73,7 +73,7 @@ You should see a list of preset configurations (Godot, React, Vue, etc.).
## Available Tools
The MCP server exposes 10 tools:
The MCP server exposes 18 tools:
### 1. `generate_config`
Create a new configuration file for any documentation website.
@@ -117,29 +117,66 @@ Scrape docs using configs/react.json
```
### 4. `package_skill`
Package a skill directory into a `.zip` file ready for Claude upload. Automatically uploads if ANTHROPIC_API_KEY is set.
Package skill directory into platform-specific format. Automatically uploads if platform API key is set.
**Parameters:**
- `skill_dir` (required): Path to skill directory (e.g., "output/react/")
- `target` (optional): Target platform - "claude", "gemini", "openai", "markdown" (default: "claude")
- `auto_upload` (optional): Try to upload automatically if API key is available (default: true)
**Example:**
**Platform-specific outputs:**
- Claude/OpenAI/Markdown: `.zip` file
- Gemini: `.tar.gz` file
**Examples:**
```
Package skill at output/react/
Package skill for Claude (default): output/react/
Package skill for Gemini: output/react/ with target gemini
Package skill for OpenAI: output/react/ with target openai
Package skill for Markdown: output/react/ with target markdown
```
### 5. `upload_skill`
Upload a skill .zip file to Claude automatically (requires ANTHROPIC_API_KEY).
Upload skill package to target LLM platform (requires platform-specific API key).
**Parameters:**
- `skill_zip` (required): Path to skill .zip file (e.g., "output/react.zip")
- `skill_zip` (required): Path to skill package (`.zip` or `.tar.gz`)
- `target` (optional): Target platform - "claude", "gemini", "openai" (default: "claude")
**Example:**
**Examples:**
```
Upload output/react.zip using upload_skill
Upload to Claude: output/react.zip
Upload to Gemini: output/react-gemini.tar.gz with target gemini
Upload to OpenAI: output/react-openai.zip with target openai
```
### 6. `list_configs`
**Note:** Requires platform-specific API key (ANTHROPIC_API_KEY, GOOGLE_API_KEY, or OPENAI_API_KEY)
### 6. `enhance_skill`
Enhance SKILL.md with AI using target platform's model. Transforms basic templates into comprehensive guides.
**Parameters:**
- `skill_dir` (required): Path to skill directory (e.g., "output/react/")
- `target` (optional): Target platform - "claude", "gemini", "openai" (default: "claude")
- `mode` (optional): "local" (Claude Code Max, no API key) or "api" (requires API key) (default: "local")
- `api_key` (optional): Platform API key (uses env var if not provided)
**What it does:**
- Transforms basic SKILL.md templates into comprehensive 500+ line guides
- Uses platform-specific AI models (Claude Sonnet 4, Gemini 2.0 Flash, GPT-4o)
- Extracts best examples from references
- Adds platform-specific formatting
**Examples:**
```
Enhance with Claude locally (no API key): output/react/
Enhance with Gemini API: output/react/ with target gemini and mode api
Enhance with OpenAI API: output/react/ with target openai and mode api
```
**Note:** Local mode uses Claude Code Max (requires Claude Code but no API key). API mode requires platform-specific API key.
### 7. `list_configs`
List all available preset configurations.
**Parameters:** None
@@ -149,7 +186,7 @@ List all available preset configurations.
List all available configs
```
### 7. `validate_config`
### 8. `validate_config`
Validate a config file for errors.
**Parameters:**
@@ -160,7 +197,7 @@ Validate a config file for errors.
Validate configs/godot.json
```
### 8. `split_config`
### 9. `split_config`
Split large documentation config into multiple focused skills. For 10K+ page documentation.
**Parameters:**
@@ -180,7 +217,7 @@ Split configs/godot.json using router strategy with 5000 pages per skill
- **router** - Create router/hub skill + specialized sub-skills (RECOMMENDED for 10K+ pages)
- **size** - Split every N pages (for docs without clear categories)
### 9. `generate_router`
### 10. `generate_router`
Generate router/hub skill for split documentation. Creates intelligent routing to sub-skills.
**Parameters:**
@@ -198,7 +235,7 @@ Generate router for configs/godot-*.json
- Creates router SKILL.md with intelligent routing logic
- Users can ask questions naturally, router directs to appropriate sub-skill
### 10. `scrape_pdf`
### 11. `scrape_pdf`
Scrape PDF documentation and build Claude skill. Extracts text, code blocks, images, and tables from PDF files with advanced features.
**Parameters:**

96
src/skill_seekers/mcp/server_fastmcp.py
View File

@@ -84,6 +84,7 @@ try:
# Packaging tools
package_skill_impl,
upload_skill_impl,
enhance_skill_impl,
install_skill_impl,
# Splitting tools
split_config_impl,
@@ -109,6 +110,7 @@ except ImportError:
scrape_pdf_impl,
package_skill_impl,
upload_skill_impl,
enhance_skill_impl,
install_skill_impl,
split_config_impl,
generate_router_impl,
@@ -397,24 +399,27 @@ async def scrape_pdf(
@safe_tool_decorator(
description="Package a skill directory into a .zip file ready for Claude upload. Automatically uploads if ANTHROPIC_API_KEY is set."
description="Package skill directory into platform-specific format (ZIP for Claude/OpenAI/Markdown, tar.gz for Gemini). Supports all platforms: claude, gemini, openai, markdown. Automatically uploads if platform API key is set."
)
async def package_skill(
skill_dir: str,
target: str = "claude",
auto_upload: bool = True,
) -> str:
"""
Package a skill directory into a .zip file.
Package skill directory for target LLM platform.
Args:
skill_dir: Path to skill directory (e.g., output/react/)
auto_upload: Try to upload automatically if API key is available (default: true). If false, only package without upload attempt.
skill_dir: Path to skill directory to package (e.g., output/react/)
target: Target platform (default: 'claude'). Options: claude, gemini, openai, markdown
auto_upload: Auto-upload after packaging if API key is available (default: true). Requires platform-specific API key: ANTHROPIC_API_KEY, GOOGLE_API_KEY, or OPENAI_API_KEY.
Returns:
Packaging results with .zip file path and upload status.
Packaging results with file path and platform info.
"""
args = {
"skill_dir": skill_dir,
"target": target,
"auto_upload": auto_upload,
}
result = await package_skill_impl(args)
@@ -424,26 +429,74 @@ async def package_skill(
@safe_tool_decorator(
description="Upload a skill .zip file to Claude automatically (requires ANTHROPIC_API_KEY)"
description="Upload skill package to target LLM platform API. Requires platform-specific API key. Supports: claude (Anthropic Skills API), gemini (Google Files API), openai (Assistants API). Does NOT support markdown."
)
async def upload_skill(skill_zip: str) -> str:
async def upload_skill(
skill_zip: str,
target: str = "claude",
api_key: str | None = None,
) -> str:
"""
Upload a skill .zip file to Claude.
Upload skill package to target platform.
Args:
skill_zip: Path to skill .zip file (e.g., output/react.zip)
skill_zip: Path to skill package (.zip or .tar.gz, e.g., output/react.zip)
target: Target platform (default: 'claude'). Options: claude, gemini, openai
api_key: Optional API key (uses env var if not provided: ANTHROPIC_API_KEY, GOOGLE_API_KEY, or OPENAI_API_KEY)
Returns:
Upload results with success/error message.
Upload results with skill ID and platform URL.
"""
result = await upload_skill_impl({"skill_zip": skill_zip})
args = {
"skill_zip": skill_zip,
"target": target,
}
if api_key:
args["api_key"] = api_key
result = await upload_skill_impl(args)
if isinstance(result, list) and result:
return result[0].text if hasattr(result[0], "text") else str(result[0])
return str(result)
@safe_tool_decorator(
description="Complete one-command workflow: fetch config → scrape docs → AI enhance (MANDATORY) → package → upload. Enhancement required for quality (3/10→9/10). Takes 20-45 min depending on config size. Automatically uploads to Claude if ANTHROPIC_API_KEY is set."
description="Enhance SKILL.md with AI using target platform's model. Local mode uses Claude Code Max (no API key). API mode uses platform API (requires key). Transforms basic templates into comprehensive 500+ line guides with examples."
)
async def enhance_skill(
skill_dir: str,
target: str = "claude",
mode: str = "local",
api_key: str | None = None,
) -> str:
"""
Enhance SKILL.md with AI.
Args:
skill_dir: Path to skill directory containing SKILL.md (e.g., output/react/)
target: Target platform (default: 'claude'). Options: claude, gemini, openai
mode: Enhancement mode (default: 'local'). Options: local (Claude Code, no API), api (uses platform API)
api_key: Optional API key for 'api' mode (uses env var if not provided: ANTHROPIC_API_KEY, GOOGLE_API_KEY, or OPENAI_API_KEY)
Returns:
Enhancement results with backup location.
"""
args = {
"skill_dir": skill_dir,
"target": target,
"mode": mode,
}
if api_key:
args["api_key"] = api_key
result = await enhance_skill_impl(args)
if isinstance(result, list) and result:
return result[0].text if hasattr(result[0], "text") else str(result[0])
return str(result)
@safe_tool_decorator(
description="Complete one-command workflow: fetch config → scrape docs → AI enhance (MANDATORY) → package → upload. Enhancement required for quality (3/10→9/10). Takes 20-45 min depending on config size. Supports multiple LLM platforms: claude (default), gemini, openai, markdown. Auto-uploads if platform API key is set."
)
async def install_skill(
config_name: str | None = None,
@@ -452,6 +505,7 @@ async def install_skill(
auto_upload: bool = True,
unlimited: bool = False,
dry_run: bool = False,
target: str = "claude",
) -> str:
"""
Complete one-command workflow to install a skill.
@@ -460,9 +514,10 @@ async def install_skill(
config_name: Config name from API (e.g., 'react', 'django'). Mutually exclusive with config_path. Tool will fetch this config from the official API before scraping.
config_path: Path to existing config JSON file (e.g., 'configs/custom.json'). Mutually exclusive with config_name. Use this if you already have a config file.
destination: Output directory for skill files (default: 'output')
auto_upload: Auto-upload to Claude after packaging (requires ANTHROPIC_API_KEY). Default: true. Set to false to skip upload.
auto_upload: Auto-upload after packaging (requires platform API key). Default: true. Set to false to skip upload.
unlimited: Remove page limits during scraping (default: false). WARNING: Can take hours for large sites.
dry_run: Preview workflow without executing (default: false). Shows all phases that would run.
target: Target LLM platform (default: 'claude'). Options: claude, gemini, openai, markdown. Requires corresponding API key: ANTHROPIC_API_KEY, GOOGLE_API_KEY, or OPENAI_API_KEY.
Returns:
Workflow results with all phase statuses.
@@ -472,6 +527,7 @@ async def install_skill(
"auto_upload": auto_upload,
"unlimited": unlimited,
"dry_run": dry_run,
"target": target,
}
if config_name:
args["config_name"] = config_name
@@ -490,7 +546,7 @@ async def install_skill(
@safe_tool_decorator(
description="Split large documentation config into multiple focused skills. For 10K+ page documentation."
description="Split large configs into multiple focused skills. Supports documentation (10K+ pages) and unified multi-source configs. Auto-detects config type and recommends best strategy."
)
async def split_config(
config_path: str,
@@ -499,12 +555,16 @@ async def split_config(
dry_run: bool = False,
) -> str:
"""
Split large documentation config into multiple skills.
Split large configs into multiple skills.
Supports:
- Documentation configs: Split by categories, size, or create router skills
- Unified configs: Split by source type (documentation, github, pdf)
Args:
config_path: Path to config JSON file (e.g., configs/godot.json)
strategy: Split strategy: auto, none, category, router, size (default: auto)
target_pages: Target pages per skill (default: 5000)
config_path: Path to config JSON file (e.g., configs/godot.json or configs/react_unified.json)
strategy: Split strategy: auto, none, source, category, router, size (default: auto). 'source' is for unified configs.
target_pages: Target pages per skill for doc configs (default: 5000)
dry_run: Preview without saving files (default: false)
Returns:

2
src/skill_seekers/mcp/tools/__init__.py
View File

@@ -29,6 +29,7 @@ from .scraping_tools import (
from .packaging_tools import (
package_skill_tool as package_skill_impl,
upload_skill_tool as upload_skill_impl,
enhance_skill_tool as enhance_skill_impl,
install_skill_tool as install_skill_impl,
)
@@ -58,6 +59,7 @@ __all__ = [
# Packaging tools
"package_skill_impl",
"upload_skill_impl",
"enhance_skill_impl",
"install_skill_impl",
# Splitting tools
"split_config_impl",

7
src/skill_seekers/mcp/tools/config_tools.py
View File

@@ -13,7 +13,12 @@ from typing import Any, List
try:
from mcp.types import TextContent
except ImportError:
TextContent = None
# Graceful degradation: Create a simple fallback class for testing
class TextContent:
"""Fallback TextContent for when MCP is not installed"""
def __init__(self, type: str, text: str):
self.type = type
self.text = text
# Path to CLI tools
CLI_DIR = Path(__file__).parent.parent.parent / "cli"

407
src/skill_seekers/mcp/tools/packaging_tools.py
View File

@@ -18,7 +18,12 @@ from typing import Any, List, Tuple
try:
from mcp.types import TextContent
except ImportError:
TextContent = None # Graceful degradation
# Graceful degradation: Create a simple fallback class for testing
class TextContent:
"""Fallback TextContent for when MCP is not installed"""
def __init__(self, type: str, text: str):
self.type = type
self.text = text
# Path to CLI tools
@@ -102,30 +107,46 @@ def run_subprocess_with_streaming(cmd: List[str], timeout: int = None) -> Tuple[
async def package_skill_tool(args: dict) -> List[TextContent]:
"""
Package skill to .zip and optionally auto-upload.
Package skill for target LLM platform and optionally auto-upload.
Args:
args: Dictionary with:
- skill_dir (str): Path to skill directory (e.g., output/react/)
- auto_upload (bool): Try to upload automatically if API key is available (default: True)
- target (str): Target platform (default: 'claude')
Options: 'claude', 'gemini', 'openai', 'markdown'
Returns:
List of TextContent with packaging results
"""
from skill_seekers.cli.adaptors import get_adaptor
skill_dir = args["skill_dir"]
auto_upload = args.get("auto_upload", True)
target = args.get("target", "claude")
# Check if API key exists - only upload if available
has_api_key = os.environ.get('ANTHROPIC_API_KEY', '').strip()
# Get platform adaptor
try:
adaptor = get_adaptor(target)
except ValueError as e:
return [TextContent(
type="text",
text=f"❌ Invalid platform: {str(e)}\n\nSupported platforms: claude, gemini, openai, markdown"
)]
# Check if platform-specific API key exists - only upload if available
env_var_name = adaptor.get_env_var_name()
has_api_key = os.environ.get(env_var_name, '').strip() if env_var_name else False
should_upload = auto_upload and has_api_key
# Run package_skill.py
# Run package_skill.py with target parameter
cmd = [
sys.executable,
str(CLI_DIR / "package_skill.py"),
skill_dir,
"--no-open", # Don't open folder in MCP context
"--skip-quality-check" # Skip interactive quality checks in MCP context
"--skip-quality-check", # Skip interactive quality checks in MCP context
"--target", target # Add target platform
]
# Add upload flag only if we have API key
@@ -135,9 +156,9 @@ async def package_skill_tool(args: dict) -> List[TextContent]:
# Timeout: 5 minutes for packaging + upload
timeout = 300
progress_msg = "📦 Packaging skill...\n"
progress_msg = f"📦 Packaging skill for {adaptor.PLATFORM_NAME}...\n"
if should_upload:
progress_msg += "📤 Will auto-upload if successful\n"
progress_msg += f"📤 Will auto-upload to {adaptor.PLATFORM_NAME} if successful\n"
progress_msg += f"⏱️ Maximum time: {timeout // 60} minutes\n\n"
stdout, stderr, returncode = run_subprocess_with_streaming(cmd, timeout=timeout)
@@ -147,24 +168,54 @@ async def package_skill_tool(args: dict) -> List[TextContent]:
if returncode == 0:
if should_upload:
# Upload succeeded
output += "\n\n✅ Skill packaged and uploaded automatically!"
output += "\n Your skill is now available in Claude!"
output += f"\n\n✅ Skill packaged and uploaded to {adaptor.PLATFORM_NAME}!"
if target == 'claude':
output += "\n Your skill is now available in Claude!"
output += "\n Go to https://claude.ai/skills to use it"
elif target == 'gemini':
output += "\n Your skill is now available in Gemini!"
output += "\n Go to https://aistudio.google.com/ to use it"
elif target == 'openai':
output += "\n Your assistant is now available in OpenAI!"
output += "\n Go to https://platform.openai.com/assistants/ to use it"
elif auto_upload and not has_api_key:
# User wanted upload but no API key
output += "\n\n📝 Skill packaged successfully!"
output += f"\n\n📝 Skill packaged successfully for {adaptor.PLATFORM_NAME}!"
output += "\n"
output += "\n💡 To enable automatic upload:"
output += "\n 1. Get API key from https://console.anthropic.com/"
output += "\n 2. Set: export ANTHROPIC_API_KEY=sk-ant-..."
output += "\n"
output += "\n📤 Manual upload:"
output += "\n 1. Find the .zip file in your output/ folder"
output += "\n 2. Go to https://claude.ai/skills"
output += "\n 3. Click 'Upload Skill' and select the .zip file"
if target == 'claude':
output += "\n 1. Get API key from https://console.anthropic.com/"
output += "\n 2. Set: export ANTHROPIC_API_KEY=sk-ant-..."
output += "\n\n📤 Manual upload:"
output += "\n 1. Find the .zip file in your output/ folder"
output += "\n 2. Go to https://claude.ai/skills"
output += "\n 3. Click 'Upload Skill' and select the .zip file"
elif target == 'gemini':
output += "\n 1. Get API key from https://aistudio.google.com/"
output += "\n 2. Set: export GOOGLE_API_KEY=AIza..."
output += "\n\n📤 Manual upload:"
output += "\n 1. Go to https://aistudio.google.com/"
output += "\n 2. Upload the .tar.gz file from your output/ folder"
elif target == 'openai':
output += "\n 1. Get API key from https://platform.openai.com/"
output += "\n 2. Set: export OPENAI_API_KEY=sk-proj-..."
output += "\n\n📤 Manual upload:"
output += "\n 1. Use OpenAI Assistants API"
output += "\n 2. Upload the .zip file from your output/ folder"
elif target == 'markdown':
output += "\n (No API key needed - markdown is export only)"
output += "\n Package created for manual distribution"
else:
# auto_upload=False, just packaged
output += "\n\n✅ Skill packaged successfully!"
output += "\n Upload manually to https://claude.ai/skills"
output += f"\n\n✅ Skill packaged successfully for {adaptor.PLATFORM_NAME}!"
if target == 'claude':
output += "\n Upload manually to https://claude.ai/skills"
elif target == 'gemini':
output += "\n Upload manually to https://aistudio.google.com/"
elif target == 'openai':
output += "\n Upload manually via OpenAI Assistants API"
elif target == 'markdown':
output += "\n Package ready for manual distribution"
return [TextContent(type="text", text=output)]
else:
@@ -173,28 +224,57 @@ async def package_skill_tool(args: dict) -> List[TextContent]:
async def upload_skill_tool(args: dict) -> List[TextContent]:
"""
Upload skill .zip to Claude.
Upload skill package to target LLM platform.
Args:
args: Dictionary with:
- skill_zip (str): Path to skill .zip file (e.g., output/react.zip)
- skill_zip (str): Path to skill package (.zip or .tar.gz)
- target (str): Target platform (default: 'claude')
Options: 'claude', 'gemini', 'openai'
Note: 'markdown' does not support upload
- api_key (str, optional): API key (uses env var if not provided)
Returns:
List of TextContent with upload results
"""
skill_zip = args["skill_zip"]
from skill_seekers.cli.adaptors import get_adaptor
# Run upload_skill.py
skill_zip = args["skill_zip"]
target = args.get("target", "claude")
api_key = args.get("api_key")
# Get platform adaptor
try:
adaptor = get_adaptor(target)
except ValueError as e:
return [TextContent(
type="text",
text=f"❌ Invalid platform: {str(e)}\n\nSupported platforms: claude, gemini, openai"
)]
# Check if upload is supported
if target == 'markdown':
return [TextContent(
type="text",
text="❌ Markdown export does not support upload. Use the packaged file manually."
)]
# Run upload_skill.py with target parameter
cmd = [
sys.executable,
str(CLI_DIR / "upload_skill.py"),
skill_zip
skill_zip,
"--target", target
]
# Add API key if provided
if api_key:
cmd.extend(["--api-key", api_key])
# Timeout: 5 minutes for upload
timeout = 300
progress_msg = "📤 Uploading skill to Claude...\n"
progress_msg = f"📤 Uploading skill to {adaptor.PLATFORM_NAME}...\n"
progress_msg += f"⏱️ Maximum time: {timeout // 60} minutes\n\n"
stdout, stderr, returncode = run_subprocess_with_streaming(cmd, timeout=timeout)
@@ -207,6 +287,142 @@ async def upload_skill_tool(args: dict) -> List[TextContent]:
return [TextContent(type="text", text=f"{output}\n\n❌ Error:\n{stderr}")]
async def enhance_skill_tool(args: dict) -> List[TextContent]:
"""
Enhance SKILL.md with AI using target platform's model.
Args:
args: Dictionary with:
- skill_dir (str): Path to skill directory
- target (str): Target platform (default: 'claude')
Options: 'claude', 'gemini', 'openai'
Note: 'markdown' does not support enhancement
- mode (str): Enhancement mode (default: 'local')
'local': Uses Claude Code Max (no API key)
'api': Uses platform API (requires API key)
- api_key (str, optional): API key for 'api' mode
Returns:
List of TextContent with enhancement results
"""
from skill_seekers.cli.adaptors import get_adaptor
skill_dir = Path(args.get("skill_dir"))
target = args.get("target", "claude")
mode = args.get("mode", "local")
api_key = args.get("api_key")
# Validate skill directory
if not skill_dir.exists():
return [TextContent(
type="text",
text=f"❌ Skill directory not found: {skill_dir}"
)]
if not (skill_dir / "SKILL.md").exists():
return [TextContent(
type="text",
text=f"❌ SKILL.md not found in {skill_dir}"
)]
# Get platform adaptor
try:
adaptor = get_adaptor(target)
except ValueError as e:
return [TextContent(
type="text",
text=f"❌ Invalid platform: {str(e)}\n\nSupported platforms: claude, gemini, openai"
)]
# Check if enhancement is supported
if not adaptor.supports_enhancement():
return [TextContent(
type="text",
text=f"❌ {adaptor.PLATFORM_NAME} does not support AI enhancement"
)]
output_lines = []
output_lines.append(f"🚀 Enhancing skill with {adaptor.PLATFORM_NAME}")
output_lines.append("-" * 70)
output_lines.append(f"Skill directory: {skill_dir}")
output_lines.append(f"Mode: {mode}")
output_lines.append("")
if mode == 'local':
# Use local enhancement (Claude Code)
output_lines.append("Using Claude Code Max (local, no API key required)")
output_lines.append("Running enhancement in headless mode...")
output_lines.append("")
cmd = [
sys.executable,
str(CLI_DIR / "enhance_skill_local.py"),
str(skill_dir)
]
try:
stdout, stderr, returncode = run_subprocess_with_streaming(cmd, timeout=900)
if returncode == 0:
output_lines.append(stdout)
output_lines.append("")
output_lines.append("✅ Enhancement complete!")
output_lines.append(f"Enhanced SKILL.md: {skill_dir / 'SKILL.md'}")
output_lines.append(f"Backup: {skill_dir / 'SKILL.md.backup'}")
else:
output_lines.append(f"❌ Enhancement failed (exit code {returncode})")
output_lines.append(stderr if stderr else stdout)
except Exception as e:
output_lines.append(f"❌ Error: {str(e)}")
elif mode == 'api':
# Use API enhancement
output_lines.append(f"Using {adaptor.PLATFORM_NAME} API")
# Get API key
if not api_key:
env_var = adaptor.get_env_var_name()
api_key = os.environ.get(env_var)
if not api_key:
return [TextContent(
type="text",
text=f"❌ {env_var} not set. Set API key or pass via api_key parameter."
)]
# Validate API key
if not adaptor.validate_api_key(api_key):
return [TextContent(
type="text",
text=f"❌ Invalid API key format for {adaptor.PLATFORM_NAME}"
)]
output_lines.append("Calling API for enhancement...")
output_lines.append("")
try:
success = adaptor.enhance(skill_dir, api_key)
if success:
output_lines.append("✅ Enhancement complete!")
output_lines.append(f"Enhanced SKILL.md: {skill_dir / 'SKILL.md'}")
output_lines.append(f"Backup: {skill_dir / 'SKILL.md.backup'}")
else:
output_lines.append("❌ Enhancement failed")
except Exception as e:
output_lines.append(f"❌ Error: {str(e)}")
else:
return [TextContent(
type="text",
text=f"❌ Invalid mode: {mode}. Use 'local' or 'api'"
)]
return [TextContent(type="text", text="\n".join(output_lines))]
async def install_skill_tool(args: dict) -> List[TextContent]:
"""
Complete skill installation workflow.
@@ -215,8 +431,8 @@ async def install_skill_tool(args: dict) -> List[TextContent]:
1. Fetch config (if config_name provided)
2. Scrape documentation
3. AI Enhancement (MANDATORY - no skip option)
4. Package to .zip
5. Upload to Claude (optional)
4. Package for target platform (ZIP or tar.gz)
5. Upload to target platform (optional)
Args:
args: Dictionary with:
@@ -226,13 +442,15 @@ async def install_skill_tool(args: dict) -> List[TextContent]:
- auto_upload (bool): Upload after packaging (default: True)
- unlimited (bool): Remove page limits (default: False)
- dry_run (bool): Preview only (default: False)
- target (str): Target LLM platform (default: "claude")
Returns:
List of TextContent with workflow progress and results
"""
# Import these here to avoid circular imports
from .scraping_tools import scrape_docs_tool
from .config_tools import fetch_config_tool
from .source_tools import fetch_config_tool
from skill_seekers.cli.adaptors import get_adaptor
# Extract and validate inputs
config_name = args.get("config_name")
@@ -241,6 +459,16 @@ async def install_skill_tool(args: dict) -> List[TextContent]:
auto_upload = args.get("auto_upload", True)
unlimited = args.get("unlimited", False)
dry_run = args.get("dry_run", False)
target = args.get("target", "claude")
# Get platform adaptor
try:
adaptor = get_adaptor(target)
except ValueError as e:
return [TextContent(
type="text",
text=f"❌ Error: {str(e)}\n\nSupported platforms: claude, gemini, openai, markdown"
)]
# Validation: Must provide exactly one of config_name or config_path
if not config_name and not config_path:
@@ -397,73 +625,118 @@ async def install_skill_tool(args: dict) -> List[TextContent]:
# ===== PHASE 4: Package Skill =====
phase_num = "4/5" if config_name else "3/4"
output_lines.append(f"📦 PHASE {phase_num}: Package Skill")
output_lines.append(f"📦 PHASE {phase_num}: Package Skill for {adaptor.PLATFORM_NAME}")
output_lines.append("-" * 70)
output_lines.append(f"Skill directory: {workflow_state['skill_dir']}")
output_lines.append(f"Target platform: {adaptor.PLATFORM_NAME}")
output_lines.append("")
if not dry_run:
# Call package_skill_tool (auto_upload=False, we handle upload separately)
# Call package_skill_tool with target
package_result = await package_skill_tool({
"skill_dir": workflow_state['skill_dir'],
"auto_upload": False # We handle upload in next phase
"auto_upload": False, # We handle upload in next phase
"target": target
})
package_output = package_result[0].text
output_lines.append(package_output)
output_lines.append("")
# Extract zip path from output
# Expected format: "Saved to: output/react.zip"
match = re.search(r"Saved to:\s*(.+\.zip)", package_output)
# Extract package path from output (supports .zip and .tar.gz)
# Expected format: "Saved to: output/react.zip" or "Saved to: output/react-gemini.tar.gz"
match = re.search(r"Saved to:\s*(.+\.(?:zip|tar\.gz))", package_output)
if match:
workflow_state['zip_path'] = match.group(1).strip()
else:
# Fallback: construct zip path
workflow_state['zip_path'] = f"{destination}/{workflow_state['skill_name']}.zip"
# Fallback: construct package path based on platform
if target == 'gemini':
workflow_state['zip_path'] = f"{destination}/{workflow_state['skill_name']}-gemini.tar.gz"
elif target == 'openai':
workflow_state['zip_path'] = f"{destination}/{workflow_state['skill_name']}-openai.zip"
else:
workflow_state['zip_path'] = f"{destination}/{workflow_state['skill_name']}.zip"
workflow_state['phases_completed'].append('package_skill')
else:
output_lines.append(" [DRY RUN] Would package to .zip file")
workflow_state['zip_path'] = f"{destination}/{workflow_state['skill_name']}.zip"
# Dry run - show expected package format
if target == 'gemini':
pkg_ext = "tar.gz"
pkg_file = f"{destination}/{workflow_state['skill_name']}-gemini.tar.gz"
elif target == 'openai':
pkg_ext = "zip"
pkg_file = f"{destination}/{workflow_state['skill_name']}-openai.zip"
else:
pkg_ext = "zip"
pkg_file = f"{destination}/{workflow_state['skill_name']}.zip"
output_lines.append(f" [DRY RUN] Would package to {pkg_ext} file for {adaptor.PLATFORM_NAME}")
workflow_state['zip_path'] = pkg_file
output_lines.append("")
# ===== PHASE 5: Upload (Optional) =====
if auto_upload:
phase_num = "5/5" if config_name else "4/4"
output_lines.append(f"📤 PHASE {phase_num}: Upload to Claude")
output_lines.append(f"📤 PHASE {phase_num}: Upload to {adaptor.PLATFORM_NAME}")
output_lines.append("-" * 70)
output_lines.append(f"Zip file: {workflow_state['zip_path']}")
output_lines.append(f"Package file: {workflow_state['zip_path']}")
output_lines.append("")
# Check for API key
has_api_key = os.environ.get('ANTHROPIC_API_KEY', '').strip()
# Check for platform-specific API key
env_var_name = adaptor.get_env_var_name()
has_api_key = os.environ.get(env_var_name, '').strip()
if not dry_run:
if has_api_key:
# Call upload_skill_tool
upload_result = await upload_skill_tool({
"skill_zip": workflow_state['zip_path']
})
# Upload not supported for markdown platform
if target == 'markdown':
output_lines.append("⚠️ Markdown export does not support upload")
output_lines.append(" Package has been created - use manually")
else:
# Call upload_skill_tool with target
upload_result = await upload_skill_tool({
"skill_zip": workflow_state['zip_path'],
"target": target
})
upload_output = upload_result[0].text
output_lines.append(upload_output)
upload_output = upload_result[0].text
output_lines.append(upload_output)
workflow_state['phases_completed'].append('upload_skill')
workflow_state['phases_completed'].append('upload_skill')
else:
output_lines.append("⚠️ ANTHROPIC_API_KEY not set - skipping upload")
# Platform-specific instructions for missing API key
output_lines.append(f"⚠️ {env_var_name} not set - skipping upload")
output_lines.append("")
output_lines.append("To enable automatic upload:")
output_lines.append(" 1. Get API key from https://console.anthropic.com/")
output_lines.append(" 2. Set: export ANTHROPIC_API_KEY=sk-ant-...")
output_lines.append("")
output_lines.append("📤 Manual upload:")
output_lines.append(" 1. Go to https://claude.ai/skills")
output_lines.append(" 2. Click 'Upload Skill'")
output_lines.append(f" 3. Select: {workflow_state['zip_path']}")
if target == 'claude':
output_lines.append(" 1. Get API key from https://console.anthropic.com/")
output_lines.append(" 2. Set: export ANTHROPIC_API_KEY=sk-ant-...")
output_lines.append("")
output_lines.append("📤 Manual upload:")
output_lines.append(" 1. Go to https://claude.ai/skills")
output_lines.append(" 2. Click 'Upload Skill'")
output_lines.append(f" 3. Select: {workflow_state['zip_path']}")
elif target == 'gemini':
output_lines.append(" 1. Get API key from https://aistudio.google.com/")
output_lines.append(" 2. Set: export GOOGLE_API_KEY=AIza...")
output_lines.append("")
output_lines.append("📤 Manual upload:")
output_lines.append(" 1. Go to https://aistudio.google.com/")
output_lines.append(f" 2. Upload package: {workflow_state['zip_path']}")
elif target == 'openai':
output_lines.append(" 1. Get API key from https://platform.openai.com/")
output_lines.append(" 2. Set: export OPENAI_API_KEY=sk-proj-...")
output_lines.append("")
output_lines.append("📤 Manual upload:")
output_lines.append(" 1. Use OpenAI Assistants API")
output_lines.append(f" 2. Upload package: {workflow_state['zip_path']}")
elif target == 'markdown':
output_lines.append(" (No API key needed - markdown is export only)")
output_lines.append(f" Package created: {workflow_state['zip_path']}")
else:
output_lines.append(" [DRY RUN] Would upload to Claude (if API key set)")
output_lines.append(f" [DRY RUN] Would upload to {adaptor.PLATFORM_NAME} (if API key set)")
output_lines.append("")
@@ -485,14 +758,22 @@ async def install_skill_tool(args: dict) -> List[TextContent]:
output_lines.append(f" Skill package: {workflow_state['zip_path']}")
output_lines.append("")
if auto_upload and has_api_key:
output_lines.append("🎉 Your skill is now available in Claude!")
output_lines.append(" Go to https://claude.ai/skills to use it")
if auto_upload and has_api_key and target != 'markdown':
# Platform-specific success message
if target == 'claude':
output_lines.append("🎉 Your skill is now available in Claude!")
output_lines.append(" Go to https://claude.ai/skills to use it")
elif target == 'gemini':
output_lines.append("🎉 Your skill is now available in Gemini!")
output_lines.append(" Go to https://aistudio.google.com/ to use it")
elif target == 'openai':
output_lines.append("🎉 Your assistant is now available in OpenAI!")
output_lines.append(" Go to https://platform.openai.com/assistants/ to use it")
elif auto_upload:
output_lines.append("📝 Manual upload required (see instructions above)")
else:
output_lines.append("📤 To upload:")
output_lines.append(" skill-seekers upload " + workflow_state['zip_path'])
output_lines.append(f" skill-seekers upload {workflow_state['zip_path']} --target {target}")
else:
output_lines.append("This was a dry run. No actions were taken.")
output_lines.append("")

7
src/skill_seekers/mcp/tools/scraping_tools.py
View File

@@ -19,7 +19,12 @@ from typing import Any, List
try:
from mcp.types import TextContent
except ImportError:
TextContent = None # Graceful degradation for testing
# Graceful degradation: Create a simple fallback class for testing
class TextContent:
"""Fallback TextContent for when MCP is not installed"""
def __init__(self, type: str, text: str):
self.type = type
self.text = text
# Path to CLI tools
CLI_DIR = Path(__file__).parent.parent.parent / "cli"

7
src/skill_seekers/mcp/tools/source_tools.py
View File

@@ -20,7 +20,12 @@ try:
from mcp.types import TextContent
MCP_AVAILABLE = True
except ImportError:
TextContent = None
# Graceful degradation: Create a simple fallback class for testing
class TextContent:
"""Fallback TextContent for when MCP is not installed"""
def __init__(self, type: str, text: str):
self.type = type
self.text = text
MCP_AVAILABLE = False
import httpx

24
src/skill_seekers/mcp/tools/splitting_tools.py
View File

@@ -13,7 +13,12 @@ from typing import Any, List
try:
from mcp.types import TextContent
except ImportError:
TextContent = None
# Graceful degradation: Create a simple fallback class for testing
class TextContent:
"""Fallback TextContent for when MCP is not installed"""
def __init__(self, type: str, text: str):
self.type = type
self.text = text
# Path to CLI tools
CLI_DIR = Path(__file__).parent.parent.parent / "cli"
@@ -94,17 +99,22 @@ def run_subprocess_with_streaming(cmd, timeout=None):
async def split_config(args: dict) -> List[TextContent]:
"""
Split large documentation config into multiple focused skills.
Split large configs into multiple focused skills.
Supports both documentation and unified (multi-source) configs:
- Documentation configs: Split by categories, size, or create router skills
- Unified configs: Split by source type (documentation, github, pdf)
For large documentation sites (10K+ pages), this tool splits the config into
multiple smaller configs based on categories, size, or custom strategy. This
improves performance and makes individual skills more focused.
multiple smaller configs. For unified configs with multiple sources, splits
into separate configs per source type.
Args:
args: Dictionary containing:
- config_path (str): Path to config JSON file (e.g., configs/godot.json)
- strategy (str, optional): Split strategy: auto, none, category, router, size (default: auto)
- target_pages (int, optional): Target pages per skill (default: 5000)
- config_path (str): Path to config JSON file (e.g., configs/godot.json or configs/react_unified.json)
- strategy (str, optional): Split strategy: auto, none, source, category, router, size (default: auto)
'source' strategy is for unified configs only
- target_pages (int, optional): Target pages per skill for doc configs (default: 5000)
- dry_run (bool, optional): Preview without saving files (default: False)
Returns:

1
tests/test_adaptors/__init__.py Normal file
View File

@@ -0,0 +1 @@
# Adaptor tests package

555
tests/test_adaptors/test_adaptors_e2e.py Normal file
View File

@@ -0,0 +1,555 @@
#!/usr/bin/env python3
"""
End-to-End Tests for Multi-LLM Adaptors
Tests complete workflows without real API uploads:
- Scrape → Package → Verify for all platforms
- Same scraped data works for all platforms
- Package structure validation
- Enhancement workflow (mocked)
"""
import unittest
import tempfile
import zipfile
import tarfile
import json
from pathlib import Path
from skill_seekers.cli.adaptors import get_adaptor, list_platforms
from skill_seekers.cli.adaptors.base import SkillMetadata
class TestAdaptorsE2E(unittest.TestCase):
"""End-to-end tests for all platform adaptors"""
def setUp(self):
"""Set up test environment with sample skill directory"""
self.temp_dir = tempfile.TemporaryDirectory()
self.skill_dir = Path(self.temp_dir.name) / "test-skill"
self.skill_dir.mkdir()
# Create realistic skill structure
self._create_sample_skill()
self.output_dir = Path(self.temp_dir.name) / "output"
self.output_dir.mkdir()
def tearDown(self):
"""Clean up temporary directory"""
self.temp_dir.cleanup()
def _create_sample_skill(self):
"""Create a sample skill directory with realistic content"""
# Create SKILL.md
skill_md_content = """# React Framework
React is a JavaScript library for building user interfaces.
## Quick Reference
```javascript
// Create a component
function Welcome(props) {
return <h1>Hello, {props.name}</h1>;
}
```
## Key Concepts
- Components
- Props
- State
- Hooks
"""
(self.skill_dir / "SKILL.md").write_text(skill_md_content)
# Create references directory
refs_dir = self.skill_dir / "references"
refs_dir.mkdir()
# Create sample reference files
(refs_dir / "getting_started.md").write_text("""# Getting Started
Install React:
```bash
npm install react
```
Create your first component:
```javascript
function App() {
return <div>Hello World</div>;
}
```
""")
(refs_dir / "hooks.md").write_text("""# React Hooks
## useState
```javascript
const [count, setCount] = useState(0);
```
## useEffect
```javascript
useEffect(() => {
document.title = `Count: ${count}`;
}, [count]);
```
""")
(refs_dir / "components.md").write_text("""# Components
## Functional Components
```javascript
function Greeting({ name }) {
return <h1>Hello {name}</h1>;
}
```
## Props
Pass data to components:
```javascript
<Greeting name="Alice" />
```
""")
# Create empty scripts and assets directories
(self.skill_dir / "scripts").mkdir()
(self.skill_dir / "assets").mkdir()
def test_e2e_all_platforms_from_same_skill(self):
"""Test that all platforms can package the same skill"""
platforms = ['claude', 'gemini', 'openai', 'markdown']
packages = {}
for platform in platforms:
adaptor = get_adaptor(platform)
# Package for this platform
package_path = adaptor.package(self.skill_dir, self.output_dir)
# Verify package was created
self.assertTrue(package_path.exists(),
f"Package not created for {platform}")
# Store for later verification
packages[platform] = package_path
# Verify all packages were created
self.assertEqual(len(packages), 4)
# Verify correct extensions
self.assertTrue(str(packages['claude']).endswith('.zip'))
self.assertTrue(str(packages['gemini']).endswith('.tar.gz'))
self.assertTrue(str(packages['openai']).endswith('.zip'))
self.assertTrue(str(packages['markdown']).endswith('.zip'))
def test_e2e_claude_workflow(self):
"""Test complete Claude workflow: package + verify structure"""
adaptor = get_adaptor('claude')
# Package
package_path = adaptor.package(self.skill_dir, self.output_dir)
# Verify package
self.assertTrue(package_path.exists())
self.assertTrue(str(package_path).endswith('.zip'))
# Verify contents
with zipfile.ZipFile(package_path, 'r') as zf:
names = zf.namelist()
# Should have SKILL.md
self.assertIn('SKILL.md', names)
# Should have references
self.assertTrue(any('references/' in name for name in names))
# Verify SKILL.md content (should have YAML frontmatter)
skill_content = zf.read('SKILL.md').decode('utf-8')
# Claude uses YAML frontmatter (but current implementation doesn't add it in package)
# Just verify content exists
self.assertGreater(len(skill_content), 0)
def test_e2e_gemini_workflow(self):
"""Test complete Gemini workflow: package + verify structure"""
adaptor = get_adaptor('gemini')
# Package
package_path = adaptor.package(self.skill_dir, self.output_dir)
# Verify package
self.assertTrue(package_path.exists())
self.assertTrue(str(package_path).endswith('.tar.gz'))
# Verify contents
with tarfile.open(package_path, 'r:gz') as tar:
names = tar.getnames()
# Should have system_instructions.md (not SKILL.md)
self.assertIn('system_instructions.md', names)
# Should have references
self.assertTrue(any('references/' in name for name in names))
# Should have metadata
self.assertIn('gemini_metadata.json', names)
# Verify metadata content
metadata_member = tar.getmember('gemini_metadata.json')
metadata_file = tar.extractfile(metadata_member)
metadata = json.loads(metadata_file.read().decode('utf-8'))
self.assertEqual(metadata['platform'], 'gemini')
self.assertEqual(metadata['name'], 'test-skill')
self.assertIn('created_with', metadata)
def test_e2e_openai_workflow(self):
"""Test complete OpenAI workflow: package + verify structure"""
adaptor = get_adaptor('openai')
# Package
package_path = adaptor.package(self.skill_dir, self.output_dir)
# Verify package
self.assertTrue(package_path.exists())
self.assertTrue(str(package_path).endswith('.zip'))
# Verify contents
with zipfile.ZipFile(package_path, 'r') as zf:
names = zf.namelist()
# Should have assistant_instructions.txt
self.assertIn('assistant_instructions.txt', names)
# Should have vector store files
self.assertTrue(any('vector_store_files/' in name for name in names))
# Should have metadata
self.assertIn('openai_metadata.json', names)
# Verify metadata content
metadata_content = zf.read('openai_metadata.json').decode('utf-8')
metadata = json.loads(metadata_content)
self.assertEqual(metadata['platform'], 'openai')
self.assertEqual(metadata['name'], 'test-skill')
self.assertEqual(metadata['model'], 'gpt-4o')
self.assertIn('file_search', metadata['tools'])
def test_e2e_markdown_workflow(self):
"""Test complete Markdown workflow: package + verify structure"""
adaptor = get_adaptor('markdown')
# Package
package_path = adaptor.package(self.skill_dir, self.output_dir)
# Verify package
self.assertTrue(package_path.exists())
self.assertTrue(str(package_path).endswith('.zip'))
# Verify contents
with zipfile.ZipFile(package_path, 'r') as zf:
names = zf.namelist()
# Should have README.md
self.assertIn('README.md', names)
# Should have DOCUMENTATION.md (combined)
self.assertIn('DOCUMENTATION.md', names)
# Should have references
self.assertTrue(any('references/' in name for name in names))
# Should have metadata
self.assertIn('metadata.json', names)
# Verify combined documentation
doc_content = zf.read('DOCUMENTATION.md').decode('utf-8')
# Should contain content from all references
self.assertIn('Getting Started', doc_content)
self.assertIn('React Hooks', doc_content)
self.assertIn('Components', doc_content)
def test_e2e_package_format_validation(self):
"""Test that each platform creates correct package format"""
test_cases = [
('claude', '.zip'),
('gemini', '.tar.gz'),
('openai', '.zip'),
('markdown', '.zip')
]
for platform, expected_ext in test_cases:
adaptor = get_adaptor(platform)
package_path = adaptor.package(self.skill_dir, self.output_dir)
# Verify extension
if expected_ext == '.tar.gz':
self.assertTrue(str(package_path).endswith('.tar.gz'),
f"{platform} should create .tar.gz file")
else:
self.assertTrue(str(package_path).endswith('.zip'),
f"{platform} should create .zip file")
def test_e2e_package_filename_convention(self):
"""Test that package filenames follow convention"""
test_cases = [
('claude', 'test-skill.zip'),
('gemini', 'test-skill-gemini.tar.gz'),
('openai', 'test-skill-openai.zip'),
('markdown', 'test-skill-markdown.zip')
]
for platform, expected_name in test_cases:
adaptor = get_adaptor(platform)
package_path = adaptor.package(self.skill_dir, self.output_dir)
# Verify filename
self.assertEqual(package_path.name, expected_name,
f"{platform} package filename incorrect")
def test_e2e_all_platforms_preserve_references(self):
"""Test that all platforms preserve reference files"""
ref_files = ['getting_started.md', 'hooks.md', 'components.md']
for platform in ['claude', 'gemini', 'openai', 'markdown']:
adaptor = get_adaptor(platform)
package_path = adaptor.package(self.skill_dir, self.output_dir)
# Check references are preserved
if platform == 'gemini':
with tarfile.open(package_path, 'r:gz') as tar:
names = tar.getnames()
for ref_file in ref_files:
self.assertTrue(
any(ref_file in name for name in names),
f"{platform}: {ref_file} not found in package"
)
else:
with zipfile.ZipFile(package_path, 'r') as zf:
names = zf.namelist()
for ref_file in ref_files:
# OpenAI moves to vector_store_files/
if platform == 'openai':
self.assertTrue(
any(f'vector_store_files/{ref_file}' in name for name in names),
f"{platform}: {ref_file} not found in vector_store_files/"
)
else:
self.assertTrue(
any(ref_file in name for name in names),
f"{platform}: {ref_file} not found in package"
)
def test_e2e_metadata_consistency(self):
"""Test that metadata is consistent across platforms"""
platforms_with_metadata = ['gemini', 'openai', 'markdown']
for platform in platforms_with_metadata:
adaptor = get_adaptor(platform)
package_path = adaptor.package(self.skill_dir, self.output_dir)
# Extract and verify metadata
if platform == 'gemini':
with tarfile.open(package_path, 'r:gz') as tar:
metadata_member = tar.getmember('gemini_metadata.json')
metadata_file = tar.extractfile(metadata_member)
metadata = json.loads(metadata_file.read().decode('utf-8'))
else:
with zipfile.ZipFile(package_path, 'r') as zf:
metadata_filename = f'{platform}_metadata.json' if platform == 'openai' else 'metadata.json'
metadata_content = zf.read(metadata_filename).decode('utf-8')
metadata = json.loads(metadata_content)
# Verify required fields
self.assertEqual(metadata['platform'], platform)
self.assertEqual(metadata['name'], 'test-skill')
self.assertIn('created_with', metadata)
def test_e2e_format_skill_md_differences(self):
"""Test that each platform formats SKILL.md differently"""
metadata = SkillMetadata(
name="test-skill",
description="Test skill for E2E testing"
)
formats = {}
for platform in ['claude', 'gemini', 'openai', 'markdown']:
adaptor = get_adaptor(platform)
formatted = adaptor.format_skill_md(self.skill_dir, metadata)
formats[platform] = formatted
# Claude should have YAML frontmatter
self.assertTrue(formats['claude'].startswith('---'))
# Gemini and Markdown should NOT have YAML frontmatter
self.assertFalse(formats['gemini'].startswith('---'))
self.assertFalse(formats['markdown'].startswith('---'))
# All should contain content from existing SKILL.md (React Framework)
for platform, formatted in formats.items():
# Check for content from existing SKILL.md
self.assertIn('react', formatted.lower(),
f"{platform} should contain skill content")
# All should have non-empty content
self.assertGreater(len(formatted), 100,
f"{platform} should have substantial content")
def test_e2e_upload_without_api_key(self):
"""Test upload behavior without API keys (should fail gracefully)"""
platforms_with_upload = ['claude', 'gemini', 'openai']
for platform in platforms_with_upload:
adaptor = get_adaptor(platform)
package_path = adaptor.package(self.skill_dir, self.output_dir)
# Try upload without API key
result = adaptor.upload(package_path, '')
# Should fail
self.assertFalse(result['success'],
f"{platform} should fail without API key")
self.assertIsNone(result['skill_id'])
self.assertIn('message', result)
def test_e2e_markdown_no_upload_support(self):
"""Test that markdown adaptor doesn't support upload"""
adaptor = get_adaptor('markdown')
package_path = adaptor.package(self.skill_dir, self.output_dir)
# Try upload (should return informative message)
result = adaptor.upload(package_path, 'not-used')
# Should indicate no upload support
self.assertFalse(result['success'])
self.assertIsNone(result['skill_id'])
self.assertIn('not support', result['message'].lower())
# URL should point to local file
self.assertIn(str(package_path.absolute()), result['url'])
class TestAdaptorsWorkflowIntegration(unittest.TestCase):
"""Integration tests for common workflow patterns"""
def test_workflow_export_to_all_platforms(self):
"""Test exporting same skill to all platforms"""
with tempfile.TemporaryDirectory() as temp_dir:
skill_dir = Path(temp_dir) / "react"
skill_dir.mkdir()
# Create minimal skill
(skill_dir / "SKILL.md").write_text("# React\n\nReact documentation")
refs_dir = skill_dir / "references"
refs_dir.mkdir()
(refs_dir / "guide.md").write_text("# Guide\n\nContent")
output_dir = Path(temp_dir) / "output"
output_dir.mkdir()
# Export to all platforms
packages = {}
for platform in ['claude', 'gemini', 'openai', 'markdown']:
adaptor = get_adaptor(platform)
package_path = adaptor.package(skill_dir, output_dir)
packages[platform] = package_path
# Verify all packages exist and are distinct
self.assertEqual(len(packages), 4)
self.assertEqual(len(set(packages.values())), 4) # All unique
def test_workflow_package_to_custom_path(self):
"""Test packaging to custom output paths"""
with tempfile.TemporaryDirectory() as temp_dir:
skill_dir = Path(temp_dir) / "skill"
skill_dir.mkdir()
(skill_dir / "SKILL.md").write_text("# Test")
(skill_dir / "references").mkdir()
# Test custom output paths
custom_output = Path(temp_dir) / "custom" / "my-package.zip"
adaptor = get_adaptor('claude')
package_path = adaptor.package(skill_dir, custom_output)
# Should respect custom path
self.assertTrue(package_path.exists())
self.assertTrue('my-package' in package_path.name or package_path.parent.name == 'custom')
def test_workflow_api_key_validation(self):
"""Test API key validation for each platform"""
test_cases = [
('claude', 'sk-ant-test123', True),
('claude', 'invalid-key', False),
('gemini', 'AIzaSyTest123', True),
('gemini', 'sk-ant-test', False),
('openai', 'sk-proj-test123', True),
('openai', 'sk-test123', True),
('openai', 'AIzaSy123', False),
('markdown', 'any-key', False), # Never uses keys
]
for platform, api_key, expected in test_cases:
adaptor = get_adaptor(platform)
result = adaptor.validate_api_key(api_key)
self.assertEqual(result, expected,
f"{platform}: validate_api_key('{api_key}') should be {expected}")
class TestAdaptorsErrorHandling(unittest.TestCase):
"""Test error handling in adaptors"""
def test_error_invalid_skill_directory(self):
"""Test packaging with invalid skill directory"""
with tempfile.TemporaryDirectory() as temp_dir:
# Empty directory (no SKILL.md)
empty_dir = Path(temp_dir) / "empty"
empty_dir.mkdir()
output_dir = Path(temp_dir) / "output"
output_dir.mkdir()
# Should handle gracefully (may create package but with empty content)
for platform in ['claude', 'gemini', 'openai', 'markdown']:
adaptor = get_adaptor(platform)
# Should not crash
try:
package_path = adaptor.package(empty_dir, output_dir)
# Package may be created but should exist
self.assertTrue(package_path.exists())
except Exception as e:
# If it raises, should be clear error
self.assertIn('SKILL.md', str(e).lower() or 'reference' in str(e).lower())
def test_error_upload_nonexistent_file(self):
"""Test upload with nonexistent file"""
for platform in ['claude', 'gemini', 'openai']:
adaptor = get_adaptor(platform)
result = adaptor.upload(Path('/nonexistent/file.zip'), 'test-key')
self.assertFalse(result['success'])
self.assertIn('not found', result['message'].lower())
def test_error_upload_wrong_format(self):
"""Test upload with wrong file format"""
with tempfile.NamedTemporaryFile(suffix='.txt') as tmp:
# Try uploading .txt file
for platform in ['claude', 'gemini', 'openai']:
adaptor = get_adaptor(platform)
result = adaptor.upload(Path(tmp.name), 'test-key')
self.assertFalse(result['success'])
if __name__ == '__main__':
unittest.main()

122
tests/test_adaptors/test_base.py Normal file
View File

@@ -0,0 +1,122 @@
#!/usr/bin/env python3
"""
Tests for base adaptor and registry
"""
import unittest
from pathlib import Path
from skill_seekers.cli.adaptors import (
get_adaptor,
list_platforms,
is_platform_available,
SkillAdaptor,
SkillMetadata,
ADAPTORS
)
class TestSkillMetadata(unittest.TestCase):
"""Test SkillMetadata dataclass"""
def test_basic_metadata(self):
"""Test basic metadata creation"""
metadata = SkillMetadata(
name="test-skill",
description="Test skill description"
)
self.assertEqual(metadata.name, "test-skill")
self.assertEqual(metadata.description, "Test skill description")
self.assertEqual(metadata.version, "1.0.0") # default
self.assertIsNone(metadata.author) # default
self.assertEqual(metadata.tags, []) # default
def test_full_metadata(self):
"""Test metadata with all fields"""
metadata = SkillMetadata(
name="react",
description="React documentation",
version="2.0.0",
author="Test Author",
tags=["react", "javascript", "web"]
)
self.assertEqual(metadata.name, "react")
self.assertEqual(metadata.description, "React documentation")
self.assertEqual(metadata.version, "2.0.0")
self.assertEqual(metadata.author, "Test Author")
self.assertEqual(metadata.tags, ["react", "javascript", "web"])
class TestAdaptorRegistry(unittest.TestCase):
"""Test adaptor registry and factory"""
def test_list_platforms(self):
"""Test listing available platforms"""
platforms = list_platforms()
self.assertIsInstance(platforms, list)
# Claude should always be available
self.assertIn('claude', platforms)
def test_is_platform_available(self):
"""Test checking platform availability"""
# Claude should be available
self.assertTrue(is_platform_available('claude'))
# Unknown platform should not be available
self.assertFalse(is_platform_available('unknown_platform'))
def test_get_adaptor_claude(self):
"""Test getting Claude adaptor"""
adaptor = get_adaptor('claude')
self.assertIsInstance(adaptor, SkillAdaptor)
self.assertEqual(adaptor.PLATFORM, 'claude')
self.assertEqual(adaptor.PLATFORM_NAME, 'Claude AI (Anthropic)')
def test_get_adaptor_invalid(self):
"""Test getting invalid adaptor raises error"""
with self.assertRaises(ValueError) as ctx:
get_adaptor('invalid_platform')
error_msg = str(ctx.exception)
self.assertIn('invalid_platform', error_msg)
self.assertIn('not supported', error_msg)
def test_get_adaptor_with_config(self):
"""Test getting adaptor with custom config"""
config = {'custom_setting': 'value'}
adaptor = get_adaptor('claude', config)
self.assertEqual(adaptor.config, config)
class TestBaseAdaptorInterface(unittest.TestCase):
"""Test base adaptor interface methods"""
def setUp(self):
"""Set up test adaptor"""
self.adaptor = get_adaptor('claude')
def test_validate_api_key_default(self):
"""Test default API key validation"""
# Claude adaptor overrides this
self.assertTrue(self.adaptor.validate_api_key('sk-ant-test123'))
self.assertFalse(self.adaptor.validate_api_key('invalid'))
def test_get_env_var_name(self):
"""Test environment variable name"""
env_var = self.adaptor.get_env_var_name()
self.assertEqual(env_var, 'ANTHROPIC_API_KEY')
def test_supports_enhancement(self):
"""Test enhancement support check"""
# Claude supports enhancement
self.assertTrue(self.adaptor.supports_enhancement())
if __name__ == '__main__':
unittest.main()

322
tests/test_adaptors/test_claude_adaptor.py Normal file
View File

@@ -0,0 +1,322 @@
#!/usr/bin/env python3
"""
Tests for Claude adaptor (refactored from existing code)
"""
import unittest
from unittest.mock import patch, MagicMock, mock_open
from pathlib import Path
import tempfile
import zipfile
import json
from skill_seekers.cli.adaptors import get_adaptor
from skill_seekers.cli.adaptors.base import SkillMetadata
class TestClaudeAdaptor(unittest.TestCase):
"""Test Claude adaptor functionality"""
def setUp(self):
"""Set up test adaptor"""
self.adaptor = get_adaptor('claude')
def test_platform_info(self):
"""Test platform identifiers"""
self.assertEqual(self.adaptor.PLATFORM, 'claude')
self.assertIn('Claude', self.adaptor.PLATFORM_NAME)
self.assertIsNotNone(self.adaptor.DEFAULT_API_ENDPOINT)
self.assertIn('anthropic.com', self.adaptor.DEFAULT_API_ENDPOINT)
def test_validate_api_key_valid(self):
"""Test valid Claude API keys"""
self.assertTrue(self.adaptor.validate_api_key('sk-ant-abc123'))
self.assertTrue(self.adaptor.validate_api_key('sk-ant-api03-test'))
self.assertTrue(self.adaptor.validate_api_key(' sk-ant-test ')) # with whitespace
def test_validate_api_key_invalid(self):
"""Test invalid API keys"""
self.assertFalse(self.adaptor.validate_api_key('AIzaSyABC123')) # Gemini key
self.assertFalse(self.adaptor.validate_api_key('sk-proj-123')) # OpenAI key (proj)
self.assertFalse(self.adaptor.validate_api_key('invalid'))
self.assertFalse(self.adaptor.validate_api_key(''))
self.assertFalse(self.adaptor.validate_api_key('sk-test')) # Missing 'ant'
def test_get_env_var_name(self):
"""Test environment variable name"""
self.assertEqual(self.adaptor.get_env_var_name(), 'ANTHROPIC_API_KEY')
def test_supports_enhancement(self):
"""Test enhancement support"""
self.assertTrue(self.adaptor.supports_enhancement())
def test_format_skill_md_with_frontmatter(self):
"""Test that Claude format includes YAML frontmatter"""
with tempfile.TemporaryDirectory() as temp_dir:
skill_dir = Path(temp_dir)
# Create minimal skill structure
(skill_dir / "references").mkdir()
(skill_dir / "references" / "test.md").write_text("# Test content")
metadata = SkillMetadata(
name="test-skill",
description="Test skill description",
version="1.0.0"
)
formatted = self.adaptor.format_skill_md(skill_dir, metadata)
# Should start with YAML frontmatter
self.assertTrue(formatted.startswith('---'))
# Should contain metadata fields
self.assertIn('name:', formatted)
self.assertIn('description:', formatted)
self.assertIn('version:', formatted)
# Should have closing delimiter
self.assertTrue('---' in formatted[3:]) # Second occurrence
def test_format_skill_md_with_existing_content(self):
"""Test that existing SKILL.md content is preserved"""
with tempfile.TemporaryDirectory() as temp_dir:
skill_dir = Path(temp_dir)
# Create SKILL.md with existing content
existing_content = """# Existing Documentation
This is existing skill content that should be preserved.
## Features
- Feature 1
- Feature 2
"""
(skill_dir / "SKILL.md").write_text(existing_content)
(skill_dir / "references").mkdir()
metadata = SkillMetadata(
name="test-skill",
description="Test description"
)
formatted = self.adaptor.format_skill_md(skill_dir, metadata)
# Should contain existing content
self.assertIn('Existing Documentation', formatted)
self.assertIn('Feature 1', formatted)
def test_package_creates_zip(self):
"""Test that package creates ZIP file with correct structure"""
with tempfile.TemporaryDirectory() as temp_dir:
skill_dir = Path(temp_dir) / "test-skill"
skill_dir.mkdir()
# Create minimal skill structure
(skill_dir / "SKILL.md").write_text("# Test Skill")
(skill_dir / "references").mkdir()
(skill_dir / "references" / "test.md").write_text("# Reference")
(skill_dir / "scripts").mkdir()
(skill_dir / "assets").mkdir()
output_dir = Path(temp_dir) / "output"
output_dir.mkdir()
# Package skill
package_path = self.adaptor.package(skill_dir, output_dir)
# Verify package was created
self.assertTrue(package_path.exists())
self.assertTrue(str(package_path).endswith('.zip'))
# Should NOT have platform suffix (Claude is default)
self.assertEqual(package_path.name, 'test-skill.zip')
# Verify package contents
with zipfile.ZipFile(package_path, 'r') as zf:
names = zf.namelist()
self.assertIn('SKILL.md', names)
self.assertTrue(any('references/' in name for name in names))
def test_package_excludes_backup_files(self):
"""Test that backup files are excluded from package"""
with tempfile.TemporaryDirectory() as temp_dir:
skill_dir = Path(temp_dir) / "test-skill"
skill_dir.mkdir()
# Create skill with backup file
(skill_dir / "SKILL.md").write_text("# Test")
(skill_dir / "SKILL.md.backup").write_text("# Old version")
(skill_dir / "references").mkdir()
output_dir = Path(temp_dir) / "output"
output_dir.mkdir()
package_path = self.adaptor.package(skill_dir, output_dir)
# Verify backup is excluded
with zipfile.ZipFile(package_path, 'r') as zf:
names = zf.namelist()
self.assertNotIn('SKILL.md.backup', names)
@patch('requests.post')
def test_upload_success(self, mock_post):
"""Test successful upload to Claude"""
with tempfile.NamedTemporaryFile(suffix='.zip') as tmp:
# Mock successful response
mock_response = MagicMock()
mock_response.status_code = 200
mock_response.json.return_value = {'id': 'skill_abc123'}
mock_post.return_value = mock_response
result = self.adaptor.upload(Path(tmp.name), 'sk-ant-test123')
self.assertTrue(result['success'])
self.assertEqual(result['skill_id'], 'skill_abc123')
self.assertIn('claude.ai', result['url'])
# Verify correct API call
mock_post.assert_called_once()
call_args = mock_post.call_args
self.assertIn('anthropic.com', call_args[0][0])
self.assertEqual(call_args[1]['headers']['x-api-key'], 'sk-ant-test123')
@patch('requests.post')
def test_upload_failure(self, mock_post):
"""Test failed upload to Claude"""
with tempfile.NamedTemporaryFile(suffix='.zip') as tmp:
# Mock failed response
mock_response = MagicMock()
mock_response.status_code = 400
mock_response.text = 'Invalid skill format'
mock_post.return_value = mock_response
result = self.adaptor.upload(Path(tmp.name), 'sk-ant-test123')
self.assertFalse(result['success'])
self.assertIsNone(result['skill_id'])
self.assertIn('Invalid skill format', result['message'])
def test_upload_invalid_file(self):
"""Test upload with invalid file"""
result = self.adaptor.upload(Path('/nonexistent/file.zip'), 'sk-ant-test123')
self.assertFalse(result['success'])
self.assertIn('not found', result['message'].lower())
def test_upload_wrong_format(self):
"""Test upload with wrong file format"""
with tempfile.NamedTemporaryFile(suffix='.tar.gz') as tmp:
result = self.adaptor.upload(Path(tmp.name), 'sk-ant-test123')
self.assertFalse(result['success'])
self.assertIn('not a zip', result['message'].lower())
@unittest.skip("Complex mocking - integration test needed with real API")
def test_enhance_success(self):
"""Test successful enhancement - skipped (needs real API for integration test)"""
pass
def test_package_with_custom_output_path(self):
"""Test packaging to custom output path"""
with tempfile.TemporaryDirectory() as temp_dir:
skill_dir = Path(temp_dir) / "my-skill"
skill_dir.mkdir()
(skill_dir / "SKILL.md").write_text("# Test")
(skill_dir / "references").mkdir()
# Custom output path
custom_output = Path(temp_dir) / "custom" / "my-package.zip"
package_path = self.adaptor.package(skill_dir, custom_output)
self.assertTrue(package_path.exists())
# Should respect custom naming if provided
self.assertTrue('my-package' in package_path.name or package_path.parent.name == 'custom')
def test_package_to_directory(self):
"""Test packaging to directory (should auto-name)"""
with tempfile.TemporaryDirectory() as temp_dir:
skill_dir = Path(temp_dir) / "react"
skill_dir.mkdir()
(skill_dir / "SKILL.md").write_text("# React")
(skill_dir / "references").mkdir()
output_dir = Path(temp_dir) / "output"
output_dir.mkdir()
# Pass directory as output
package_path = self.adaptor.package(skill_dir, output_dir)
self.assertTrue(package_path.exists())
self.assertEqual(package_path.name, 'react.zip')
self.assertEqual(package_path.parent, output_dir)
class TestClaudeAdaptorEdgeCases(unittest.TestCase):
"""Test edge cases and error handling"""
def setUp(self):
"""Set up test adaptor"""
self.adaptor = get_adaptor('claude')
def test_format_with_minimal_metadata(self):
"""Test formatting with only required metadata fields"""
with tempfile.TemporaryDirectory() as temp_dir:
skill_dir = Path(temp_dir)
(skill_dir / "references").mkdir()
metadata = SkillMetadata(
name="minimal",
description="Minimal skill"
# No version, author, tags
)
formatted = self.adaptor.format_skill_md(skill_dir, metadata)
# Should still create valid output
self.assertIn('---', formatted)
self.assertIn('minimal', formatted)
def test_format_with_special_characters_in_name(self):
"""Test formatting with special characters in skill name"""
with tempfile.TemporaryDirectory() as temp_dir:
skill_dir = Path(temp_dir)
(skill_dir / "references").mkdir()
metadata = SkillMetadata(
name="test-skill_v2.0",
description="Skill with special chars"
)
formatted = self.adaptor.format_skill_md(skill_dir, metadata)
# Should handle special characters
self.assertIn('test-skill_v2.0', formatted)
def test_api_key_validation_edge_cases(self):
"""Test API key validation with edge cases"""
# Empty string
self.assertFalse(self.adaptor.validate_api_key(''))
# Only whitespace
self.assertFalse(self.adaptor.validate_api_key(' '))
# Correct prefix but very short
self.assertTrue(self.adaptor.validate_api_key('sk-ant-x'))
# Case sensitive
self.assertFalse(self.adaptor.validate_api_key('SK-ANT-TEST'))
def test_upload_with_network_error(self):
"""Test upload with network errors"""
with tempfile.NamedTemporaryFile(suffix='.zip') as tmp:
with patch('requests.post') as mock_post:
# Simulate network error
mock_post.side_effect = Exception("Network error")
result = self.adaptor.upload(Path(tmp.name), 'sk-ant-test')
self.assertFalse(result['success'])
self.assertIn('Network error', result['message'])
if __name__ == '__main__':
unittest.main()

150
tests/test_adaptors/test_gemini_adaptor.py Normal file
View File

@@ -0,0 +1,150 @@
#!/usr/bin/env python3
"""
Tests for Gemini adaptor
"""
import unittest
from unittest.mock import patch, MagicMock, mock_open
from pathlib import Path
import tempfile
import tarfile
from skill_seekers.cli.adaptors import get_adaptor
from skill_seekers.cli.adaptors.base import SkillMetadata
class TestGeminiAdaptor(unittest.TestCase):
"""Test Gemini adaptor functionality"""
def setUp(self):
"""Set up test adaptor"""
self.adaptor = get_adaptor('gemini')
def test_platform_info(self):
"""Test platform identifiers"""
self.assertEqual(self.adaptor.PLATFORM, 'gemini')
self.assertEqual(self.adaptor.PLATFORM_NAME, 'Google Gemini')
self.assertIsNotNone(self.adaptor.DEFAULT_API_ENDPOINT)
def test_validate_api_key_valid(self):
"""Test valid Google API key"""
self.assertTrue(self.adaptor.validate_api_key('AIzaSyABC123'))
self.assertTrue(self.adaptor.validate_api_key(' AIzaSyTest ')) # with whitespace
def test_validate_api_key_invalid(self):
"""Test invalid API keys"""
self.assertFalse(self.adaptor.validate_api_key('sk-ant-123')) # Claude key
self.assertFalse(self.adaptor.validate_api_key('invalid'))
self.assertFalse(self.adaptor.validate_api_key(''))
def test_get_env_var_name(self):
"""Test environment variable name"""
self.assertEqual(self.adaptor.get_env_var_name(), 'GOOGLE_API_KEY')
def test_supports_enhancement(self):
"""Test enhancement support"""
self.assertTrue(self.adaptor.supports_enhancement())
def test_format_skill_md_no_frontmatter(self):
"""Test that Gemini format has no YAML frontmatter"""
with tempfile.TemporaryDirectory() as temp_dir:
skill_dir = Path(temp_dir)
# Create minimal skill structure
(skill_dir / "references").mkdir()
(skill_dir / "references" / "test.md").write_text("# Test content")
metadata = SkillMetadata(
name="test-skill",
description="Test skill description"
)
formatted = self.adaptor.format_skill_md(skill_dir, metadata)
# Should NOT start with YAML frontmatter
self.assertFalse(formatted.startswith('---'))
# Should contain the content
self.assertIn('test-skill', formatted.lower())
self.assertIn('Test skill description', formatted)
def test_package_creates_targz(self):
"""Test that package creates tar.gz file"""
with tempfile.TemporaryDirectory() as temp_dir:
skill_dir = Path(temp_dir) / "test-skill"
skill_dir.mkdir()
# Create minimal skill structure
(skill_dir / "SKILL.md").write_text("# Test Skill")
(skill_dir / "references").mkdir()
(skill_dir / "references" / "test.md").write_text("# Reference")
output_dir = Path(temp_dir) / "output"
output_dir.mkdir()
# Package skill
package_path = self.adaptor.package(skill_dir, output_dir)
# Verify package was created
self.assertTrue(package_path.exists())
self.assertTrue(str(package_path).endswith('.tar.gz'))
self.assertIn('gemini', package_path.name)
# Verify package contents
with tarfile.open(package_path, 'r:gz') as tar:
names = tar.getnames()
self.assertIn('system_instructions.md', names)
self.assertIn('gemini_metadata.json', names)
# Should have references
self.assertTrue(any('references' in name for name in names))
@unittest.skip("Complex mocking - integration test needed with real API")
def test_upload_success(self):
"""Test successful upload to Gemini - skipped (needs real API for integration test)"""
pass
def test_upload_missing_library(self):
"""Test upload when google-generativeai is not installed"""
with tempfile.NamedTemporaryFile(suffix='.tar.gz') as tmp:
# Simulate missing library by not mocking it
result = self.adaptor.upload(Path(tmp.name), 'AIzaSyTest')
self.assertFalse(result['success'])
self.assertIn('google-generativeai', result['message'])
self.assertIn('not installed', result['message'])
def test_upload_invalid_file(self):
"""Test upload with invalid file"""
result = self.adaptor.upload(Path('/nonexistent/file.tar.gz'), 'AIzaSyTest')
self.assertFalse(result['success'])
self.assertIn('not found', result['message'].lower())
def test_upload_wrong_format(self):
"""Test upload with wrong file format"""
with tempfile.NamedTemporaryFile(suffix='.zip') as tmp:
result = self.adaptor.upload(Path(tmp.name), 'AIzaSyTest')
self.assertFalse(result['success'])
self.assertIn('not a tar.gz', result['message'].lower())
@unittest.skip("Complex mocking - integration test needed with real API")
def test_enhance_success(self):
"""Test successful enhancement - skipped (needs real API for integration test)"""
pass
def test_enhance_missing_library(self):
"""Test enhance when google-generativeai is not installed"""
with tempfile.TemporaryDirectory() as temp_dir:
skill_dir = Path(temp_dir)
refs_dir = skill_dir / "references"
refs_dir.mkdir()
(refs_dir / "test.md").write_text("Test")
# Don't mock the module - it won't be available
success = self.adaptor.enhance(skill_dir, 'AIzaSyTest')
self.assertFalse(success)
if __name__ == '__main__':
unittest.main()

228
tests/test_adaptors/test_markdown_adaptor.py Normal file
View File

@@ -0,0 +1,228 @@
#!/usr/bin/env python3
"""
Tests for Markdown adaptor
"""
import unittest
from pathlib import Path
import tempfile
import zipfile
from skill_seekers.cli.adaptors import get_adaptor
from skill_seekers.cli.adaptors.base import SkillMetadata
class TestMarkdownAdaptor(unittest.TestCase):
"""Test Markdown adaptor functionality"""
def setUp(self):
"""Set up test adaptor"""
self.adaptor = get_adaptor('markdown')
def test_platform_info(self):
"""Test platform identifiers"""
self.assertEqual(self.adaptor.PLATFORM, 'markdown')
self.assertEqual(self.adaptor.PLATFORM_NAME, 'Generic Markdown (Universal)')
self.assertIsNone(self.adaptor.DEFAULT_API_ENDPOINT)
def test_validate_api_key(self):
"""Test that markdown export doesn't use API keys"""
# Any key should return False (no keys needed)
self.assertFalse(self.adaptor.validate_api_key('sk-ant-123'))
self.assertFalse(self.adaptor.validate_api_key('AIzaSyABC123'))
self.assertFalse(self.adaptor.validate_api_key('any-key'))
self.assertFalse(self.adaptor.validate_api_key(''))
def test_get_env_var_name(self):
"""Test environment variable name"""
self.assertEqual(self.adaptor.get_env_var_name(), '')
def test_supports_enhancement(self):
"""Test enhancement support"""
self.assertFalse(self.adaptor.supports_enhancement())
def test_enhance_returns_false(self):
"""Test that enhance always returns False"""
with tempfile.TemporaryDirectory() as temp_dir:
skill_dir = Path(temp_dir)
refs_dir = skill_dir / "references"
refs_dir.mkdir()
(refs_dir / "test.md").write_text("Test content")
success = self.adaptor.enhance(skill_dir, 'not-used')
self.assertFalse(success)
def test_format_skill_md_no_frontmatter(self):
"""Test that markdown format has no YAML frontmatter"""
with tempfile.TemporaryDirectory() as temp_dir:
skill_dir = Path(temp_dir)
# Create minimal skill structure
(skill_dir / "references").mkdir()
(skill_dir / "references" / "test.md").write_text("# Test content")
metadata = SkillMetadata(
name="test-skill",
description="Test skill description"
)
formatted = self.adaptor.format_skill_md(skill_dir, metadata)
# Should NOT start with YAML frontmatter
self.assertFalse(formatted.startswith('---'))
# Should contain the skill name and description
self.assertIn('test-skill', formatted.lower())
self.assertIn('Test skill description', formatted)
def test_package_creates_zip(self):
"""Test that package creates ZIP file with correct structure"""
with tempfile.TemporaryDirectory() as temp_dir:
skill_dir = Path(temp_dir) / "test-skill"
skill_dir.mkdir()
# Create minimal skill structure
(skill_dir / "SKILL.md").write_text("# Test Skill Documentation")
(skill_dir / "references").mkdir()
(skill_dir / "references" / "guide.md").write_text("# User Guide")
(skill_dir / "references" / "api.md").write_text("# API Reference")
output_dir = Path(temp_dir) / "output"
output_dir.mkdir()
# Package skill
package_path = self.adaptor.package(skill_dir, output_dir)
# Verify package was created
self.assertTrue(package_path.exists())
self.assertTrue(str(package_path).endswith('.zip'))
self.assertIn('markdown', package_path.name)
# Verify package contents
with zipfile.ZipFile(package_path, 'r') as zf:
names = zf.namelist()
# Should have README.md (from SKILL.md)
self.assertIn('README.md', names)
# Should have metadata.json
self.assertIn('metadata.json', names)
# Should have DOCUMENTATION.md (combined)
self.assertIn('DOCUMENTATION.md', names)
# Should have reference files
self.assertIn('references/guide.md', names)
self.assertIn('references/api.md', names)
def test_package_readme_content(self):
"""Test that README.md contains SKILL.md content"""
with tempfile.TemporaryDirectory() as temp_dir:
skill_dir = Path(temp_dir) / "test-skill"
skill_dir.mkdir()
skill_md_content = "# Test Skill\n\nThis is test documentation."
(skill_dir / "SKILL.md").write_text(skill_md_content)
(skill_dir / "references").mkdir()
output_dir = Path(temp_dir) / "output"
output_dir.mkdir()
package_path = self.adaptor.package(skill_dir, output_dir)
# Verify README.md content
with zipfile.ZipFile(package_path, 'r') as zf:
readme_content = zf.read('README.md').decode('utf-8')
self.assertEqual(readme_content, skill_md_content)
def test_package_combined_documentation(self):
"""Test that DOCUMENTATION.md combines all references"""
with tempfile.TemporaryDirectory() as temp_dir:
skill_dir = Path(temp_dir) / "test-skill"
skill_dir.mkdir()
# Create SKILL.md
(skill_dir / "SKILL.md").write_text("# Main Skill")
# Create references
refs_dir = skill_dir / "references"
refs_dir.mkdir()
(refs_dir / "guide.md").write_text("# Guide Content")
(refs_dir / "api.md").write_text("# API Content")
output_dir = Path(temp_dir) / "output"
output_dir.mkdir()
package_path = self.adaptor.package(skill_dir, output_dir)
# Verify DOCUMENTATION.md contains combined content
with zipfile.ZipFile(package_path, 'r') as zf:
doc_content = zf.read('DOCUMENTATION.md').decode('utf-8')
# Should contain main skill content
self.assertIn('Main Skill', doc_content)
# Should contain reference content
self.assertIn('Guide Content', doc_content)
self.assertIn('API Content', doc_content)
# Should have separators
self.assertIn('---', doc_content)
def test_package_metadata(self):
"""Test that metadata.json is correct"""
with tempfile.TemporaryDirectory() as temp_dir:
skill_dir = Path(temp_dir) / "test-skill"
skill_dir.mkdir()
(skill_dir / "SKILL.md").write_text("# Test")
(skill_dir / "references").mkdir()
output_dir = Path(temp_dir) / "output"
output_dir.mkdir()
package_path = self.adaptor.package(skill_dir, output_dir)
# Verify metadata
with zipfile.ZipFile(package_path, 'r') as zf:
import json
metadata_content = zf.read('metadata.json').decode('utf-8')
metadata = json.loads(metadata_content)
self.assertEqual(metadata['platform'], 'markdown')
self.assertEqual(metadata['name'], 'test-skill')
self.assertEqual(metadata['format'], 'universal_markdown')
self.assertIn('created_with', metadata)
def test_upload_not_supported(self):
"""Test that upload returns appropriate message"""
with tempfile.NamedTemporaryFile(suffix='.zip') as tmp:
result = self.adaptor.upload(Path(tmp.name), 'not-used')
self.assertFalse(result['success'])
self.assertIsNone(result['skill_id'])
self.assertIn('not support', result['message'].lower())
# URL should point to local file
self.assertIn(tmp.name, result['url'])
def test_package_output_filename(self):
"""Test that package creates correct filename"""
with tempfile.TemporaryDirectory() as temp_dir:
skill_dir = Path(temp_dir) / "my-framework"
skill_dir.mkdir()
(skill_dir / "SKILL.md").write_text("# Test")
(skill_dir / "references").mkdir()
output_dir = Path(temp_dir) / "output"
output_dir.mkdir()
package_path = self.adaptor.package(skill_dir, output_dir)
# Should include skill name and 'markdown' suffix
self.assertTrue(package_path.name.startswith('my-framework'))
self.assertIn('markdown', package_path.name)
self.assertTrue(package_path.name.endswith('.zip'))
if __name__ == '__main__':
unittest.main()

191
tests/test_adaptors/test_openai_adaptor.py Normal file
View File

@@ -0,0 +1,191 @@
#!/usr/bin/env python3
"""
Tests for OpenAI adaptor
"""
import unittest
from unittest.mock import patch, MagicMock
from pathlib import Path
import tempfile
import zipfile
from skill_seekers.cli.adaptors import get_adaptor
from skill_seekers.cli.adaptors.base import SkillMetadata
class TestOpenAIAdaptor(unittest.TestCase):
"""Test OpenAI adaptor functionality"""
def setUp(self):
"""Set up test adaptor"""
self.adaptor = get_adaptor('openai')
def test_platform_info(self):
"""Test platform identifiers"""
self.assertEqual(self.adaptor.PLATFORM, 'openai')
self.assertEqual(self.adaptor.PLATFORM_NAME, 'OpenAI ChatGPT')
self.assertIsNotNone(self.adaptor.DEFAULT_API_ENDPOINT)
def test_validate_api_key_valid(self):
"""Test valid OpenAI API keys"""
self.assertTrue(self.adaptor.validate_api_key('sk-proj-abc123'))
self.assertTrue(self.adaptor.validate_api_key('sk-abc123'))
self.assertTrue(self.adaptor.validate_api_key(' sk-test ')) # with whitespace
def test_validate_api_key_invalid(self):
"""Test invalid API keys"""
self.assertFalse(self.adaptor.validate_api_key('AIzaSyABC123')) # Gemini key
# Note: Can't distinguish Claude keys (sk-ant-*) from OpenAI keys (sk-*)
self.assertFalse(self.adaptor.validate_api_key('invalid'))
self.assertFalse(self.adaptor.validate_api_key(''))
def test_get_env_var_name(self):
"""Test environment variable name"""
self.assertEqual(self.adaptor.get_env_var_name(), 'OPENAI_API_KEY')
def test_supports_enhancement(self):
"""Test enhancement support"""
self.assertTrue(self.adaptor.supports_enhancement())
def test_format_skill_md_no_frontmatter(self):
"""Test that OpenAI format has no YAML frontmatter"""
with tempfile.TemporaryDirectory() as temp_dir:
skill_dir = Path(temp_dir)
# Create minimal skill structure
(skill_dir / "references").mkdir()
(skill_dir / "references" / "test.md").write_text("# Test content")
metadata = SkillMetadata(
name="test-skill",
description="Test skill description"
)
formatted = self.adaptor.format_skill_md(skill_dir, metadata)
# Should NOT start with YAML frontmatter
self.assertFalse(formatted.startswith('---'))
# Should contain assistant-style instructions
self.assertIn('You are an expert assistant', formatted)
self.assertIn('test-skill', formatted)
self.assertIn('Test skill description', formatted)
def test_package_creates_zip(self):
"""Test that package creates ZIP file with correct structure"""
with tempfile.TemporaryDirectory() as temp_dir:
skill_dir = Path(temp_dir) / "test-skill"
skill_dir.mkdir()
# Create minimal skill structure
(skill_dir / "SKILL.md").write_text("You are an expert assistant")
(skill_dir / "references").mkdir()
(skill_dir / "references" / "test.md").write_text("# Reference")
output_dir = Path(temp_dir) / "output"
output_dir.mkdir()
# Package skill
package_path = self.adaptor.package(skill_dir, output_dir)
# Verify package was created
self.assertTrue(package_path.exists())
self.assertTrue(str(package_path).endswith('.zip'))
self.assertIn('openai', package_path.name)
# Verify package contents
with zipfile.ZipFile(package_path, 'r') as zf:
names = zf.namelist()
self.assertIn('assistant_instructions.txt', names)
self.assertIn('openai_metadata.json', names)
# Should have vector store files
self.assertTrue(any('vector_store_files' in name for name in names))
def test_upload_missing_library(self):
"""Test upload when openai library is not installed"""
with tempfile.NamedTemporaryFile(suffix='.zip') as tmp:
# Simulate missing library by not mocking it
result = self.adaptor.upload(Path(tmp.name), 'sk-test123')
self.assertFalse(result['success'])
self.assertIn('openai', result['message'])
self.assertIn('not installed', result['message'])
def test_upload_invalid_file(self):
"""Test upload with invalid file"""
result = self.adaptor.upload(Path('/nonexistent/file.zip'), 'sk-test123')
self.assertFalse(result['success'])
self.assertIn('not found', result['message'].lower())
def test_upload_wrong_format(self):
"""Test upload with wrong file format"""
with tempfile.NamedTemporaryFile(suffix='.tar.gz') as tmp:
result = self.adaptor.upload(Path(tmp.name), 'sk-test123')
self.assertFalse(result['success'])
self.assertIn('not a zip', result['message'].lower())
@unittest.skip("Complex mocking - integration test needed with real API")
def test_upload_success(self):
"""Test successful upload to OpenAI - skipped (needs real API for integration test)"""
pass
@unittest.skip("Complex mocking - integration test needed with real API")
def test_enhance_success(self):
"""Test successful enhancement - skipped (needs real API for integration test)"""
pass
def test_enhance_missing_library(self):
"""Test enhance when openai library is not installed"""
with tempfile.TemporaryDirectory() as temp_dir:
skill_dir = Path(temp_dir)
refs_dir = skill_dir / "references"
refs_dir.mkdir()
(refs_dir / "test.md").write_text("Test")
# Don't mock the module - it won't be available
success = self.adaptor.enhance(skill_dir, 'sk-test123')
self.assertFalse(success)
def test_package_includes_instructions(self):
"""Test that packaged ZIP includes assistant instructions"""
with tempfile.TemporaryDirectory() as temp_dir:
skill_dir = Path(temp_dir) / "test-skill"
skill_dir.mkdir()
# Create SKILL.md
skill_md_content = "You are an expert assistant for testing."
(skill_dir / "SKILL.md").write_text(skill_md_content)
# Create references
refs_dir = skill_dir / "references"
refs_dir.mkdir()
(refs_dir / "guide.md").write_text("# User Guide")
output_dir = Path(temp_dir) / "output"
output_dir.mkdir()
# Package
package_path = self.adaptor.package(skill_dir, output_dir)
# Verify contents
with zipfile.ZipFile(package_path, 'r') as zf:
# Read instructions
instructions = zf.read('assistant_instructions.txt').decode('utf-8')
self.assertEqual(instructions, skill_md_content)
# Verify vector store file
self.assertIn('vector_store_files/guide.md', zf.namelist())
# Verify metadata
metadata_content = zf.read('openai_metadata.json').decode('utf-8')
import json
metadata = json.loads(metadata_content)
self.assertEqual(metadata['platform'], 'openai')
self.assertEqual(metadata['name'], 'test-skill')
self.assertIn('file_search', metadata['tools'])
if __name__ == '__main__':
unittest.main()

138
tests/test_install_multiplatform.py Normal file
View File

@@ -0,0 +1,138 @@
#!/usr/bin/env python3
"""
Tests for multi-platform install workflow
"""
import unittest
from unittest.mock import patch, MagicMock, AsyncMock
import asyncio
from pathlib import Path
class TestInstallCLI(unittest.TestCase):
"""Test install_skill CLI with multi-platform support"""
def test_cli_accepts_target_flag(self):
"""Test that CLI accepts --target flag"""
import argparse
import sys
from pathlib import Path
# Mock sys.path to import install_skill module
sys.path.insert(0, str(Path(__file__).parent.parent / "src" / "skill_seekers" / "cli"))
try:
# Create parser like install_skill.py does
parser = argparse.ArgumentParser()
parser.add_argument("--config", required=True)
parser.add_argument("--target", choices=['claude', 'gemini', 'openai', 'markdown'], default='claude')
# Test that each platform is accepted
for platform in ['claude', 'gemini', 'openai', 'markdown']:
args = parser.parse_args(['--config', 'test', '--target', platform])
self.assertEqual(args.target, platform)
# Test default is claude
args = parser.parse_args(['--config', 'test'])
self.assertEqual(args.target, 'claude')
finally:
sys.path.pop(0)
def test_cli_rejects_invalid_target(self):
"""Test that CLI rejects invalid --target values"""
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("--config", required=True)
parser.add_argument("--target", choices=['claude', 'gemini', 'openai', 'markdown'], default='claude')
# Should raise SystemExit for invalid target
with self.assertRaises(SystemExit):
parser.parse_args(['--config', 'test', '--target', 'invalid'])
class TestInstallToolMultiPlatform(unittest.IsolatedAsyncioTestCase):
"""Test install_skill_tool with multi-platform support"""
async def test_install_tool_accepts_target_parameter(self):
"""Test that install_skill_tool accepts target parameter"""
from skill_seekers.mcp.tools.packaging_tools import install_skill_tool
# Just test dry_run mode which doesn't need mocking all internal tools
# Test with each platform
for target in ['claude', 'gemini', 'openai']:
# Use dry_run=True which skips actual execution
# It will still show us the platform is being recognized
with patch('builtins.open', create=True) as mock_open, \
patch('json.load') as mock_json_load:
# Mock config file reading
mock_json_load.return_value = {'name': 'test-skill'}
mock_file = MagicMock()
mock_file.__enter__ = lambda s: s
mock_file.__exit__ = MagicMock()
mock_open.return_value = mock_file
result = await install_skill_tool({
"config_path": "configs/test.json",
"target": target,
"dry_run": True
})
# Verify result mentions the correct platform
result_text = result[0].text
self.assertIsInstance(result_text, str)
self.assertIn("WORKFLOW COMPLETE", result_text)
async def test_install_tool_uses_correct_adaptor(self):
"""Test that install_skill_tool uses the correct adaptor for each platform"""
from skill_seekers.mcp.tools.packaging_tools import install_skill_tool
from skill_seekers.cli.adaptors import get_adaptor
# Test that each platform creates the right adaptor
for target in ['claude', 'gemini', 'openai', 'markdown']:
adaptor = get_adaptor(target)
self.assertEqual(adaptor.PLATFORM, target)
async def test_install_tool_platform_specific_api_keys(self):
"""Test that install_tool checks for correct API key per platform"""
from skill_seekers.cli.adaptors import get_adaptor
# Test API key env var names
claude_adaptor = get_adaptor('claude')
self.assertEqual(claude_adaptor.get_env_var_name(), 'ANTHROPIC_API_KEY')
gemini_adaptor = get_adaptor('gemini')
self.assertEqual(gemini_adaptor.get_env_var_name(), 'GOOGLE_API_KEY')
openai_adaptor = get_adaptor('openai')
self.assertEqual(openai_adaptor.get_env_var_name(), 'OPENAI_API_KEY')
markdown_adaptor = get_adaptor('markdown')
# Markdown doesn't need an API key, but should still have a method
self.assertIsNotNone(markdown_adaptor.get_env_var_name())
class TestInstallWorkflowIntegration(unittest.IsolatedAsyncioTestCase):
"""Integration tests for full install workflow"""
async def test_dry_run_shows_correct_platform(self):
"""Test dry run shows correct platform in output"""
from skill_seekers.cli.adaptors import get_adaptor
# Test each platform shows correct platform name
platforms = {
'claude': 'Claude AI (Anthropic)',
'gemini': 'Google Gemini',
'openai': 'OpenAI ChatGPT',
'markdown': 'Generic Markdown (Universal)'
}
for target, expected_name in platforms.items():
adaptor = get_adaptor(target)
self.assertEqual(adaptor.PLATFORM_NAME, expected_name)
if __name__ == '__main__':
unittest.main()