Metadata-Version: 2.4
Name: skillful-cli
Version: 0.2.5
Summary: Convert videos into SKILL.md files for AI coding agents
License: MIT
Author: Skillful Contributors
Requires-Python: >=3.10
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: httpx (>=0.27.0)
Requires-Dist: pydantic (>=2.0.0)
Requires-Dist: pyyaml (>=6.0.0)
Requires-Dist: rich (>=13.0.0)
Requires-Dist: typer (>=0.12.0)
Requires-Dist: yt-dlp (>=2025.0.0)
Project-URL: Homepage, https://github.com/thepearl/skillful
Project-URL: Repository, https://github.com/thepearl/skillful
Description-Content-Type: text/markdown

# Skillful

**Video → SKILL.md converter for AI coding agents.**

Turn any video (conference talk, tutorial, course) into a `SKILL.md` file that Claude Code, Cursor, Copilot, Codex, Windsurf, and 65+ other AI agents can use.

## Quick Start

```bash
pip install skillful-cli

# Run the setup wizard to pick your provider and model
skillful setup

# Or just jump in — the wizard runs automatically on first use
skillful generate "https://www.youtube.com/watch?v=..."
```

That's it. Skillful walks you through provider selection, key validation, and model discovery.

## Smart Setup Wizard

On first run, Skillful launches an interactive 4-step wizard:

```
$ skillful setup

🔧 Skillful Setup

Step 1: Select your AI provider
  ┌───┬─────────────┬──────────────────────────────────┬────────────┐
  │ # │ Provider    │ Description                      │ Key Format │
  ├───┼─────────────┼──────────────────────────────────┼────────────┤
  │ 1 │ OpenAI →    │ GPT-4o, GPT-4.1, o4-mini         │ sk-...     │
  │ 2 │ Anthropic   │ Claude Sonnet 4, Opus 4, Haiku   │ sk-ant-... │
  │ 3 │ DeepSeek    │ DeepSeek Chat — free tier         │ sk-...     │
  │ … │             │                                  │            │
  └───┴─────────────┴──────────────────────────────────┴────────────┘
  Provider number (default: 1): 2   ← pick Anthropic

Step 2: API Key for Anthropic
  Keys typically look like: sk-ant-...
  Paste your API key: ********

Step 3: Validating API key with Anthropic...
  ✓ API key accepted by Anthropic

Step 4: Fetching available models from Anthropic...
  ┌───┬──────────────────────────┐
  │ # │ Model ID                 │
  ├───┼──────────────────────────┤
  │ 1 │ claude-sonnet-4-6 →      │
  │ 2 │ claude-haiku-4-5         │
  │ 3 │ claude-opus-4-8          │
  └───┴──────────────────────────┘
  Model number (default: 1):    ← just hit Enter

✓ Configuration saved to ~/.skillful/config.yaml
```

**How it works:**
1. You pick your provider from the list (OpenAI, Anthropic, DeepSeek, etc.) — base URL is set automatically
2. You enter your API key (with provider-specific format hints)
3. The key is validated against your chosen provider
4. Live model list is fetched from `/v1/models`, filtered to chat-capable models only
5. You confirm the model (smart default pre-selected) — done

## BYOK — Bring Your Own Key

Works with **any** OpenAI-compatible API. Skillful ships with 10 pre-configured providers:

| Provider | Base URL | Default Model |
|---|---|---|
| OpenAI | `https://api.openai.com/v1` | `gpt-4o` |
| Anthropic | `https://api.anthropic.com/v1` | `claude-sonnet-4-6` |
| DeepSeek | `https://api.deepseek.com/v1` | `deepseek-chat` |
| Groq | `https://api.groq.com/openai/v1` | `llama-4-maverick-17b-128e-instruct` |
| Mistral | `https://api.mistral.ai/v1` | `mistral-large-latest` |
| Together AI | `https://api.together.xyz/v1` | `meta-llama/Llama-4-Maverick-17B-128E-Instruct` |
| Fireworks AI | `https://api.fireworks.ai/inference/v1` | `accounts/fireworks/models/llama-v4-maverick-17b-128e-instruct` |
| xAI | `https://api.x.ai/v1` | `grok-4-latest` |
| NVIDIA NIM | `https://integrate.api.nvidia.com/v1` | `mistralai/mistral-large-3-675b-instruct-2512` |
| Ollama (local) | `http://localhost:11434/v1` | `llama3.2` |

