From 9806b62a9bc350efcdcfcd65761a3bbb7e6ada3f Mon Sep 17 00:00:00 2001 From: yusyus Date: Sun, 28 Dec 2025 21:55:07 +0300 Subject: [PATCH] docs: Update all documentation for multi-platform feature parity MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Complete documentation update to reflect multi-platform support across all 4 platforms (Claude, Gemini, OpenAI, Markdown). Changes: - src/skill_seekers/mcp/README.md: * Fixed tool count (10 → 18 tools) * Added enhance_skill tool documentation * Updated package_skill docs with target parameter * Updated upload_skill docs with target parameter * Updated tool numbering after adding enhance_skill - docs/MCP_SETUP.md: * Updated packaging tools section (3 → 4 tools) * Added enhance_skill to tool lists * Added Example 4: Multi-Platform Support * Shows target parameter usage for all platforms - docs/ENHANCEMENT.md: * Added comprehensive Multi-Platform Enhancement section * Documented Claude (local + API modes) * Documented Gemini (API mode, model, format) * Documented OpenAI (API mode, model, format) * Added platform comparison table * Updated See Also links - docs/UPLOAD_GUIDE.md: * Complete rewrite for multi-platform support * Detailed guides for all 4 platforms * Claude AI: API + manual upload methods * Google Gemini: tar.gz format, Files API * OpenAI ChatGPT: Vector Store, Assistants API * Generic Markdown: Universal export, manual distribution * Added platform comparison tables * Added troubleshooting for all platforms All docs now accurately reflect the feature parity implementation. Users can now find complete information about packaging, uploading, and enhancing skills for any platform. Related: Feature parity implementation (commits 891ce2d, 2ec2840) --- docs/ENHANCEMENT.md | 78 ++++ docs/MCP_SETUP.md | 56 ++- docs/UPLOAD_GUIDE.md | 683 ++++++++++++++++++-------------- src/skill_seekers/mcp/README.md | 63 ++- 4 files changed, 566 insertions(+), 314 deletions(-) diff --git a/docs/ENHANCEMENT.md b/docs/ENHANCEMENT.md index 0a9b9f8..c437725 100644 --- a/docs/ENHANCEMENT.md +++ b/docs/ENHANCEMENT.md @@ -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 diff --git a/docs/MCP_SETUP.md b/docs/MCP_SETUP.md index 78fd941..4e6e64e 100644 --- a/docs/MCP_SETUP.md +++ b/docs/MCP_SETUP.md @@ -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 diff --git a/docs/UPLOAD_GUIDE.md b/docs/UPLOAD_GUIDE.md index 25ad04c..d11063c 100644 --- a/docs/UPLOAD_GUIDE.md +++ b/docs/UPLOAD_GUIDE.md @@ -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 diff --git a/src/skill_seekers/mcp/README.md b/src/skill_seekers/mcp/README.md index f34cb1f..b267b5b 100644 --- a/src/skill_seekers/mcp/README.md +++ b/src/skill_seekers/mcp/README.md @@ -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:**