youtube-skill

name	youtube-skill
description	Download YouTube videos with format control, metadata extraction, and real-time progress tracking. Use via agent tools or an interactive desktop window.

YouTube Downloader Skill

A Copilot CLI extension that enables downloading YouTube videos with flexible format selection, metadata extraction, and progress tracking. Access via agent tools or an interactive webview UI.

Features

• Multiple download formats: Best quality, audio extraction (MP3/M4A/WAV), MP4, MKV, resolution presets (360p/720p/1080p)
• Metadata extraction: Save JSON info files, thumbnails, auto-generated subtitles
• Interactive UI: Desktop window for URL input, format selection, output directory picker
• Agent tools: youtube_download tool for programmatic downloads
• Real-time progress: Live progress bar and status log
• Format discovery: Query available formats before downloading (coming soon)

Prerequisites

Option 1: yt-dlp Binary (Recommended - No Python Required)

Download the pre-built binary for Linux/Mac:

# Linux
cd .github/skills/youtube-skill/bin
wget https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp -O yt-dlp
chmod +x yt-dlp

# Mac
cd .github/skills/youtube-skill/bin
curl -L https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp_macos -o yt-dlp
chmod +x yt-dlp

Benefits:

• No Python dependency
• Faster startup
• Single executable
• Portable

Option 2: Python Module (System-wide)

1. Python 3.10+ installed system-wide
2. yt-dlp package:

   pip install yt-dlp
   

Benefits:

• No additional download
• Easy to update: pip install --upgrade yt-dlp

Option 3: Separate Virtual Environment

Create an isolated Python environment:

cd .github/skills/youtube-skill/
python3 -m venv .venv
source .venv/bin/activate   # On Windows: .venv\Scripts\activate
pip install yt-dlp

Benefits:

• Isolated from system Python
• No permission issues
• Easy to delete (.venv folder)

Option 4: Copilot CLI Auto-Download

First startup may auto-detect and download the binary if Python is unavailable. Or call:

import { downloadBinary } from "./backend.js";
await downloadBinary();  // Downloads for your OS

Installation

1. Copy this skill directory to your workspace:

   .github/skills/youtube-skill/
   

2. Reload Copilot extensions (or restart Copilot CLI)

Usage

Via Slash Command (Interactive UI)

Open the YouTube downloader window:

/youtube-skill

Or pass a URL as argument:

/youtube-skill https://www.youtube.com/watch?v=dQw4w9WgXcQ

The window provides:

• URL input field
• Format dropdown (best, audio, MP4, MKV, 360p, 720p, 1080p)
• Output directory picker
• Metadata checkbox (JSON, thumbnail, subtitles)
• Real-time progress bar and status log

Via Agent Tool

Ask Copilot to download a video:

Download the video from https://youtube.com/watch?v=dQw4w9WgXcQ as MP3 to ~/Downloads

The agent will invoke the youtube_download tool with parameters:

• url (required): YouTube video URL
• format (optional): Video format (default: "best")
• outputPath (required): Directory to save files
• metadata (optional): Whether to save metadata (default: true)

Programmatic (Node.js)

import { downloadVideo, verifyPrerequisites } from "./backend.js";

// Verify yt-dlp is installed
const ready = await verifyPrerequisites();
if (!ready) {
    console.error("yt-dlp not found. Install: pip install yt-dlp");
    process.exit(1);
}

// Download with progress tracking
const result = await downloadVideo({
    url: "https://youtube.com/watch?v=...",
    format: "mp4",
    outputPath: "./downloads",
    metadata: true,
    onProgress: (percent, status) => {
        console.log(`[${percent}%] ${status}`);
    },
});

if (result.success) {
    console.log(`✅ Saved: ${result.filename}`);
} else {
    console.error(`❌ ${result.error}`);
}

Supported Formats