If your provider isn't listed, you can still use it — just set the env vars manually:

```bash
export SKILLFUL_API_KEY="your-key"
export SKILLFUL_API_BASE_URL="https://your-provider.com/v1"
export SKILLFUL_MODEL="your-model"
```

Or use `skillful config --set`:

```bash
skillful config --set base_url --value "https://custom.api/v1"
skillful config --set model --value "my-model"
```

## Commands

```bash
# Core
skillful generate <url>              # Generate SKILL.md from a video
skillful generate --verbose <url>    # Stream claims in real-time as extracted
skillful generate --playlist <url>   # Generate from entire playlist
skillful generate --split category   # One SKILL.md per claim category
skillful list                        # List generated batches
skillful review <dir>                # Interactively review claims
skillful setup                       # Run the interactive config wizard

# Advanced (optional flags on generate)
skillful generate <url> --frames scene            # Extract + describe key frames via vision API
skillful generate <url> --frames interval --frame-interval 60
skillful generate <url> --docs https://docs.foo.com
skillful generate <url> --sample-project ./my-repo
skillful generate <url> --local-models            # Use local LLM (Ollama/LM Studio)

# Export & Publish
skillful export <dir> --target claude     # Export to Claude Code
skillful export <dir> --target all        # Export to all 72 agents
skillful publish <dir> --target github    # Publish to GitHub repo
skillful publish <dir> --target skills-sh # Publish to skills.sh

# Quality
skillful evaluate <dir>                   # Score a single SKILL.md (0-100)
skillful eval                             # Run 5-video benchmark

# Config & Cache
skillful config --show                    # Show current config
skillful config --set api_key --value "sk-..."  # Set any config key
skillful cache                            # Show cache stats
skillful cache --clear                    # Clear cached LLM responses
```

## Configuration Reference

All 13 config keys (3 required, 10 optional):

| Key | Required | Env Var | Description |
|---|---|---|---|
| `api_key` | **Yes** | `SKILLFUL_API_KEY` | Your API key |
| `base_url` | **Yes** | `SKILLFUL_API_BASE_URL` | API endpoint URL |
| `model` | **Yes** | `SKILLFUL_MODEL` | Model name |
| `vision_api_key` | No | `SKILLFUL_VISION_API_KEY` | Vision model key (falls back to `api_key`) |
| `vision_model` | No | `SKILLFUL_VISION_MODEL` | Vision model for `--frames` |
| `search_api_key` | No | `SKILLFUL_SEARCH_API_KEY` | Search API key for `--docs` |
| `github_token` | No | `SKILLFUL_GITHUB_TOKEN` | GitHub PAT for `publish --target github` |
| `skills_sh_token` | No | `SKILLS_SH_TOKEN` | skills.sh token for `publish --target skills-sh` |
| `cache_dir` | No | `SKILLFUL_CACHE_DIR` | LLM response cache location |
| `output_dir` | No | `SKILLFUL_OUTPUT_DIR` | Default output directory |
| `default_language` | No | `SKILLFUL_DEFAULT_LANGUAGE` | Output language (default: `auto`) |
| `batch_size` | No | `SKILLFUL_BATCH_SIZE` | Segments per LLM batch (default: `4`) |
| `concurrency` | No | `SKILLFUL_CONCURRENCY` | Parallel workers (default: `1`) |

## Features

