Metadata-Version: 2.4
Name: skillful-cli
Version: 0.2.1
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
git clone https://github.com/thepearl/skillful.git && cd skillful && pip install -e .

# If 'skillful' not found, add to PATH:
export PATH="$HOME/Library/Python/3.12/bin:$PATH"  # macOS
# or: export PATH="$HOME/.local/bin:$PATH"           # Linux

# Set your API key (any OpenAI-compatible provider)
export SKILLFUL_API_KEY="sk-your-key-here"

# Generate a SKILL.md from any video
skillful generate "https://www.youtube.com/watch?v=..."
```

## BYOK — Bring Your Own Key

Works with **any** OpenAI-compatible API:

| Provider | `SKILLFUL_API_KEY` | `SKILLFUL_API_BASE_URL` | `SKILLFUL_MODEL` |
|---|---|---|---|
| DeepSeek | `sk-...` | `https://api.deepseek.com/v1` | `deepseek-chat` |
| OpenAI | `sk-...` | `https://api.openai.com/v1` | `gpt-4o` |
| Anthropic | `sk-ant-...` | `https://api.anthropic.com/v1` | `claude-sonnet-4-20250514` |
| Groq | `gsk_...` | `https://api.groq.com/openai/v1` | `llama-3.1-70b` |
| Ollama (local) | `ollama` | `http://localhost:11434/v1` | `llama3` |

## 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

# Advanced (optional flags on generate)
skillful generate <url> --frames scene            # Extract + describe key frames
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

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

# Cache
skillful cache                            # Show cache stats
skillful cache --clear                    # Clear cached LLM responses

# Config
skillful config --init                    # Save API config
skillful config --show                    # Show current config
skillful config --set api_key --value "sk-..."  # Set API key
```

## 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

### Advanced Features
- **`--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

### 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**: Coverage, Structure, Actionability, Specificity, Metadata
- **5-video benchmark**: Automated quality comparison across curated test videos
- **469 tests**: Comprehensive test suite with 0 failures (457 unit + 12 integration)
- **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`** — Add pip bin to PATH (see Quick Start above).

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

**No claims extracted** — Check your `SKILLFUL_API_KEY` and model availability.

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

## Contribute

```bash
pip install -e .
pip install pytest ruff
pytest tests/ -q                # 340+ 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.