Format	Output	Use Case
best	video + audio (best available)	Default; highest quality
best-video	video + audio merged	Similar to "best"
audio	MP3 file	Music extraction
audio-m4a	M4A file	Portable audio
audio-wav	WAV file	Lossless audio
mp4	MP4 video file	Universally compatible
mkv	MKV video file	Preserves quality
360p	Video ≤ 360p	Low bandwidth
720p	Video ≤ 720p	Standard HD
1080p	Video ≤ 1080p	Full HD

Output Structure

Downloads are saved to the specified directory:

output-directory/
├── Video Title.mp4              # Downloaded video/audio
├── Video Title.info.json        # Metadata (if metadata=true)
├── Video Title.jpg              # Thumbnail
└── Video Title.en.vtt           # Auto-generated subtitles

Configuration

Optional .env file (copy from .env.example):

# Default output directory (if empty, user is prompted)
YOUTUBE_SKILL_DEFAULT_OUTPUT_DIR=./downloads

# Enable debug logging
DEBUG=false

Troubleshooting

"Python 3.10+ and yt-dlp not found"

Fix: Install yt-dlp

python3 -m pip install --upgrade yt-dlp

"Download failed: Video unavailable"

Causes:

• Video is age-restricted or private
• Video is geographically blocked
• Video was deleted

Solution: Try a different video or check YouTube restrictions

"No formats found"

Possible issue: yt-dlp failed to fetch video metadata

Solution:

• Verify the URL is correct
• Check internet connection
• Update yt-dlp: pip install --upgrade yt-dlp

Webview won't open

Possible issue: Missing WebView dependencies

Solution:

• On Linux: Install libxdo-dev, libxkbcommon-dev, libssl-dev
• On macOS: Update Xcode command-line tools
• On Windows: Ensure WebView2 runtime is installed

Progress stuck at 0%

Possible issue: yt-dlp is still initializing (fetching metadata)

Solution: Wait; this is normal for the first 5-10 seconds

Known Limitations

1. Single download at a time: Cannot queue multiple downloads (use slash command multiple times)
2. Playlist downloads: Not yet supported; extract video ID and download individually
3. Live streams: Limited support; requires testing
4. Region-locked content: May fail depending on YouTube's TOS and geo-blocks
5. Large files: May timeout if file >4 GB or connection is slow

Architecture

┌─────────────────┐
│  Copilot Agent  │
└────────┬────────┘
         │
    ┌────▼─────────────────────────┐
    │   youtube-skill Extension    │
    ├──────────────────────────────┤
    │ main.mjs (callbacks + tools) │
    │ backend.js (orchestration)   │
    │ content/ (webview UI)        │
    └────────┬─────────────────────┘
             │
    ┌────────▼──────────────────────┐
    │  Python subprocess            │
    │  yt-dlp (CLI tool)            │
    └───────────────────────────────┘

File Structure

.github/skills/youtube-skill/
├── extension.mjs              # Bootstrapper (do not edit)
├── main.mjs                   # Extension logic, callbacks, tools
├── backend.js                 # yt-dlp orchestration
├── package.json               # Node dependencies
├── .gitignore                 # Ignore node_modules, downloads
├── .env.example               # Configuration template
├── lib/
│   ├── copilot-webview.js    # Webview library (do not edit)
│   └── webview-child.mjs     # Child process launcher (do not edit)
├── content/
│   ├── index.html            # Webview UI structure
│   ├── main.js               # Form logic and callbacks
│   └── style.css             # Styling
└── SKILL.md                   # This file

Contributing

Improvements welcome! Common areas:

• Format auto-detection (query available formats before download)
• Playlist support
• Download queue management
• Custom post-processors (audio conversion, compression)
• Proxy/VPN support for geo-blocked content

License

MIT

Support

For issues or feature requests:

1. Verify yt-dlp is installed: python3 -m yt_dlp --version
2. Check logs in Copilot's debug output
3. Try updating: pip install --upgrade yt-dlp

References

• yt-dlp GitHub
• yt-dlp Documentation
• Copilot CLI Extension SDK