### Rich SKILL.md Output
- YAML frontmatter (name, description, tags, version, source_url)
- Overview section with claim summary
- How-To steps with code blocks (auto-detected language: Swift/Python/JS/Rust/SQL/etc.)
- Code Examples section with syntax-highlighted fences
- Extracted Knowledge organized by category (APIs, Code Patterns, Rules, General)
- Timestamped knowledge: every claim links back to the video timestamp
- skills.sh compatible format — direct publish to the skills.sh registry

### Advanced Features
- **Smart Setup Wizard** — Provider-first flow: pick your provider, validate your key, auto-discover models
- **`--verbose`** — Stream claims in real-time with category icons and per-batch timing
- **`--frames`** — Extract key frames via ffmpeg scene detection, describe with vision API
- **`--docs`** — Fetch reference documentation URLs to ground extraction claims
- **`--sample-project`** — Scan a codebase to ground claims against real code patterns
- **`--local-models`** — Auto-detect Ollama, LM Studio, LocalAI — no cloud API needed
- **`--playlist`** — Process entire YouTube playlists into multiple SKILL.md files
- **`--split category`** — Produce one SKILL.md per claim category (APIs, Code, Rules, etc.)
- **Parallel extraction** — Process LLM batches concurrently (3x speedup)
- **Response caching** — `skillful cache` avoids re-processing the same video
- **88% token deduplication** — Recursive word-level repeat detection eliminates YouTube caption noise

### Export to 72 AI Agents
Claude Code, Cursor, Copilot, Codex, OpenCode, Windsurf, Gemini, Aider, Continue, Tabnine, Cody, Qodo, Augment, Replit, Lovable, Bolt, v0, Devin, Factory, Cline, Roo, All-Hands, Avante, Melty, PearAI, Void, Open Interpreter, aiChat, Shell-GPT, Mods, Fabric, CrewAI, AutoGen, LangChain, LlamaIndex, DSPy, Smolagents, Pydantic-AI, Magentic, Ollama, LM Studio, Jan, GPT4All, LocalAI, Text-Generation-WebUI, vLLM, Amazon Q, WatsonX, Vertex AI, Azure AI, Databricks, Snowflake, GPT Researcher, PaperQA, Storm, Perplexity, Phind, You, K8sGPT, Pulumi AI, OpenTofu, Dagger, SWE-Agent, Devika, GPT-Pilot, Mentat, GPT-Engineer, MetaGPT, ChatDev, Aider-Chat

### Quality
- **5-axis evaluator** — Scores on Coverage (25%), Structure (20%), Actionability (20%), Specificity (20%), Metadata (15%)
- **5-video benchmark** — Automated quality comparison across curated test videos
- **469 tests** — 457 unit + 12 integration, 0 failures, clean PyPI install verified
- **GitHub Actions CI** — Automated testing on Python 3.10–3.12

## Token Usage

~500 tokens per minute of video after YouTube caption deduplication (88% reduction). A 10-minute video costs ~5,000 tokens — ~$0.01 with DeepSeek, ~$0.02 with GPT-4o.

## Troubleshooting

**`skillful: command not found`** — Ensure pip's bin directory is in your PATH:
```bash
export PATH="$HOME/.local/bin:$PATH"         # Linux
export PATH="$HOME/Library/Python/3.12/bin:$PATH"  # macOS
```

**YouTube "Precondition check failed"** — Update yt-dlp:
```bash
pip install --upgrade yt-dlp
```

**No claims extracted** — Check your API key and model:
```bash
skillful config --show
```

**Rate limited (429)** — Skillful retries with exponential backoff (up to 5 attempts). Try `--local-models` to avoid cloud rate limits.

**Authentication failed during setup** — Run `skillful setup` again and verify you picked the correct provider for your key. Anthropic keys use `x-api-key` auth; all others use `Bearer`.

## Contribute

```bash
git clone https://github.com/thepearl/skillful-cli.git && cd skillful-cli
pip install -e ".[dev]"
pip install pytest ruff
pytest tests/ -q                # 469 tests
ruff check --select E,F,W,I,N --ignore E501 .
```

See [CHANGELOG.md](CHANGELOG.md) for version history. See [VISION.md](VISION.md) for the full project vision.

