skillful-cli 0.2.0

Convert videos into SKILL.md files for AI coding agents

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

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

# 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

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 for version history. See VISION.md for the full project vision.