skillful-cli 0.2.5

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

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:

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:

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

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

export PATH="$HOME/.local/bin:$PATH"         # Linux
export PATH="$HOME/Library/Python/3.12/bin:$PATH"  # macOS

YouTube "Precondition check failed" — Update yt-dlp:

pip install --upgrade yt-dlp

No claims extracted — Check your API key and model:

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

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