firefrost-gaming/claude-code-skills-reference
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Release v1.24.0: Add claude-skills-troubleshooting

Browse Source 
- Add claude-skills-troubleshooting v1.0.0
  - Plugin installation and enablement debugging
  - Diagnostic scripts for installed vs enabled mismatch
  - Known GitHub issues tracking (#17832, #19696, #17089, #13543, #16260)
  - Skills vs Commands architecture documentation
  - Batch enable script for missing plugins

- Add i18n-expert v1.0.0
  - Complete i18n/l10n setup for React/Next.js/Vue
  - Key architecture and locale file organization
  - Translation generation strategy (AI, professional, manual)
  - Key parity validation between en-US and zh-CN
  - Bundled i18n_audit.py script

- Update marketplace to v1.24.0 (32 skills)
- Update README.md badges (skills count, version)
- Update README.zh-CN.md badges (skills count, version)
- Update CLAUDE.md skills count and Available Skills list
- Update youtube-downloader with PO token enhancements

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
daymade
2026-01-22 22:05:14 +08:00
parent abd7fdc048
commit 35872b9e77
16 changed files with 2577 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files

167
youtube-downloader/SKILL.md
View File

@@ -12,6 +12,95 @@ Enable reliable video and audio downloads from YouTube and HLS streaming platfor
- HLS stream downloads with authentication headers
- Handling protected content and troubleshooting common download failures
## Non-Technical User Experience (Default)
Assume the user is non-technical. Do not ask them to run commands. Execute everything yourself and report progress in plain language. Avoid mentioning tooling unless the user asks.
**Default flow:**
1. Ask for the URL (if not provided).
2. Fetch video metadata (title/uploader/duration/thumbnail) and confirm it matches the user's intent.
- If yt-dlp is blocked by “confirm you’re not a bot”, fall back to YouTube oEmbed for title/uploader/thumbnail (duration may be unknown).
3. Offer simple choices (video vs. audio-only, quality, subtitles, save location).
4. Proceed with sensible defaults if the user does not specify:
- Video download at best quality
- MP4 merged output
- Single video only (no playlists)
5. Download and report the final file path, file size, and resolution (if video).
**Offer choices in user-friendly terms:**
- “Download the video in best quality (default)”
- “Download audio only (MP3)”
- “Pick a quality: 1080p / 720p / 480p / 360p”
- “Include subtitles (if available)”
- “Save to the Downloads folder (default) or tell me another folder”
**Always render the thumbnail when available:**
- If metadata includes a thumbnail URL, include it using Markdown image syntax: `![Thumbnail](URL)`.
**Ask before doing extra work:**
- Confirm playlist downloads (can be large).
- Confirm installing/upgrading dependencies if missing.
- Ask before extracting browser cookies.
- If using cookies, never mention cookie counts or raw cookie details in user-facing responses. Say “used your Chrome login session”.
- If verification is required, automatically set up a local PO Token helper (no user actions). If Docker is missing or fails, do **not** attempt to install Docker—switch to the browser-based PO Token provider instead.
**Legal/Safety reminder (brief):**
- Proceed only if the user has the rights or permission to download the content.
**Response template (use plain language, no commands):**
```
![Thumbnail](THUMBNAIL_URL)
Title: …
Channel: …
Duration: …
I can help you:
1) Download the video (best quality, MP4)
2) Download audio only (MP3)
3) Pick a specific quality (1080p/720p/480p/360p)
4) Include subtitles (if available)
Where should I save it? (Default: Downloads folder)
```
**If the user says “just download”:**
- Proceed with defaults and confirm when the download finishes.
- If blocked by a 403, automatically set up the verification helper and retry.
## Reliable Download SOP (Internal)
Follow this SOP to avoid common failures and confusion:
1. Quote URLs in shell commands (zsh treats `?` as a glob). Example: `'https://www.youtube.com/watch?v=VIDEO_ID'`.
2. Ensure proxy is active for both yt-dlp and PO Token providers (HTTP_PROXY/HTTPS_PROXY/ALL_PROXY).
3. If you see “Sign in to confirm you’re not a bot”, request permission and use browser cookies. Do not proceed without cookies.
4. Start a PO Token provider before downloading (fail fast if it cannot start).
- Use Docker bgutil provider when available.
- If Docker is missing or fails, switch to browser-based WPC provider.
5. If cookies are in use, prefer the `web_safari` player client. Otherwise prefer `mweb` for PO tokens.
6. Keep the browser window open while WPC is minting tokens. Ensure Chrome can reach YouTube through the same proxy.
7. If you get “Only images are available” or “Requested format is not available”, treat it as a PO Token failure and retry after fixing token provider/browser state.
8. If you get SSL EOF or fragment errors, treat it as a proxy/network issue. Retry with progressive formats and/or a better proxy.
## Agent Execution Checklist (Internal)
- Run `scripts/download_video.py URL --info` (add `--cookies-from-browser chrome` if permission granted) to fetch metadata and thumbnail.
- If yt-dlp metadata fails, rely on the script’s oEmbed fallback for title/uploader/thumbnail and note that duration may be unavailable.
- If a thumbnail URL is present, render it in the response with Markdown image syntax.
- Ask the user to choose video vs. audio-only and (optionally) a quality preset.
- Use a friendly default save location (Downloads folder) unless the user specifies a folder.
- For subtitles, run with `--subtitles` and the requested `--sub-lang`.
- After download, report file name, size, and resolution (if video) in plain language.
- If download fails with 403/fragment errors, retry once with non-m3u8 progressive formats.
- If “Sign in to confirm you’re not a bot” appears, request cookie access and retry with cookies + `web_safari`.
- If “Only images are available” appears, treat it as PO Token failure and retry after fixing provider/browser state.
- Start the PO Token provider before downloads (`--auto-po-token` default). Fail fast if it cannot start.
- If Docker-based provider fails (common in China), automatically fall back to the browser-based WPC provider (it may briefly open a browser window).
- If the WPC provider is used, keep the browser window open until download starts. If the browser fails to launch, set the Chrome path explicitly.
- If the PO Token provider times out, restart it once and retry.
- If a system proxy is configured, pass it into the provider container. If the proxy points to 127.0.0.1/localhost, rewrite it to `host.docker.internal` for Docker.
## When to Use This Skill
This skill should be invoked when users:
@@ -27,7 +116,7 @@ This skill should be invoked when users:
## Prerequisites
### 1. Verify yt-dlp Installation
### 1. Verify yt-dlp Installation (Run this yourself)
```bash
which yt-dlp
@@ -44,7 +133,7 @@ pip install --upgrade yt-dlp # Cross-platform
**Critical**: Outdated yt-dlp versions cause nsig extraction failures and missing formats.
### 2. Check Current Quality Access
### 2. Check Current Quality Access (Run this yourself)
Before downloading, check available formats:
@@ -61,11 +150,11 @@ yt-dlp -F "https://youtu.be/VIDEO_ID"
For 1080p/1440p/4K access, install a PO token provider plugin into yt-dlp's Python environment:
```bash
# Find yt-dlp's Python path
# Find yt-dlp's Python path (interpreter used by yt-dlp)
head -1 $(which yt-dlp)
# Install plugin (adjust path to match yt-dlp version)
/opt/homebrew/Cellar/yt-dlp/$(yt-dlp --version)/libexec/bin/python -m pip install bgutil-ytdlp-pot-provider
# Install plugin using the interpreter from the line above
<YTDLP_PYTHON> -m pip install bgutil-ytdlp-pot-provider
```
**Verification**: Run `yt-dlp -F "VIDEO_URL"` again. Look for formats 137 (1080p), 271 (1440p), or 313 (4K).
@@ -111,11 +200,14 @@ yt-dlp --cookies-from-browser chrome -f "bestvideo[height<=1080]+bestaudio/best"
```
**Benefits**: Access to age-restricted and members-only content.
**Requirement**: Must be logged into YouTube in the specified browser.
**Requirements**:
- Must be logged into YouTube in the specified browser.
- Browser and yt-dlp must use the same IP/proxy.
- Do not use Android client with cookies (Android client does not support cookies).
## Common Tasks
### Audio-Only Download
### Audio-Only Download (Run this yourself)
Extract audio as MP3:
@@ -123,25 +215,25 @@ Extract audio as MP3:
yt-dlp -x --audio-format mp3 "VIDEO_URL"
```
### Custom Output Directory
### Custom Output Directory (Run this yourself)
```bash
yt-dlp -P ~/Downloads/YouTube "VIDEO_URL"
```
### Download with Subtitles
### Download with Subtitles (Run this yourself)
```bash
yt-dlp --write-subs --sub-lang en "VIDEO_URL"
```
### Playlist Download
### Playlist Download (Run this yourself)
```bash
yt-dlp -f "bestvideo[height<=1080]+bestaudio/best" "PLAYLIST_URL"
```
### Convert WebM to MP4
### Convert WebM to MP4 (Run this yourself)
YouTube high-quality downloads often use WebM format (VP9 codec). Convert to MP4 for wider compatibility:
@@ -173,6 +265,24 @@ ffmpeg -i "video.webm" -c:v libx264 -preset medium -crf 23 -c:a aac -b:a 128k "v
2. Install PO token provider (see Step 1 above)
3. Or use browser cookies method
### Sign in to Confirm You’re Not a Bot
**Cause**: YouTube requires authentication to proceed.
**Solution**:
1. Request permission and use browser cookies (`--cookies-from-browser chrome`).
2. Ensure the browser and yt-dlp use the same IP/proxy.
3. Retry with `web_safari` client if needed.
### Only Images Available / Requested Format Not Available
**Cause**: PO tokens not applied or provider/browser verification failed.
**Solution**:
1. Verify PO Token provider is running before download.
2. Keep the browser window open if using WPC.
3. If cookies are in use, prefer `web_safari` client and retry.
### nsig Extraction Failed
**Symptoms**:
@@ -183,7 +293,16 @@ WARNING: [youtube] nsig extraction failed: Some formats may be missing
**Solution**:
1. Update yt-dlp to latest version
2. Install PO token provider
3. If still failing, use Android client: `yt-dlp --extractor-args "youtube:player_client=android" "VIDEO_URL"`
3. If still failing and PO tokens are disabled, use Android client: `yt-dlp --extractor-args "youtube:player_client=android" "VIDEO_URL"`
### SSL EOF / Fragment Errors
**Cause**: Proxy or network instability.
**Solution**:
1. Retry with progressive formats (non-m3u8).
2. Switch to a more stable proxy/node.
3. Avoid closing the PO token browser window during download.
### Slow Downloads or Network Errors
@@ -204,7 +323,7 @@ WARNING: android client https formats require a GVS PO Token
### scripts/download_video.py
A convenience wrapper that applies Android client workaround by default:
Use this convenience wrapper to auto-start a PO Token provider by default for high-quality downloads. Use it yourself and report results to the user without asking them to run commands.
**Basic usage:**
```bash
@@ -214,20 +333,34 @@ scripts/download_video.py "VIDEO_URL"
**Arguments:**
- `url` - YouTube video URL (required)
- `-o, --output-dir` - Output directory
- `--output-template` - Output filename template (yt-dlp syntax)
- `-f, --format` - Format specification
- `-q, --quality` - Quality preset (best, 1080p, 720p, 480p, 360p, worst). Default: best (skipped for `--audio-only`)
- `-a, --audio-only` - Extract audio as MP3
- `--subtitles` - Download subtitles if available
- `--sub-lang` - Subtitle languages (comma-separated, default: en)
- `--cookies-from-browser` - Load cookies from a browser (e.g., chrome, firefox)
- `--cookies-file` - Load cookies from a cookies.txt file
- `--player-client` - Use a specific YouTube player client (e.g., web_safari)
- `--auto-po-token` - Auto-start PO Token provider (default; uses Docker if available, otherwise switches to browser-based provider)
- `--no-auto-po-token` - Disable auto PO Token setup
- `--proxy` - Proxy URL for yt-dlp and the PO Token provider (e.g., http://127.0.0.1:1082)
- `--wpc-browser-path` - Browser executable path for WPC provider
- `-F, --list-formats` - List available formats
- `--no-android-client` - Disable Android client workaround
- `--merge-format` - Merge output container (e.g., mp4, mkv). Default: mp4
- `--playlist` - Allow playlist downloads (default: single video only)
- `--info` - Print title/uploader/duration/thumbnail and exit
- `--no-android-client` - Disable Android client fallback
**Note**: This script uses Android client (360p only without PO tokens). For high quality, use yt-dlp directly with PO token provider.
**Note**: Use the Android client only when PO tokens are disabled. Keep PO tokens enabled for high quality.
## Quality Expectations
| Setup | 360p | 720p | 1080p | 1440p | 4K |
|-------|------|------|-------|-------|-----|
| No setup (default) | ✗ | ✗ | ✗ | ✗ | ✗ |
| **Auto PO token (default)** | ✓ | ✓ | ✓ | ✓ | ✓ |
| Android client only | ✓ | ✗ | ✗ | ✗ | ✗ |
| **PO token provider** | ✓ | ✓ | ✓ | ✓ | ✓ |
| PO token provider (manual) | ✓ | ✓ | ✓ | ✓ | ✓ |
| Browser cookies | ✓ | ✓ | ✓ | ✓ | ✓ |
## HLS Stream Downloads (m3u8)

51
youtube-downloader/references/po-token-setup.md
View File

@@ -16,6 +16,41 @@ With PO token provider: **Full access** to all quality levels including 4K.
## Recommended Solution: PO Token Provider Plugin
## Operational SOP (Internal)
Use this checklist to prevent common failures:
1. Quote URLs in shell commands to avoid zsh globbing (`'https://www.youtube.com/watch?v=VIDEO_ID'`).
2. Ensure proxy is active for yt-dlp and token providers (HTTP_PROXY/HTTPS_PROXY/ALL_PROXY).
3. If YouTube asks to confirm you’re not a bot, use browser cookies. Do not proceed without cookies.
4. Start the PO token provider before downloading.
- Prefer Docker bgutil when available.
- Fall back to WPC (browser) if Docker is missing or fails.
5. Use `web_safari` when cookies are present; use `mweb` otherwise for PO tokens.
6. Keep the browser window open during WPC token minting.
7. If you see “Only images are available” or “Requested format is not available”, treat it as PO token failure and retry after fixing provider/browser state.
8. If you see SSL EOF/fragment errors, treat it as proxy instability and retry with progressive formats or a better proxy.
### Automatic Setup (Preferred for non-technical users)
If Docker is available, you can start the PO token provider automatically:
1. Install the plugin into yt-dlp's Python environment (one-time):
```bash
<YTDLP_PYTHON> -m pip install bgutil-ytdlp-pot-provider
```
In China, prefer a local PyPI mirror:
```bash
<YTDLP_PYTHON> -m pip install bgutil-ytdlp-pot-provider -i https://pypi.tuna.tsinghua.edu.cn/simple
```
2. Start the provider (Docker):
```bash
docker run -d --name bgutil-pot-provider -p 4416:4416 --init brainicism/bgutil-ytdlp-pot-provider
```
3. Retry yt-dlp downloads using a web client (e.g., `mweb`) so PO tokens apply.
### Installation
Install a PO token provider plugin to handle token generation automatically. The plugin must be installed into yt-dlp's own Python environment.
@@ -31,7 +66,7 @@ head -1 $(which yt-dlp)
```bash
# For Homebrew-installed yt-dlp (macOS)
/opt/homebrew/Cellar/yt-dlp/$(yt-dlp --version)/libexec/bin/python -m pip install bgutil-ytdlp-pot-provider
<YTDLP_PYTHON> -m pip install bgutil-ytdlp-pot-provider
# For pip-installed yt-dlp
python3 -m pip install bgutil-ytdlp-pot-provider --user
@@ -61,7 +96,19 @@ Look for high-quality formats (137, 248, 271, 313) in the output. If present, th
- **Method**: Launches browser to mint tokens
- **Best for**: Users comfortable with browser automation
### 3. yt-dlp-get-pot-rustypipe
### 3. yt-dlp-getpot-wpc (Browser-based, no Docker)
- **Installation**: `pip install yt-dlp-getpot-wpc`
- **Requires**: yt-dlp 2025.09.26 or above
- **Method**: Uses a browser window to mint tokens
- **Best for**: Environments without Docker or restricted networks
In China, prefer a local PyPI mirror:
```bash
pip install yt-dlp-getpot-wpc -i https://pypi.tuna.tsinghua.edu.cn/simple
```
### 4. yt-dlp-get-pot-rustypipe
- **Installation**: `pip install yt-dlp-get-pot-rustypipe`
- **Method**: Uses rustypipe-botguard

962
youtube-downloader/scripts/download_video.py
View File

File diff suppressed because it is too large Load Diff