Release v1.24.0: Add claude-skills-troubleshooting
- 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
@@ -5,8 +5,8 @@
|
|||||||
"email": "daymadev89@gmail.com"
|
"email": "daymadev89@gmail.com"
|
||||||
},
|
},
|
||||||
"metadata": {
|
"metadata": {
|
||||||
"description": "Professional Claude Code skills for GitHub operations, document conversion, diagram generation, statusline customization, Teams communication, repomix utilities, skill creation, CLI demo generation, LLM icon access, Cloudflare troubleshooting, UI design system extraction, professional presentation creation, YouTube video downloading, secure repomix packaging, ASR transcription correction, video comparison quality analysis, comprehensive QA testing infrastructure, prompt optimization with EARS methodology, session history recovery, documentation cleanup, PDF generation with Chinese font support, CLAUDE.md progressive disclosure optimization, CCPM skill registry search and management, Promptfoo LLM evaluation framework, iOS app development with XcodeGen and SwiftUI, fact-checking with automated corrections, Twitter/X content fetching, intelligent macOS disk space recovery, skill quality review and improvement, and GitHub contribution strategy",
|
"description": "Professional Claude Code skills for GitHub operations, document conversion, diagram generation, statusline customization, Teams communication, repomix utilities, skill creation, CLI demo generation, LLM icon access, Cloudflare troubleshooting, UI design system extraction, professional presentation creation, YouTube video downloading, secure repomix packaging, ASR transcription correction, video comparison quality analysis, comprehensive QA testing infrastructure, prompt optimization with EARS methodology, session history recovery, documentation cleanup, PDF generation with Chinese font support, CLAUDE.md progressive disclosure optimization, CCPM skill registry search and management, Promptfoo LLM evaluation framework, iOS app development with XcodeGen and SwiftUI, fact-checking with automated corrections, Twitter/X content fetching, intelligent macOS disk space recovery, skill quality review and improvement, GitHub contribution strategy, complete internationalization/localization setup, and plugin/skill troubleshooting with diagnostic tools",
|
||||||
"version": "1.22.0",
|
"version": "1.24.0",
|
||||||
"homepage": "https://github.com/daymade/claude-code-skills"
|
"homepage": "https://github.com/daymade/claude-code-skills"
|
||||||
},
|
},
|
||||||
"plugins": [
|
"plugins": [
|
||||||
@@ -619,6 +619,51 @@
|
|||||||
"skills": [
|
"skills": [
|
||||||
"./github-contributor"
|
"./github-contributor"
|
||||||
]
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "i18n-expert",
|
||||||
|
"description": "Complete internationalization/localization setup and auditing for UI codebases. Configure i18n frameworks, replace hard-coded strings with translation keys, ensure locale parity between en-US and zh-CN, and validate pluralization and formatting. Use when setting up i18n for React/Next.js/Vue apps, auditing existing implementations, replacing hard-coded strings, ensuring proper error code mapping, or validating pluralization and date/time/number formatting across locales",
|
||||||
|
"source": "./",
|
||||||
|
"strict": false,
|
||||||
|
"version": "1.0.0",
|
||||||
|
"category": "developer-tools",
|
||||||
|
"keywords": [
|
||||||
|
"i18n",
|
||||||
|
"internationalization",
|
||||||
|
"localization",
|
||||||
|
"translation",
|
||||||
|
"react-i18next",
|
||||||
|
"next-intl",
|
||||||
|
"vue-i18n",
|
||||||
|
"locale",
|
||||||
|
"multilingual",
|
||||||
|
"globalization"
|
||||||
|
],
|
||||||
|
"skills": [
|
||||||
|
"./i18n-expert"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "claude-skills-troubleshooting",
|
||||||
|
"description": "Diagnose and resolve Claude Code plugin and skill configuration issues. Debug plugin installation, enablement, and activation problems with systematic workflows. Use when plugins are installed but not showing in available skills list, skills are not activating as expected, troubleshooting enabledPlugins configuration in settings.json, debugging 'plugin not working' or 'skill not showing' issues, or understanding plugin state architecture and lifecycle",
|
||||||
|
"source": "./",
|
||||||
|
"strict": false,
|
||||||
|
"version": "1.0.0",
|
||||||
|
"category": "utilities",
|
||||||
|
"keywords": [
|
||||||
|
"troubleshooting",
|
||||||
|
"debugging",
|
||||||
|
"plugins",
|
||||||
|
"skills",
|
||||||
|
"diagnostics",
|
||||||
|
"configuration",
|
||||||
|
"enabledPlugins",
|
||||||
|
"settings",
|
||||||
|
"marketplace"
|
||||||
|
],
|
||||||
|
"skills": [
|
||||||
|
"./claude-skills-troubleshooting"
|
||||||
|
]
|
||||||
}
|
}
|
||||||
]
|
]
|
||||||
}
|
}
|
||||||
|
|||||||
51
CHANGELOG.md
51
CHANGELOG.md
@@ -10,6 +10,57 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|||||||
### Added
|
### Added
|
||||||
- None
|
- None
|
||||||
|
|
||||||
|
## [1.24.0] - 2026-01-22
|
||||||
|
|
||||||
|
### Added
|
||||||
|
- **New Skill**: claude-skills-troubleshooting - Diagnose and resolve Claude Code plugin and skill configuration issues
|
||||||
|
- Plugin installation and enablement debugging
|
||||||
|
- installed_plugins.json vs settings.json enabledPlugins diagnosis
|
||||||
|
- Marketplace cache freshness detection
|
||||||
|
- Plugin state architecture documentation
|
||||||
|
- Bundled diagnostic script (diagnose_plugins.py)
|
||||||
|
- Batch enable script for missing plugins (enable_all_plugins.py)
|
||||||
|
- Known GitHub issues tracking (#17832, #19696, #17089, #13543, #16260)
|
||||||
|
- Skills vs Commands architecture explanation
|
||||||
|
|
||||||
|
### Changed
|
||||||
|
- Updated marketplace skills count from 31 to 32
|
||||||
|
- Updated marketplace version from 1.23.0 to 1.24.0
|
||||||
|
- Updated README.md badges (skills count, version)
|
||||||
|
- Updated README.md to include claude-skills-troubleshooting in skills listing
|
||||||
|
- Updated README.zh-CN.md badges (skills count, version)
|
||||||
|
- Updated README.zh-CN.md to include claude-skills-troubleshooting in skills listing
|
||||||
|
- Updated CLAUDE.md skills count from 31 to 32
|
||||||
|
- Added claude-skills-troubleshooting use case section to README.md
|
||||||
|
- Added claude-skills-troubleshooting use case section to README.zh-CN.md
|
||||||
|
|
||||||
|
## [1.23.0] - 2026-01-22
|
||||||
|
|
||||||
|
### Added
|
||||||
|
- **New Skill**: i18n-expert - Complete internationalization/localization setup and auditing for UI codebases
|
||||||
|
- Library selection and setup (react-i18next, next-intl, vue-i18n)
|
||||||
|
- Key architecture and locale file organization (JSON, YAML, PO, XLIFF)
|
||||||
|
- Translation generation strategy (AI, professional, manual)
|
||||||
|
- Routing and language detection/switching
|
||||||
|
- SEO and metadata localization
|
||||||
|
- RTL support for applicable locales
|
||||||
|
- Key parity validation between en-US and zh-CN
|
||||||
|
- Pluralization and formatting validation
|
||||||
|
- Error code mapping to localized messages
|
||||||
|
- Bundled i18n_audit.py script for key usage extraction
|
||||||
|
- Scope inputs: framework, existing i18n state, target locales, translation quality needs
|
||||||
|
|
||||||
|
### Changed
|
||||||
|
- Updated marketplace skills count from 30 to 31
|
||||||
|
- Updated marketplace version from 1.22.0 to 1.23.0
|
||||||
|
- Updated README.md badges (skills count, version)
|
||||||
|
- Updated README.md to include i18n-expert in skills listing
|
||||||
|
- Updated README.zh-CN.md badges (skills count, version)
|
||||||
|
- Updated README.zh-CN.md to include i18n-expert in skills listing
|
||||||
|
- Updated CLAUDE.md skills count from 30 to 31
|
||||||
|
- Added i18n-expert use case section to README.md
|
||||||
|
- Added i18n-expert use case section to README.zh-CN.md
|
||||||
|
|
||||||
### Changed
|
### Changed
|
||||||
- None
|
- None
|
||||||
|
|
||||||
|
|||||||
23
CLAUDE.md
23
CLAUDE.md
@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
|
|||||||
|
|
||||||
## Repository Overview
|
## Repository Overview
|
||||||
|
|
||||||
This is a Claude Code skills marketplace containing 30 production-ready skills organized in a plugin marketplace structure. Each skill is a self-contained package that extends Claude's capabilities with specialized knowledge, workflows, and bundled resources.
|
This is a Claude Code skills marketplace containing 32 production-ready skills organized in a plugin marketplace structure. Each skill is a self-contained package that extends Claude's capabilities with specialized knowledge, workflows, and bundled resources.
|
||||||
|
|
||||||
**Essential Skill**: `skill-creator` is the most important skill in this marketplace - it's a meta-skill that enables users to create their own skills. Always recommend it first for users interested in extending Claude Code.
|
**Essential Skill**: `skill-creator` is the most important skill in this marketplace - it's a meta-skill that enables users to create their own skills. Always recommend it first for users interested in extending Claude Code.
|
||||||
|
|
||||||
@@ -134,7 +134,7 @@ Skills for public distribution must NOT contain:
|
|||||||
## Marketplace Configuration
|
## Marketplace Configuration
|
||||||
|
|
||||||
The marketplace is configured in `.claude-plugin/marketplace.json`:
|
The marketplace is configured in `.claude-plugin/marketplace.json`:
|
||||||
- Contains 30 plugins, each mapping to one skill
|
- Contains 32 plugins, each mapping to one skill
|
||||||
- Each plugin has: name, description, version, category, keywords, skills array
|
- Each plugin has: name, description, version, category, keywords, skills array
|
||||||
- Marketplace metadata: name, owner, version, homepage
|
- Marketplace metadata: name, owner, version, homepage
|
||||||
|
|
||||||
@@ -144,7 +144,7 @@ The marketplace is configured in `.claude-plugin/marketplace.json`:
|
|||||||
|
|
||||||
1. **Marketplace Version** (`.claude-plugin/marketplace.json` → `metadata.version`)
|
1. **Marketplace Version** (`.claude-plugin/marketplace.json` → `metadata.version`)
|
||||||
- Tracks the marketplace catalog as a whole
|
- Tracks the marketplace catalog as a whole
|
||||||
- Current: v1.22.0
|
- Current: v1.23.0
|
||||||
- Bump when: Adding/removing skills, major marketplace restructuring
|
- Bump when: Adding/removing skills, major marketplace restructuring
|
||||||
- Semantic versioning: MAJOR.MINOR.PATCH
|
- Semantic versioning: MAJOR.MINOR.PATCH
|
||||||
|
|
||||||
@@ -172,7 +172,7 @@ The marketplace is configured in `.claude-plugin/marketplace.json`:
|
|||||||
10. **cloudflare-troubleshooting** - API-driven Cloudflare diagnostics and debugging
|
10. **cloudflare-troubleshooting** - API-driven Cloudflare diagnostics and debugging
|
||||||
11. **ui-designer** - Design system extraction from UI mockups
|
11. **ui-designer** - Design system extraction from UI mockups
|
||||||
12. **ppt-creator** - Professional presentation creation with dual-path PPTX generation
|
12. **ppt-creator** - Professional presentation creation with dual-path PPTX generation
|
||||||
13. **youtube-downloader** - YouTube video and audio downloading with yt-dlp error handling
|
13. **youtube-downloader** - YouTube video/audio downloads with PO token handling, cookies, and proxy-aware retries
|
||||||
14. **repomix-safe-mixer** - Secure repomix packaging with automatic credential detection
|
14. **repomix-safe-mixer** - Secure repomix packaging with automatic credential detection
|
||||||
15. **transcript-fixer** - ASR/STT transcription error correction with dictionary and AI learning
|
15. **transcript-fixer** - ASR/STT transcription error correction with dictionary and AI learning
|
||||||
16. **video-comparer** - Video comparison and quality analysis with interactive HTML reports
|
16. **video-comparer** - Video comparison and quality analysis with interactive HTML reports
|
||||||
@@ -190,9 +190,24 @@ The marketplace is configured in `.claude-plugin/marketplace.json`:
|
|||||||
28. **macos-cleaner** - Intelligent macOS disk space analysis and cleanup with safety-first philosophy, risk categorization, and interactive confirmation
|
28. **macos-cleaner** - Intelligent macOS disk space analysis and cleanup with safety-first philosophy, risk categorization, and interactive confirmation
|
||||||
29. **skill-reviewer** - Reviews and improves Claude Code skills against official best practices with self-review, external review, and auto-PR modes
|
29. **skill-reviewer** - Reviews and improves Claude Code skills against official best practices with self-review, external review, and auto-PR modes
|
||||||
30. **github-contributor** - Strategic guide for becoming an effective GitHub contributor with opportunity discovery, project selection, and reputation building
|
30. **github-contributor** - Strategic guide for becoming an effective GitHub contributor with opportunity discovery, project selection, and reputation building
|
||||||
|
31. **i18n-expert** - Complete internationalization/localization setup and auditing for UI codebases with framework support, key architecture, and parity validation
|
||||||
|
32. **claude-skills-troubleshooting** - Diagnose and resolve Claude Code plugin and skill configuration issues with diagnostic scripts and architecture documentation
|
||||||
|
|
||||||
**Recommendation**: Always suggest `skill-creator` first for users interested in creating skills or extending Claude Code.
|
**Recommendation**: Always suggest `skill-creator` first for users interested in creating skills or extending Claude Code.
|
||||||
|
|
||||||
|
## YouTube Downloader SOP (Internal)
|
||||||
|
|
||||||
|
Use this SOP to avoid common yt-dlp failures and confusion:
|
||||||
|
|
||||||
|
1. Quote YouTube URLs in shell commands (zsh treats `?` as 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 cookie permission and use browser cookies.
|
||||||
|
4. Start the PO Token provider before downloading. Prefer Docker bgutil; fall back to browser-based WPC when Docker is unavailable or fails.
|
||||||
|
5. Use `web_safari` client when cookies are present; otherwise use `mweb` for PO tokens.
|
||||||
|
6. Keep the browser window open while WPC is minting tokens and make sure it can reach YouTube through the same proxy.
|
||||||
|
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 or fragment errors, treat it as proxy instability. Retry with progressive formats or switch to a more stable proxy.
|
||||||
|
|
||||||
## Python Development
|
## Python Development
|
||||||
|
|
||||||
All Python scripts in this repository:
|
All Python scripts in this repository:
|
||||||
|
|||||||
165
README.md
165
README.md
@@ -6,15 +6,15 @@
|
|||||||
[](./README.zh-CN.md)
|
[](./README.zh-CN.md)
|
||||||
|
|
||||||
[](https://opensource.org/licenses/MIT)
|
[](https://opensource.org/licenses/MIT)
|
||||||
[](https://github.com/daymade/claude-code-skills)
|
[](https://github.com/daymade/claude-code-skills)
|
||||||
[](https://github.com/daymade/claude-code-skills)
|
[](https://github.com/daymade/claude-code-skills)
|
||||||
[](https://claude.com/code)
|
[](https://claude.com/code)
|
||||||
[](./CONTRIBUTING.md)
|
[](./CONTRIBUTING.md)
|
||||||
[](https://github.com/daymade/claude-code-skills/graphs/commit-activity)
|
[](https://github.com/daymade/claude-code-skills/graphs/commit-activity)
|
||||||
|
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
Professional Claude Code skills marketplace featuring 30 production-ready skills for enhanced development workflows.
|
Professional Claude Code skills marketplace featuring 32 production-ready skills for enhanced development workflows.
|
||||||
|
|
||||||
## 📑 Table of Contents
|
## 📑 Table of Contents
|
||||||
|
|
||||||
@@ -526,12 +526,12 @@ Download YouTube videos and audio using yt-dlp with robust error handling and au
|
|||||||
- Working with YouTube content in regions with access restrictions
|
- Working with YouTube content in regions with access restrictions
|
||||||
|
|
||||||
**Key features:**
|
**Key features:**
|
||||||
- Android client workaround for nsig extraction issues (automatic)
|
- Auto PO Token provider (Docker-first, browser fallback) for high-quality access
|
||||||
|
- Browser-cookie verification for “not a bot” prompts (privacy-friendly)
|
||||||
- Audio-only download with MP3 conversion
|
- Audio-only download with MP3 conversion
|
||||||
- Format listing and custom format selection
|
- Format listing and custom format selection
|
||||||
- Output directory customization
|
- Output directory customization
|
||||||
- Network error handling for proxy/restricted environments
|
- Proxy-aware downloads for restricted environments
|
||||||
- Availability check for yt-dlp dependency
|
|
||||||
|
|
||||||
**🎬 Live Demo**
|
**🎬 Live Demo**
|
||||||
|
|
||||||
@@ -1153,7 +1153,52 @@ Recommendation: Start with 🟢 Safe items (95 GB), then review 🟡 items toget
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### 27. **skill-reviewer** - Skill Quality Review & Improvement
|
### 27. **fact-checker** - Document Fact-Checking
|
||||||
|
|
||||||
|
Verify factual claims in documents using web search and official sources, then propose corrections with user confirmation.
|
||||||
|
|
||||||
|
**When to use:**
|
||||||
|
- Fact-checking documents for accuracy
|
||||||
|
- Verifying AI model specifications and technical documentation
|
||||||
|
- Updating outdated information in documents
|
||||||
|
- Validating statistical claims and benchmarks
|
||||||
|
- Checking API capabilities and version numbers
|
||||||
|
|
||||||
|
**Key features:**
|
||||||
|
- Web search integration with authoritative sources
|
||||||
|
- AI model specification verification
|
||||||
|
- Technical documentation accuracy checks
|
||||||
|
- Statistical data validation
|
||||||
|
- Automated correction reports with user confirmation
|
||||||
|
- Supports general factual statements and technical claims
|
||||||
|
|
||||||
|
**Example usage:**
|
||||||
|
```bash
|
||||||
|
# Install the skill
|
||||||
|
claude plugin install fact-checker@daymade-skills
|
||||||
|
|
||||||
|
# Fact-check a document
|
||||||
|
"Please fact-check this section about AI model capabilities"
|
||||||
|
|
||||||
|
# Verify technical specs
|
||||||
|
"Check if these Claude model specifications are still accurate"
|
||||||
|
|
||||||
|
# Update outdated info
|
||||||
|
"Verify and update the version numbers in this documentation"
|
||||||
|
```
|
||||||
|
|
||||||
|
**🎬 Live Demo**
|
||||||
|
|
||||||
|
*Coming soon*
|
||||||
|
|
||||||
|
📚 **Documentation**: See [fact-checker/SKILL.md](./fact-checker/SKILL.md) for full workflow and claim types.
|
||||||
|
|
||||||
|
**Requirements**:
|
||||||
|
- Web search access (via Claude Code)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 28. **skill-reviewer** - Skill Quality Review & Improvement
|
||||||
|
|
||||||
Review and improve Claude Code skills against official best practices with three powerful modes.
|
Review and improve Claude Code skills against official best practices with three powerful modes.
|
||||||
|
|
||||||
@@ -1198,7 +1243,7 @@ claude plugin install skill-reviewer@daymade-skills
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### 28. **github-contributor** - GitHub Contribution Strategy
|
### 29. **github-contributor** - GitHub Contribution Strategy
|
||||||
|
|
||||||
Strategic guide for becoming an effective GitHub contributor and building your open-source reputation.
|
Strategic guide for becoming an effective GitHub contributor and building your open-source reputation.
|
||||||
|
|
||||||
@@ -1255,6 +1300,99 @@ claude plugin install github-contributor@daymade-skills
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
### 31. **i18n-expert** - Internationalization & Localization
|
||||||
|
|
||||||
|
Complete internationalization/localization setup and auditing for UI codebases. Configure i18n frameworks, replace hard-coded strings with translation keys, ensure locale parity between en-US and zh-CN, and validate pluralization and formatting.
|
||||||
|
|
||||||
|
**When to use:**
|
||||||
|
- Setting up i18n for new React/Next.js/Vue applications
|
||||||
|
- Auditing existing i18n implementations for key parity and completeness
|
||||||
|
- Replacing hard-coded strings with translation keys
|
||||||
|
- Ensuring proper error code mapping to localized messages
|
||||||
|
- Validating pluralization, date/time/number formatting across locales
|
||||||
|
- Implementing language switching and SEO metadata localization
|
||||||
|
|
||||||
|
**Key features:**
|
||||||
|
- Library selection and setup (react-i18next, next-intl, vue-i18n)
|
||||||
|
- Key architecture and locale file organization (JSON, YAML, PO, XLIFF)
|
||||||
|
- Translation generation strategy (AI, professional, manual)
|
||||||
|
- Routing and language detection/switching
|
||||||
|
- SEO and metadata localization
|
||||||
|
- RTL support for applicable locales
|
||||||
|
- Key parity validation between en-US and zh-CN
|
||||||
|
- Pluralization and formatting validation
|
||||||
|
- Error code mapping to localized messages
|
||||||
|
- Bundled i18n_audit.py script for key usage extraction
|
||||||
|
|
||||||
|
**Example usage:**
|
||||||
|
```bash
|
||||||
|
# Install the skill
|
||||||
|
claude plugin install i18n-expert@daymade-skills
|
||||||
|
|
||||||
|
# Setup i18n for a new project
|
||||||
|
"Set up i18n for my React app with English and Chinese support"
|
||||||
|
|
||||||
|
# Audit existing i18n implementation
|
||||||
|
"Audit the i18n setup and find missing translation keys"
|
||||||
|
|
||||||
|
# Replace hard-coded strings
|
||||||
|
"Replace all hard-coded strings in this component with i18n keys"
|
||||||
|
```
|
||||||
|
|
||||||
|
**🎬 Live Demo**
|
||||||
|
|
||||||
|
*Coming soon*
|
||||||
|
|
||||||
|
📚 **Documentation**: See [i18n-expert/SKILL.md](./i18n-expert/SKILL.md) for complete workflow and architecture guidance.
|
||||||
|
|
||||||
|
**Requirements**:
|
||||||
|
- **Python 3.6+** (for audit script)
|
||||||
|
- **React/Next.js/Vue** (framework-specific i18n library)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 32. **claude-skills-troubleshooting** - Plugin & Skill Troubleshooting
|
||||||
|
|
||||||
|
Diagnose and resolve Claude Code plugin and skill configuration issues. Debug plugin installation, enablement, and activation problems with systematic workflows.
|
||||||
|
|
||||||
|
**When to use:**
|
||||||
|
- Plugins installed but not showing in available skills list
|
||||||
|
- Skills not activating as expected despite installation
|
||||||
|
- Troubleshooting enabledPlugins configuration in settings.json
|
||||||
|
- Debugging "plugin not working" or "skill not showing" issues
|
||||||
|
- Understanding plugin state architecture and lifecycle
|
||||||
|
|
||||||
|
**Key features:**
|
||||||
|
- Quick diagnosis via diagnostic script (detects installed vs enabled mismatch)
|
||||||
|
- Plugin state architecture documentation (installed_plugins.json vs settings.json)
|
||||||
|
- Marketplace cache freshness detection and update guidance
|
||||||
|
- Known GitHub issues tracking (#17832, #19696, #17089, #13543, #16260)
|
||||||
|
- Batch enable script for missing plugins from a marketplace
|
||||||
|
- Skills vs Commands architecture explanation
|
||||||
|
- Comprehensive diagnostic commands reference
|
||||||
|
|
||||||
|
**Example usage:**
|
||||||
|
```bash
|
||||||
|
# Install the skill
|
||||||
|
claude plugin install claude-skills-troubleshooting@daymade-skills
|
||||||
|
|
||||||
|
# Run diagnostic
|
||||||
|
python3 scripts/diagnose_plugins.py
|
||||||
|
|
||||||
|
# Batch enable missing plugins
|
||||||
|
python3 scripts/enable_all_plugins.py daymade-skills
|
||||||
|
```
|
||||||
|
|
||||||
|
**🎬 Live Demo**
|
||||||
|
|
||||||
|
*Coming soon*
|
||||||
|
|
||||||
|
📚 **Documentation**: See [claude-skills-troubleshooting/SKILL.md](./claude-skills-troubleshooting/SKILL.md) for complete troubleshooting workflow and architecture guidance.
|
||||||
|
|
||||||
|
**Requirements**: None (uses Claude Code built-in Python)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## 🎬 Interactive Demo Gallery
|
## 🎬 Interactive Demo Gallery
|
||||||
|
|
||||||
Want to see all demos in one place with click-to-enlarge functionality? Check out our [interactive demo gallery](./demos/index.html) or browse the [demos directory](./demos/).
|
Want to see all demos in one place with click-to-enlarge functionality? Check out our [interactive demo gallery](./demos/index.html) or browse the [demos directory](./demos/).
|
||||||
@@ -1324,6 +1462,12 @@ Use **twitter-reader** to fetch tweet content without JavaScript rendering or au
|
|||||||
### For Skill Quality & Open-Source Contributions
|
### For Skill Quality & Open-Source Contributions
|
||||||
Use **skill-reviewer** to validate your own skills against best practices before publishing, or to review and improve others' skill repositories. Combine with **github-contributor** to find high-impact open-source projects, create professional PRs, and build your contributor reputation. Perfect for developers who want to contribute to the Claude Code ecosystem or any GitHub project systematically.
|
Use **skill-reviewer** to validate your own skills against best practices before publishing, or to review and improve others' skill repositories. Combine with **github-contributor** to find high-impact open-source projects, create professional PRs, and build your contributor reputation. Perfect for developers who want to contribute to the Claude Code ecosystem or any GitHub project systematically.
|
||||||
|
|
||||||
|
### For Internationalization & Localization
|
||||||
|
Use **i18n-expert** to set up complete i18n infrastructure for React/Next.js/Vue applications, audit existing implementations for missing translation keys, and ensure locale parity between en-US and zh-CN. Perfect for teams launching products to global markets, maintaining multi-language UIs, or replacing hard-coded strings with proper i18n keys. Combine with **skill-creator** to create locale-aware skills, or with **docs-cleaner** to consolidate documentation across multiple languages.
|
||||||
|
|
||||||
|
### For Plugin & Skill Troubleshooting
|
||||||
|
Use **claude-skills-troubleshooting** to diagnose and resolve Claude Code plugin and skill configuration issues. Debug why plugins appear installed but don't show in available skills, understand the installed_plugins.json vs settings.json enabledPlugins architecture, and batch-enable missing plugins from a marketplace. Essential for marketplace maintainers debugging installation issues, developers troubleshooting skill activation, or anyone confused by the GitHub #17832 auto-enable bug.
|
||||||
|
|
||||||
## 📚 Documentation
|
## 📚 Documentation
|
||||||
|
|
||||||
Each skill includes:
|
Each skill includes:
|
||||||
@@ -1363,6 +1507,9 @@ Each skill includes:
|
|||||||
- **macos-cleaner**: See `macos-cleaner/references/cleanup_targets.md` for detailed cleanup target explanations, `macos-cleaner/references/mole_integration.md` for Mole visual tool integration, and `macos-cleaner/references/safety_rules.md` for comprehensive safety guidelines
|
- **macos-cleaner**: See `macos-cleaner/references/cleanup_targets.md` for detailed cleanup target explanations, `macos-cleaner/references/mole_integration.md` for Mole visual tool integration, and `macos-cleaner/references/safety_rules.md` for comprehensive safety guidelines
|
||||||
- **skill-reviewer**: See `skill-reviewer/references/evaluation_checklist.md` for complete evaluation criteria, `skill-reviewer/references/pr_template.md` for PR templates, and `skill-reviewer/references/marketplace_template.json` for marketplace configuration
|
- **skill-reviewer**: See `skill-reviewer/references/evaluation_checklist.md` for complete evaluation criteria, `skill-reviewer/references/pr_template.md` for PR templates, and `skill-reviewer/references/marketplace_template.json` for marketplace configuration
|
||||||
- **github-contributor**: See `github-contributor/references/pr_checklist.md` for PR quality checklist, `github-contributor/references/project_evaluation.md` for project evaluation criteria, and `github-contributor/references/communication_templates.md` for issue/PR templates
|
- **github-contributor**: See `github-contributor/references/pr_checklist.md` for PR quality checklist, `github-contributor/references/project_evaluation.md` for project evaluation criteria, and `github-contributor/references/communication_templates.md` for issue/PR templates
|
||||||
|
- **i18n-expert**: See `i18n-expert/SKILL.md` for complete i18n setup workflow, key architecture guidance, and audit procedures
|
||||||
|
- **claude-skills-troubleshooting**: See `claude-skills-troubleshooting/SKILL.md` for plugin troubleshooting workflow and architecture
|
||||||
|
- **fact-checker**: See `fact-checker/SKILL.md` for fact-checking workflow and claim verification process
|
||||||
|
|
||||||
## 🛠️ Requirements
|
## 🛠️ Requirements
|
||||||
|
|
||||||
@@ -1467,4 +1614,4 @@ If you find these skills useful, please:
|
|||||||
|
|
||||||
**Built with ❤️ using the skill-creator skill for Claude Code**
|
**Built with ❤️ using the skill-creator skill for Claude Code**
|
||||||
|
|
||||||
Last updated: 2026-01-15 | Marketplace version 1.22.0
|
Last updated: 2026-01-22 | Marketplace version 1.23.0
|
||||||
|
|||||||
167
README.zh-CN.md
167
README.zh-CN.md
@@ -6,15 +6,15 @@
|
|||||||
[](./README.zh-CN.md)
|
[](./README.zh-CN.md)
|
||||||
|
|
||||||
[](https://opensource.org/licenses/MIT)
|
[](https://opensource.org/licenses/MIT)
|
||||||
[](https://github.com/daymade/claude-code-skills)
|
[](https://github.com/daymade/claude-code-skills)
|
||||||
[](https://github.com/daymade/claude-code-skills)
|
[](https://github.com/daymade/claude-code-skills)
|
||||||
[](https://claude.com/code)
|
[](https://claude.com/code)
|
||||||
[](./CONTRIBUTING.md)
|
[](./CONTRIBUTING.md)
|
||||||
[](https://github.com/daymade/claude-code-skills/graphs/commit-activity)
|
[](https://github.com/daymade/claude-code-skills/graphs/commit-activity)
|
||||||
|
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
专业的 Claude Code 技能市场，提供 30 个生产就绪的技能，用于增强开发工作流。
|
专业的 Claude Code 技能市场，提供 32 个生产就绪的技能，用于增强开发工作流。
|
||||||
|
|
||||||
## 📑 目录
|
## 📑 目录
|
||||||
|
|
||||||
@@ -561,12 +561,12 @@ CC-Switch 支持以下中国 AI 服务提供商：
|
|||||||
- 在受限环境中下载视频
|
- 在受限环境中下载视频
|
||||||
|
|
||||||
**主要功能：**
|
**主要功能：**
|
||||||
- 视频和播放列表下载
|
- 自动 PO Token 提供器（优先 Docker，失败自动切换浏览器方案）
|
||||||
|
- 通过浏览器 Cookie 处理“不是机器人”验证（更友好）
|
||||||
- 仅音频下载并转换为 MP3
|
- 仅音频下载并转换为 MP3
|
||||||
- Android 客户端绕过 nsig 提取问题（自动）
|
|
||||||
- 格式列表和自定义格式选择
|
- 格式列表和自定义格式选择
|
||||||
- 代理/受限环境的网络错误处理
|
- 输出目录自定义
|
||||||
- 常见 yt-dlp 问题的综合故障排除
|
- 代理/受限环境的下载支持
|
||||||
|
|
||||||
**示例用法：**
|
**示例用法：**
|
||||||
```bash
|
```bash
|
||||||
@@ -1195,7 +1195,52 @@ claude plugin install macos-cleaner@daymade-skills
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### 27. **skill-reviewer** - 技能质量审查与改进
|
### 27. **fact-checker** - 文档事实核查
|
||||||
|
|
||||||
|
使用网络搜索和权威来源验证文档中的事实声明，然后提议更正并等待用户确认。
|
||||||
|
|
||||||
|
**使用场景：**
|
||||||
|
- 核实文档准确性
|
||||||
|
- 验证 AI 模型规格和技术文档
|
||||||
|
- 更新文档中的过时信息
|
||||||
|
- 验证统计声明和基准测试
|
||||||
|
- 检查 API 功能和版本号
|
||||||
|
|
||||||
|
**主要功能：**
|
||||||
|
- 集成权威来源的网络搜索
|
||||||
|
- AI 模型规格验证
|
||||||
|
- 技术文档准确性检查
|
||||||
|
- 统计数据验证
|
||||||
|
- 自动更正报告（需用户确认）
|
||||||
|
- 支持一般事实声明和技术声明
|
||||||
|
|
||||||
|
**示例用法：**
|
||||||
|
```bash
|
||||||
|
# 安装技能
|
||||||
|
claude plugin install fact-checker@daymade-skills
|
||||||
|
|
||||||
|
# 核实文档
|
||||||
|
"请核查这部分关于 AI 模型功能的内容"
|
||||||
|
|
||||||
|
# 验证技术规格
|
||||||
|
"检查这些 Claude 模型规格是否仍然准确"
|
||||||
|
|
||||||
|
# 更新过时信息
|
||||||
|
"验证并更新此文档中的版本号"
|
||||||
|
```
|
||||||
|
|
||||||
|
**🎬 实时演示**
|
||||||
|
|
||||||
|
*即将推出*
|
||||||
|
|
||||||
|
📚 **文档**：参见 [fact-checker/SKILL.md](./fact-checker/SKILL.md) 了解完整的工作流程和声明类型。
|
||||||
|
|
||||||
|
**要求**：
|
||||||
|
- 网络搜索访问（通过 Claude Code）
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 28. **skill-reviewer** - 技能质量审查与改进
|
||||||
|
|
||||||
以三种强大模式审查和改进 Claude Code 技能，确保符合官方最佳实践。
|
以三种强大模式审查和改进 Claude Code 技能，确保符合官方最佳实践。
|
||||||
|
|
||||||
@@ -1240,7 +1285,7 @@ claude plugin install skill-reviewer@daymade-skills
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### 28. **github-contributor** - GitHub 贡献策略
|
### 29. **github-contributor** - GitHub 贡献策略
|
||||||
|
|
||||||
成为高效 GitHub 贡献者并建立开源声誉的战略指南。
|
成为高效 GitHub 贡献者并建立开源声誉的战略指南。
|
||||||
|
|
||||||
@@ -1297,6 +1342,99 @@ claude plugin install github-contributor@daymade-skills
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
### 31. **i18n-expert** - 国际化与本地化
|
||||||
|
|
||||||
|
为 UI 代码库提供完整的国际化/本地化设置和审计。配置 i18n 框架、将硬编码字符串替换为翻译键、确保 en-US 和 zh-CN 之间的语言环境一致性，并验证复数形式和格式设置。
|
||||||
|
|
||||||
|
**使用场景：**
|
||||||
|
- 为新的 React/Next.js/Vue 应用程序设置 i18n
|
||||||
|
- 审计现有 i18n 实现的键一致性和完整性
|
||||||
|
- 将硬编码字符串替换为翻译键
|
||||||
|
- 确保错误代码正确映射到本地化消息
|
||||||
|
- 验证跨语言环境的复数形式、日期/时间/数字格式设置
|
||||||
|
- 实现语言切换和 SEO 元数据本地化
|
||||||
|
|
||||||
|
**主要功能：**
|
||||||
|
- 库选择和设置（react-i18next、next-intl、vue-i18n）
|
||||||
|
- 键架构和语言环境文件组织（JSON、YAML、PO、XLIFF）
|
||||||
|
- 翻译生成策略（AI、专业、手动）
|
||||||
|
- 路由和语言检测/切换
|
||||||
|
- SEO 和元数据本地化
|
||||||
|
- 适用语言环境的 RTL 支持
|
||||||
|
- en-US 和 zh-CN 之间的键一致性验证
|
||||||
|
- 复数形式和格式设置验证
|
||||||
|
- 错误代码映射到本地化消息
|
||||||
|
- 捆绑的 i18n_audit.py 脚本用于键使用提取
|
||||||
|
|
||||||
|
**示例用法：**
|
||||||
|
```bash
|
||||||
|
# 安装技能
|
||||||
|
claude plugin install i18n-expert@daymade-skills
|
||||||
|
|
||||||
|
# 为新项目设置 i18n
|
||||||
|
"为我的 React 应用设置支持英文和中文的 i18n"
|
||||||
|
|
||||||
|
# 审计现有 i18n 实现
|
||||||
|
"审计 i18n 设置并查找缺失的翻译键"
|
||||||
|
|
||||||
|
# 替换硬编码字符串
|
||||||
|
"将此组件中的所有硬编码字符串替换为 i18n 键"
|
||||||
|
```
|
||||||
|
|
||||||
|
**🎬 实时演示**
|
||||||
|
|
||||||
|
*即将推出*
|
||||||
|
|
||||||
|
📚 **文档**：参见 [i18n-expert/SKILL.md](./i18n-expert/SKILL.md) 了解完整的工作流程和架构指导。
|
||||||
|
|
||||||
|
**要求**：
|
||||||
|
- **Python 3.6+**（用于审计脚本）
|
||||||
|
- **React/Next.js/Vue**（框架特定的 i18n 库）
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 32. **claude-skills-troubleshooting** - 插件与技能故障排除
|
||||||
|
|
||||||
|
诊断和解决 Claude Code 插件和技能配置问题。通过系统化工作流程调试插件安装、启用和激活问题。
|
||||||
|
|
||||||
|
**使用场景：**
|
||||||
|
- 插件已安装但未显示在可用技能列表中
|
||||||
|
- 尽管已安装，技能仍未按预期激活
|
||||||
|
- 调试 settings.json 中的 enabledPlugins 配置
|
||||||
|
- 调试"插件不工作"或"技能未显示"问题
|
||||||
|
- 了解插件状态架构和生命周期
|
||||||
|
|
||||||
|
**主要功能：**
|
||||||
|
- 通过诊断脚本快速诊断（检测已安装但未启用的不匹配）
|
||||||
|
- 插件状态架构文档（installed_plugins.json vs settings.json）
|
||||||
|
- 市场缓存新鲜度检测和更新指导
|
||||||
|
- 已知 GitHub 问题跟踪（#17832、#19696、#17089、#13543、#16260）
|
||||||
|
- 用于批量启用市场缺失插件的脚本
|
||||||
|
- 技能与命令架构解释
|
||||||
|
- 全面的诊断命令参考
|
||||||
|
|
||||||
|
**示例用法：**
|
||||||
|
```bash
|
||||||
|
# 安装技能
|
||||||
|
claude plugin install claude-skills-troubleshooting@daymade-skills
|
||||||
|
|
||||||
|
# 运行诊断
|
||||||
|
python3 scripts/diagnose_plugins.py
|
||||||
|
|
||||||
|
# 批量启用缺失的插件
|
||||||
|
python3 scripts/enable_all_plugins.py daymade-skills
|
||||||
|
```
|
||||||
|
|
||||||
|
**🎬 实时演示**
|
||||||
|
|
||||||
|
*即将推出*
|
||||||
|
|
||||||
|
📚 **文档**：参见 [claude-skills-troubleshooting/SKILL.md](./claude-skills-troubleshooting/SKILL.md) 了解完整的故障排除工作流程和架构指导。
|
||||||
|
|
||||||
|
**要求**：无（使用 Claude Code 内置 Python）
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## 🎬 交互式演示画廊
|
## 🎬 交互式演示画廊
|
||||||
|
|
||||||
想要在一个地方查看所有演示并具有点击放大功能？访问我们的[交互式演示画廊](./demos/index.html)或浏览[演示目录](./demos/)。
|
想要在一个地方查看所有演示并具有点击放大功能？访问我们的[交互式演示画廊](./demos/index.html)或浏览[演示目录](./demos/)。
|
||||||
@@ -1366,6 +1504,12 @@ claude plugin install github-contributor@daymade-skills
|
|||||||
### 技能质量与开源贡献
|
### 技能质量与开源贡献
|
||||||
使用 **skill-reviewer** 在发布前验证你的技能是否符合最佳实践，或审查并改进他人的技能仓库。与 **github-contributor** 结合使用，寻找高影响力的开源项目、创建专业的 PR，并系统性地建立贡献者声誉。非常适合希望为 Claude Code 生态系统或任何 GitHub 项目做出贡献的开发者。
|
使用 **skill-reviewer** 在发布前验证你的技能是否符合最佳实践，或审查并改进他人的技能仓库。与 **github-contributor** 结合使用，寻找高影响力的开源项目、创建专业的 PR，并系统性地建立贡献者声誉。非常适合希望为 Claude Code 生态系统或任何 GitHub 项目做出贡献的开发者。
|
||||||
|
|
||||||
|
### 国际化与本地化
|
||||||
|
使用 **i18n-expert** 为 React/Next.js/Vue 应用程序设置完整的 i18n 基础设施、审计现有实现中缺失的翻译键，并确保 en-US 和 zh-CN 之间的语言环境一致性。非常适合向全球市场推出产品的团队、维护多语言 UI，或将硬编码字符串替换为正确的 i18n 键。与 **skill-creator** 结合使用可创建支持语言环境的技能，或与 **docs-cleaner** 结合使用可整合多种语言的文档。
|
||||||
|
|
||||||
|
### 插件与技能故障排除
|
||||||
|
使用 **claude-skills-troubleshooting** 诊断和解决 Claude Code 插件和技能配置问题。调试为什么插件显示已安装但未显示在可用技能列表中、了解 installed_plugins.json 与 settings.json enabledPlugins 架构，以及批量启用市场中缺失的插件。非常适合市场维护者调试安装问题、开发者调试技能激活，或任何对 GitHub #17832 自动启用 bug 感到困惑的人。
|
||||||
|
|
||||||
## 📚 文档
|
## 📚 文档
|
||||||
|
|
||||||
每个技能包括：
|
每个技能包括：
|
||||||
@@ -1405,6 +1549,9 @@ claude plugin install github-contributor@daymade-skills
|
|||||||
- **macos-cleaner**：参见 `macos-cleaner/references/cleanup_targets.md` 了解详细清理目标说明、`macos-cleaner/references/mole_integration.md` 了解 Mole 可视化工具集成、`macos-cleaner/references/safety_rules.md` 了解全面安全指南
|
- **macos-cleaner**：参见 `macos-cleaner/references/cleanup_targets.md` 了解详细清理目标说明、`macos-cleaner/references/mole_integration.md` 了解 Mole 可视化工具集成、`macos-cleaner/references/safety_rules.md` 了解全面安全指南
|
||||||
- **skill-reviewer**：参见 `skill-reviewer/references/evaluation_checklist.md` 了解完整评估标准、`skill-reviewer/references/pr_template.md` 了解 PR 模板、`skill-reviewer/references/marketplace_template.json` 了解 marketplace 配置
|
- **skill-reviewer**：参见 `skill-reviewer/references/evaluation_checklist.md` 了解完整评估标准、`skill-reviewer/references/pr_template.md` 了解 PR 模板、`skill-reviewer/references/marketplace_template.json` 了解 marketplace 配置
|
||||||
- **github-contributor**：参见 `github-contributor/references/pr_checklist.md` 了解 PR 质量清单、`github-contributor/references/project_evaluation.md` 了解项目评估标准、`github-contributor/references/communication_templates.md` 了解 issue/PR 沟通模板
|
- **github-contributor**：参见 `github-contributor/references/pr_checklist.md` 了解 PR 质量清单、`github-contributor/references/project_evaluation.md` 了解项目评估标准、`github-contributor/references/communication_templates.md` 了解 issue/PR 沟通模板
|
||||||
|
- **i18n-expert**：参见 `i18n-expert/SKILL.md` 了解完整的 i18n 设置工作流程、键架构指导和审计程序
|
||||||
|
- **claude-skills-troubleshooting**：参见 `claude-skills-troubleshooting/SKILL.md` 了解插件故障排除工作流程和架构
|
||||||
|
- **fact-checker**：参见 `fact-checker/SKILL.md` 了解事实核查工作流程和声明验证过程
|
||||||
|
|
||||||
## 🛠️ 系统要求
|
## 🛠️ 系统要求
|
||||||
|
|
||||||
@@ -1506,4 +1653,4 @@ claude plugin install skill-name@daymade-skills
|
|||||||
|
|
||||||
**使用 skill-creator 技能为 Claude Code 精心打造 ❤️**
|
**使用 skill-creator 技能为 Claude Code 精心打造 ❤️**
|
||||||
|
|
||||||
最后更新：2026-01-15 | 市场版本 1.22.0
|
最后更新：2026-01-22 | 市场版本 1.23.0
|
||||||
|
|||||||
148
claude-skills-troubleshooting/SKILL.md
Normal file
148
claude-skills-troubleshooting/SKILL.md
Normal file
@@ -0,0 +1,148 @@
|
|||||||
|
---
|
||||||
|
name: claude-skills-troubleshooting
|
||||||
|
description: Diagnose and resolve Claude Code plugin and skill issues. This skill should be used when plugins are installed but not showing in available skills list, skills are not activating as expected, or when troubleshooting enabledPlugins configuration in settings.json. Triggers include "plugin not working", "skill not showing", "installed but disabled", or "enabledPlugins" issues.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Claude Skills Troubleshooting
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
Diagnose and resolve common Claude Code plugin and skill configuration issues. This skill provides systematic debugging workflows for plugin installation, enablement, and activation problems.
|
||||||
|
|
||||||
|
## Quick Diagnosis
|
||||||
|
|
||||||
|
Run the diagnostic script to identify common issues:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python3 scripts/diagnose_plugins.py
|
||||||
|
```
|
||||||
|
|
||||||
|
The script checks:
|
||||||
|
- Installed vs enabled plugins mismatch
|
||||||
|
- Missing enabledPlugins entries in settings.json
|
||||||
|
- Stale marketplace cache
|
||||||
|
- Invalid plugin configurations
|
||||||
|
|
||||||
|
## Common Issues
|
||||||
|
|
||||||
|
### Issue 1: Plugin Installed But Not Showing in Available Skills
|
||||||
|
|
||||||
|
**Symptoms:**
|
||||||
|
- `/plugin` shows plugin as installed
|
||||||
|
- Skill not appearing in Skill tool's available list
|
||||||
|
- Plugin metadata exists in `installed_plugins.json`
|
||||||
|
|
||||||
|
**Root Cause:** Known bug ([GitHub #17832](https://github.com/anthropics/claude-code/issues/17832)) - plugins are added to `installed_plugins.json` but NOT automatically added to `enabledPlugins` in `settings.json`.
|
||||||
|
|
||||||
|
**Diagnosis:**
|
||||||
|
```bash
|
||||||
|
# Check if plugin is in installed_plugins.json
|
||||||
|
cat ~/.claude/plugins/installed_plugins.json | grep "plugin-name"
|
||||||
|
|
||||||
|
# Check if plugin is enabled in settings.json
|
||||||
|
cat ~/.claude/settings.json | grep "plugin-name"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Solution:**
|
||||||
|
```bash
|
||||||
|
# Option 1: Use CLI to enable
|
||||||
|
claude plugin enable plugin-name@marketplace-name
|
||||||
|
|
||||||
|
# Option 2: Manually edit settings.json
|
||||||
|
# Add to enabledPlugins section:
|
||||||
|
# "plugin-name@marketplace-name": true
|
||||||
|
```
|
||||||
|
|
||||||
|
### Issue 2: Understanding Plugin State Architecture
|
||||||
|
|
||||||
|
**Key files:**
|
||||||
|
|
||||||
|
| File | Purpose |
|
||||||
|
|------|---------|
|
||||||
|
| `~/.claude/plugins/installed_plugins.json` | Registry of ALL plugins (installed + disabled) |
|
||||||
|
| `~/.claude/settings.json` → `enabledPlugins` | Controls which plugins are ACTIVE |
|
||||||
|
| `~/.claude/plugins/known_marketplaces.json` | Registered marketplace sources |
|
||||||
|
| `~/.claude/plugins/cache/` | Actual plugin files |
|
||||||
|
|
||||||
|
**A plugin is active ONLY when:**
|
||||||
|
1. Exists in `installed_plugins.json` (registered)
|
||||||
|
2. Listed in `settings.json` → `enabledPlugins` with value `true`
|
||||||
|
|
||||||
|
### Issue 3: Marketplace Cache Stale
|
||||||
|
|
||||||
|
**Symptoms:**
|
||||||
|
- GitHub has latest changes
|
||||||
|
- Install finds plugin but gets old version
|
||||||
|
- Newly added plugins not visible
|
||||||
|
|
||||||
|
**Solution:**
|
||||||
|
```bash
|
||||||
|
# Update marketplace cache
|
||||||
|
claude plugin marketplace update marketplace-name
|
||||||
|
|
||||||
|
# Or clear and re-fetch
|
||||||
|
rm -rf ~/.claude/plugins/cache/marketplace-name
|
||||||
|
claude plugin marketplace update marketplace-name
|
||||||
|
```
|
||||||
|
|
||||||
|
### Issue 4: Plugin Not Found in Marketplace
|
||||||
|
|
||||||
|
**Common causes (in order of likelihood):**
|
||||||
|
|
||||||
|
1. **Local changes not pushed to GitHub** - Most common!
|
||||||
|
```bash
|
||||||
|
git status
|
||||||
|
git push
|
||||||
|
claude plugin marketplace update marketplace-name
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **marketplace.json configuration error**
|
||||||
|
```bash
|
||||||
|
python3 -m json.tool .claude-plugin/marketplace.json
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Skill directory missing**
|
||||||
|
```bash
|
||||||
|
ls -la skill-name/SKILL.md
|
||||||
|
```
|
||||||
|
|
||||||
|
## Diagnostic Commands Reference
|
||||||
|
|
||||||
|
| Purpose | Command |
|
||||||
|
|---------|---------|
|
||||||
|
| List marketplaces | `claude plugin marketplace list` |
|
||||||
|
| Update marketplace | `claude plugin marketplace update {name}` |
|
||||||
|
| Install plugin | `claude plugin install {plugin}@{marketplace}` |
|
||||||
|
| Enable plugin | `claude plugin enable {plugin}@{marketplace}` |
|
||||||
|
| Disable plugin | `claude plugin disable {plugin}@{marketplace}` |
|
||||||
|
| Uninstall plugin | `claude plugin uninstall {plugin}@{marketplace}` |
|
||||||
|
| Check installed | `cat ~/.claude/plugins/installed_plugins.json \| jq '.plugins \| keys'` |
|
||||||
|
| Check enabled | `cat ~/.claude/settings.json \| jq '.enabledPlugins'` |
|
||||||
|
|
||||||
|
## Batch Enable Missing Plugins
|
||||||
|
|
||||||
|
To enable all installed but disabled plugins from a marketplace:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python3 scripts/enable_all_plugins.py marketplace-name
|
||||||
|
```
|
||||||
|
|
||||||
|
## Skills vs Commands Architecture
|
||||||
|
|
||||||
|
Claude Code has two types of user-invocable extensions:
|
||||||
|
|
||||||
|
1. **Skills** (in `skills/` directory)
|
||||||
|
- Auto-activated based on description matching
|
||||||
|
- Loaded when user request matches skill description
|
||||||
|
|
||||||
|
2. **Commands** (in `commands/` directory)
|
||||||
|
- Explicitly invocable via `/command-name`
|
||||||
|
- Appears in Skill tool's available list
|
||||||
|
- Requires command file (e.g., `commands/seer.md`)
|
||||||
|
|
||||||
|
If a skill should be explicitly invocable, add a corresponding command file.
|
||||||
|
|
||||||
|
## References
|
||||||
|
|
||||||
|
- See `references/known_issues.md` for GitHub issue tracking
|
||||||
|
- See `references/architecture.md` for detailed plugin architecture
|
||||||
198
claude-skills-troubleshooting/references/architecture.md
Normal file
198
claude-skills-troubleshooting/references/architecture.md
Normal file
@@ -0,0 +1,198 @@
|
|||||||
|
# Claude Code Plugin Architecture
|
||||||
|
|
||||||
|
## Directory Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
~/.claude/
|
||||||
|
├── settings.json # User settings including enabledPlugins
|
||||||
|
├── plugins/
|
||||||
|
│ ├── installed_plugins.json # Registry of ALL plugins (enabled + disabled)
|
||||||
|
│ ├── known_marketplaces.json # Registered marketplace sources
|
||||||
|
│ ├── marketplaces/ # Marketplace git clones
|
||||||
|
│ │ ├── marketplace-name/
|
||||||
|
│ │ │ └── .claude-plugin/
|
||||||
|
│ │ │ └── marketplace.json # Plugin definitions
|
||||||
|
│ │ └── ...
|
||||||
|
│ └── cache/ # Installed plugin files
|
||||||
|
│ └── marketplace-name/
|
||||||
|
│ └── plugin-name/
|
||||||
|
│ └── version/
|
||||||
|
│ └── skill-name/
|
||||||
|
│ ├── SKILL.md
|
||||||
|
│ ├── scripts/
|
||||||
|
│ └── references/
|
||||||
|
└── skills/ # Personal skills (not from marketplace)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Plugin Lifecycle
|
||||||
|
|
||||||
|
### Installation Flow
|
||||||
|
|
||||||
|
```
|
||||||
|
1. User runs: claude plugin install plugin@marketplace
|
||||||
|
↓
|
||||||
|
2. CLI reads marketplace.json from marketplace directory
|
||||||
|
↓
|
||||||
|
3. Plugin files copied to cache:
|
||||||
|
~/.claude/plugins/cache/marketplace/plugin/version/
|
||||||
|
↓
|
||||||
|
4. Entry added to installed_plugins.json:
|
||||||
|
{ "plugin@marketplace": [{ "version": "1.0.0", ... }] }
|
||||||
|
↓
|
||||||
|
5. ⚠️ BUG: Entry NOT automatically added to settings.json enabledPlugins
|
||||||
|
↓
|
||||||
|
6. User must manually enable:
|
||||||
|
claude plugin enable plugin@marketplace
|
||||||
|
↓
|
||||||
|
7. Entry added to settings.json:
|
||||||
|
{ "enabledPlugins": { "plugin@marketplace": true } }
|
||||||
|
```
|
||||||
|
|
||||||
|
### Activation Flow
|
||||||
|
|
||||||
|
```
|
||||||
|
1. Claude Code starts
|
||||||
|
↓
|
||||||
|
2. Reads settings.json → enabledPlugins
|
||||||
|
↓
|
||||||
|
3. For each enabled plugin:
|
||||||
|
- Loads skill metadata (name + description)
|
||||||
|
- Metadata added to system prompt
|
||||||
|
↓
|
||||||
|
4. User sends message
|
||||||
|
↓
|
||||||
|
5. Claude matches message against skill descriptions
|
||||||
|
↓
|
||||||
|
6. Matching skill's SKILL.md loaded into context
|
||||||
|
↓
|
||||||
|
7. Claude uses skill instructions to respond
|
||||||
|
```
|
||||||
|
|
||||||
|
## Key Files Explained
|
||||||
|
|
||||||
|
### installed_plugins.json
|
||||||
|
|
||||||
|
**Purpose:** Registry of all plugins ever installed (NOT just active ones).
|
||||||
|
|
||||||
|
**Structure:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"version": 2,
|
||||||
|
"plugins": {
|
||||||
|
"plugin-name@marketplace": [
|
||||||
|
{
|
||||||
|
"scope": "user",
|
||||||
|
"installPath": "~/.claude/plugins/cache/...",
|
||||||
|
"version": "1.0.0",
|
||||||
|
"installedAt": "2025-01-01T00:00:00.000Z"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Note:** A plugin listed here is NOT necessarily active. Check `settings.json` for actual enabled state.
|
||||||
|
|
||||||
|
### settings.json
|
||||||
|
|
||||||
|
**Purpose:** User preferences and enabled plugins.
|
||||||
|
|
||||||
|
**Relevant section:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"enabledPlugins": {
|
||||||
|
"plugin-name@marketplace": true,
|
||||||
|
"another-plugin@marketplace": true
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Important:** Only plugins with `true` value are loaded at startup.
|
||||||
|
|
||||||
|
### known_marketplaces.json
|
||||||
|
|
||||||
|
**Purpose:** Registry of marketplace sources.
|
||||||
|
|
||||||
|
**Structure:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"marketplace-name": {
|
||||||
|
"source": {
|
||||||
|
"source": "github",
|
||||||
|
"repo": "owner/repo"
|
||||||
|
},
|
||||||
|
"installLocation": "~/.claude/plugins/marketplaces/marketplace-name",
|
||||||
|
"lastUpdated": "2025-01-01T00:00:00.000Z"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### marketplace.json (in marketplace repo)
|
||||||
|
|
||||||
|
**Purpose:** Defines available plugins in a marketplace.
|
||||||
|
|
||||||
|
**Location:** `.claude-plugin/marketplace.json`
|
||||||
|
|
||||||
|
**Structure:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"name": "marketplace-name",
|
||||||
|
"metadata": {
|
||||||
|
"version": "1.0.0",
|
||||||
|
"description": "..."
|
||||||
|
},
|
||||||
|
"plugins": [
|
||||||
|
{
|
||||||
|
"name": "plugin-name",
|
||||||
|
"description": "...",
|
||||||
|
"version": "1.0.0",
|
||||||
|
"skills": ["./skill-directory"]
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Plugin vs Skill vs Command
|
||||||
|
|
||||||
|
### Plugin
|
||||||
|
|
||||||
|
- Distribution unit that packages one or more skills
|
||||||
|
- Defined in marketplace.json
|
||||||
|
- Installed via `claude plugin install`
|
||||||
|
|
||||||
|
### Skill
|
||||||
|
|
||||||
|
- Functional unit with SKILL.md and optional resources
|
||||||
|
- Auto-activates based on description matching
|
||||||
|
- Located in `skills/` directory
|
||||||
|
|
||||||
|
### Command
|
||||||
|
|
||||||
|
- Explicit slash command (e.g., `/seer`)
|
||||||
|
- Defined in `commands/` directory
|
||||||
|
- Appears in Skill tool's available list
|
||||||
|
- Must be explicitly invoked by user
|
||||||
|
|
||||||
|
## Scopes
|
||||||
|
|
||||||
|
Plugins can be installed in different scopes:
|
||||||
|
|
||||||
|
| Scope | Location | Visibility |
|
||||||
|
|-------|----------|------------|
|
||||||
|
| user | `~/.claude/settings.json` | All projects for current user |
|
||||||
|
| project | `.claude/settings.json` | Team members via git |
|
||||||
|
| local | `.claude/settings.local.json` | Only local machine |
|
||||||
|
|
||||||
|
## Common Misconceptions
|
||||||
|
|
||||||
|
1. **installed_plugins.json = active plugins**
|
||||||
|
- Reality: It's a registry of ALL plugins, including disabled ones
|
||||||
|
|
||||||
|
2. **Plugins auto-enable after install**
|
||||||
|
- Reality: Bug prevents auto-enable; manual step required
|
||||||
|
|
||||||
|
3. **Updating local files updates the plugin**
|
||||||
|
- Reality: Must push to GitHub, then update marketplace cache
|
||||||
|
|
||||||
|
4. **Cache is just for performance**
|
||||||
|
- Reality: Cache IS where plugins live; deleting it uninstalls plugins
|
||||||
72
claude-skills-troubleshooting/references/known_issues.md
Normal file
72
claude-skills-troubleshooting/references/known_issues.md
Normal file
@@ -0,0 +1,72 @@
|
|||||||
|
# Known Claude Code Plugin Issues
|
||||||
|
|
||||||
|
This document tracks known bugs and issues related to Claude Code plugins.
|
||||||
|
|
||||||
|
## Open Issues
|
||||||
|
|
||||||
|
### GitHub #17832 - Plugins Not Auto-Enabled After Install
|
||||||
|
|
||||||
|
**Status:** OPEN
|
||||||
|
**URL:** https://github.com/anthropics/claude-code/issues/17832
|
||||||
|
|
||||||
|
**Problem:** When installing a plugin from a marketplace, Claude Code adds the plugin to `installed_plugins.json` but does NOT add it to `settings.json` `enabledPlugins`.
|
||||||
|
|
||||||
|
**Impact:** Plugins appear "installed" but don't function. Skills silently fail to load.
|
||||||
|
|
||||||
|
**Workaround:** Manually enable via CLI or edit settings.json:
|
||||||
|
```bash
|
||||||
|
claude plugin enable plugin-name@marketplace
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### GitHub #19696 - installed_plugins.json Naming Misleading
|
||||||
|
|
||||||
|
**Status:** OPEN
|
||||||
|
**URL:** https://github.com/anthropics/claude-code/issues/19696
|
||||||
|
|
||||||
|
**Problem:** The file `installed_plugins.json` contains ALL plugins ever registered, including disabled ones. The actual enabled state is tracked separately in `settings.json`.
|
||||||
|
|
||||||
|
**Impact:** Confusing for developers - file shows many plugins but only some are active.
|
||||||
|
|
||||||
|
**Note:** This is a naming/documentation issue, not a functional bug.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### GitHub #17089 - Local Plugins Breaking After 2.1.x Update
|
||||||
|
|
||||||
|
**Status:** Reported
|
||||||
|
**URL:** https://github.com/anthropics/claude-code/issues/17089
|
||||||
|
|
||||||
|
**Problem:** Local plugins no longer persist after the 2.1.x update.
|
||||||
|
|
||||||
|
**Workaround:** Create a marketplace wrapper structure for local plugins.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### GitHub #13543 - MCP Servers from Marketplace Not Available
|
||||||
|
|
||||||
|
**Status:** Reported
|
||||||
|
**URL:** https://github.com/anthropics/claude-code/issues/13543
|
||||||
|
|
||||||
|
**Problem:** After updating to Claude Code 2.0.64, MCP servers defined in marketplace plugins were no longer available.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### GitHub #16260 - Contradictory Scope Error Messages
|
||||||
|
|
||||||
|
**Status:** Reported
|
||||||
|
**URL:** https://github.com/anthropics/claude-code/issues/16260
|
||||||
|
|
||||||
|
**Problem:** CLI gives contradictory error messages about plugin scope.
|
||||||
|
|
||||||
|
**Workaround:** Manually edit settings.json to fix scope issues.
|
||||||
|
|
||||||
|
## Resolved Issues
|
||||||
|
|
||||||
|
(Add resolved issues here as they are fixed)
|
||||||
|
|
||||||
|
## Related Documentation
|
||||||
|
|
||||||
|
- [Plugins Reference](https://code.claude.com/docs/en/plugins-reference)
|
||||||
|
- [Claude Code Settings](https://code.claude.com/docs/en/settings)
|
||||||
182
claude-skills-troubleshooting/scripts/diagnose_plugins.py
Executable file
182
claude-skills-troubleshooting/scripts/diagnose_plugins.py
Executable file
@@ -0,0 +1,182 @@
|
|||||||
|
#!/usr/bin/env python3
|
||||||
|
"""
|
||||||
|
Diagnose Claude Code plugin and skill configuration issues.
|
||||||
|
|
||||||
|
This script checks for common problems:
|
||||||
|
- Installed plugins not enabled in settings.json
|
||||||
|
- Stale marketplace cache
|
||||||
|
- Missing plugin files
|
||||||
|
- Configuration inconsistencies
|
||||||
|
"""
|
||||||
|
|
||||||
|
import json
|
||||||
|
import os
|
||||||
|
from pathlib import Path
|
||||||
|
from datetime import datetime
|
||||||
|
|
||||||
|
|
||||||
|
def get_claude_dir():
|
||||||
|
"""Get the Claude configuration directory."""
|
||||||
|
return Path.home() / ".claude"
|
||||||
|
|
||||||
|
|
||||||
|
def load_json_file(path):
|
||||||
|
"""Load a JSON file, return None if not found."""
|
||||||
|
try:
|
||||||
|
with open(path, 'r') as f:
|
||||||
|
return json.load(f)
|
||||||
|
except (FileNotFoundError, json.JSONDecodeError) as e:
|
||||||
|
return None
|
||||||
|
|
||||||
|
|
||||||
|
def check_installed_plugins():
|
||||||
|
"""Check installed_plugins.json."""
|
||||||
|
claude_dir = get_claude_dir()
|
||||||
|
installed_path = claude_dir / "plugins" / "installed_plugins.json"
|
||||||
|
|
||||||
|
data = load_json_file(installed_path)
|
||||||
|
if not data:
|
||||||
|
print("❌ Cannot read installed_plugins.json")
|
||||||
|
return {}
|
||||||
|
|
||||||
|
plugins = data.get("plugins", {})
|
||||||
|
print(f"📦 Found {len(plugins)} registered plugins in installed_plugins.json")
|
||||||
|
return plugins
|
||||||
|
|
||||||
|
|
||||||
|
def check_enabled_plugins():
|
||||||
|
"""Check enabledPlugins in settings.json."""
|
||||||
|
claude_dir = get_claude_dir()
|
||||||
|
settings_path = claude_dir / "settings.json"
|
||||||
|
|
||||||
|
data = load_json_file(settings_path)
|
||||||
|
if not data:
|
||||||
|
print("❌ Cannot read settings.json")
|
||||||
|
return {}
|
||||||
|
|
||||||
|
enabled = data.get("enabledPlugins", {})
|
||||||
|
enabled_count = sum(1 for v in enabled.values() if v)
|
||||||
|
print(f"✅ Found {enabled_count} enabled plugins in settings.json")
|
||||||
|
return enabled
|
||||||
|
|
||||||
|
|
||||||
|
def check_marketplaces():
|
||||||
|
"""Check registered marketplaces."""
|
||||||
|
claude_dir = get_claude_dir()
|
||||||
|
marketplaces_path = claude_dir / "plugins" / "known_marketplaces.json"
|
||||||
|
|
||||||
|
data = load_json_file(marketplaces_path)
|
||||||
|
if not data:
|
||||||
|
print("❌ Cannot read known_marketplaces.json")
|
||||||
|
return {}
|
||||||
|
|
||||||
|
print(f"🏪 Found {len(data)} registered marketplaces:")
|
||||||
|
for name, info in data.items():
|
||||||
|
last_updated = info.get("lastUpdated", "unknown")
|
||||||
|
print(f" - {name} (updated: {last_updated[:10] if len(last_updated) > 10 else last_updated})")
|
||||||
|
return data
|
||||||
|
|
||||||
|
|
||||||
|
def find_missing_enabled(installed, enabled):
|
||||||
|
"""Find plugins that are installed but not enabled."""
|
||||||
|
missing = []
|
||||||
|
|
||||||
|
for plugin_name in installed.keys():
|
||||||
|
if plugin_name not in enabled or not enabled.get(plugin_name):
|
||||||
|
missing.append(plugin_name)
|
||||||
|
|
||||||
|
return missing
|
||||||
|
|
||||||
|
|
||||||
|
def check_cache_freshness(marketplaces):
|
||||||
|
"""Check if marketplace caches are stale."""
|
||||||
|
claude_dir = get_claude_dir()
|
||||||
|
cache_dir = claude_dir / "plugins" / "cache"
|
||||||
|
|
||||||
|
stale = []
|
||||||
|
for name, info in marketplaces.items():
|
||||||
|
marketplace_cache = cache_dir / name
|
||||||
|
if marketplace_cache.exists():
|
||||||
|
# Check modification time
|
||||||
|
mtime = datetime.fromtimestamp(marketplace_cache.stat().st_mtime)
|
||||||
|
age_days = (datetime.now() - mtime).days
|
||||||
|
if age_days > 7:
|
||||||
|
stale.append((name, age_days))
|
||||||
|
|
||||||
|
return stale
|
||||||
|
|
||||||
|
|
||||||
|
def main():
|
||||||
|
print("=" * 60)
|
||||||
|
print("Claude Code Plugin Diagnostics")
|
||||||
|
print("=" * 60)
|
||||||
|
print()
|
||||||
|
|
||||||
|
# Check installed plugins
|
||||||
|
installed = check_installed_plugins()
|
||||||
|
print()
|
||||||
|
|
||||||
|
# Check enabled plugins
|
||||||
|
enabled = check_enabled_plugins()
|
||||||
|
print()
|
||||||
|
|
||||||
|
# Check marketplaces
|
||||||
|
marketplaces = check_marketplaces()
|
||||||
|
print()
|
||||||
|
|
||||||
|
# Find missing enabled
|
||||||
|
missing = find_missing_enabled(installed, enabled)
|
||||||
|
if missing:
|
||||||
|
print("=" * 60)
|
||||||
|
print(f"⚠️ WARNING: {len(missing)} plugins installed but NOT enabled!")
|
||||||
|
print("=" * 60)
|
||||||
|
print()
|
||||||
|
print("These plugins exist in installed_plugins.json but are missing")
|
||||||
|
print("from enabledPlugins in settings.json:")
|
||||||
|
print()
|
||||||
|
for plugin in sorted(missing):
|
||||||
|
print(f" - {plugin}")
|
||||||
|
print()
|
||||||
|
print("To enable, run:")
|
||||||
|
print(" claude plugin enable <plugin-name>")
|
||||||
|
print()
|
||||||
|
print("Or add to ~/.claude/settings.json under enabledPlugins:")
|
||||||
|
print(' "plugin-name@marketplace": true')
|
||||||
|
print()
|
||||||
|
else:
|
||||||
|
print("✅ All installed plugins are enabled!")
|
||||||
|
print()
|
||||||
|
|
||||||
|
# Check cache freshness
|
||||||
|
stale = check_cache_freshness(marketplaces)
|
||||||
|
if stale:
|
||||||
|
print("=" * 60)
|
||||||
|
print("⚠️ Stale marketplace caches detected:")
|
||||||
|
print("=" * 60)
|
||||||
|
for name, days in stale:
|
||||||
|
print(f" - {name}: {days} days old")
|
||||||
|
print()
|
||||||
|
print("To update, run:")
|
||||||
|
print(" claude plugin marketplace update <marketplace-name>")
|
||||||
|
print()
|
||||||
|
|
||||||
|
# Summary
|
||||||
|
print("=" * 60)
|
||||||
|
print("Summary")
|
||||||
|
print("=" * 60)
|
||||||
|
print(f" Registered plugins: {len(installed)}")
|
||||||
|
print(f" Enabled plugins: {sum(1 for v in enabled.values() if v)}")
|
||||||
|
print(f" Missing enabled: {len(missing)}")
|
||||||
|
print(f" Marketplaces: {len(marketplaces)}")
|
||||||
|
print()
|
||||||
|
|
||||||
|
if missing:
|
||||||
|
print("🔧 Action needed: Enable missing plugins to make them available")
|
||||||
|
return 1
|
||||||
|
else:
|
||||||
|
print("✅ No issues detected!")
|
||||||
|
return 0
|
||||||
|
|
||||||
|
|
||||||
|
if __name__ == "__main__":
|
||||||
|
exit(main())
|
||||||
102
claude-skills-troubleshooting/scripts/enable_all_plugins.py
Executable file
102
claude-skills-troubleshooting/scripts/enable_all_plugins.py
Executable file
@@ -0,0 +1,102 @@
|
|||||||
|
#!/usr/bin/env python3
|
||||||
|
"""
|
||||||
|
Enable all installed but disabled plugins from a specific marketplace.
|
||||||
|
|
||||||
|
Usage:
|
||||||
|
python3 enable_all_plugins.py <marketplace-name>
|
||||||
|
|
||||||
|
Example:
|
||||||
|
python3 enable_all_plugins.py daymade-skills
|
||||||
|
"""
|
||||||
|
|
||||||
|
import json
|
||||||
|
import sys
|
||||||
|
from pathlib import Path
|
||||||
|
|
||||||
|
|
||||||
|
def get_claude_dir():
|
||||||
|
"""Get the Claude configuration directory."""
|
||||||
|
return Path.home() / ".claude"
|
||||||
|
|
||||||
|
|
||||||
|
def load_json_file(path):
|
||||||
|
"""Load a JSON file."""
|
||||||
|
with open(path, 'r') as f:
|
||||||
|
return json.load(f)
|
||||||
|
|
||||||
|
|
||||||
|
def save_json_file(path, data):
|
||||||
|
"""Save data to a JSON file."""
|
||||||
|
with open(path, 'w') as f:
|
||||||
|
json.dump(data, f, indent=2)
|
||||||
|
|
||||||
|
|
||||||
|
def main():
|
||||||
|
if len(sys.argv) < 2:
|
||||||
|
print("Usage: python3 enable_all_plugins.py <marketplace-name>")
|
||||||
|
print("Example: python3 enable_all_plugins.py daymade-skills")
|
||||||
|
return 1
|
||||||
|
|
||||||
|
marketplace = sys.argv[1]
|
||||||
|
claude_dir = get_claude_dir()
|
||||||
|
|
||||||
|
# Load installed plugins
|
||||||
|
installed_path = claude_dir / "plugins" / "installed_plugins.json"
|
||||||
|
try:
|
||||||
|
installed_data = load_json_file(installed_path)
|
||||||
|
except FileNotFoundError:
|
||||||
|
print(f"❌ Cannot find {installed_path}")
|
||||||
|
return 1
|
||||||
|
|
||||||
|
# Load settings
|
||||||
|
settings_path = claude_dir / "settings.json"
|
||||||
|
try:
|
||||||
|
settings = load_json_file(settings_path)
|
||||||
|
except FileNotFoundError:
|
||||||
|
print(f"❌ Cannot find {settings_path}")
|
||||||
|
return 1
|
||||||
|
|
||||||
|
# Get current enabled plugins
|
||||||
|
enabled = settings.get("enabledPlugins", {})
|
||||||
|
|
||||||
|
# Find plugins from the specified marketplace
|
||||||
|
plugins_to_enable = []
|
||||||
|
for plugin_name in installed_data.get("plugins", {}).keys():
|
||||||
|
if plugin_name.endswith(f"@{marketplace}"):
|
||||||
|
if plugin_name not in enabled or not enabled[plugin_name]:
|
||||||
|
plugins_to_enable.append(plugin_name)
|
||||||
|
|
||||||
|
if not plugins_to_enable:
|
||||||
|
print(f"✅ All plugins from {marketplace} are already enabled!")
|
||||||
|
return 0
|
||||||
|
|
||||||
|
print(f"Found {len(plugins_to_enable)} plugins to enable from {marketplace}:")
|
||||||
|
for plugin in sorted(plugins_to_enable):
|
||||||
|
print(f" - {plugin}")
|
||||||
|
|
||||||
|
# Confirm
|
||||||
|
print()
|
||||||
|
response = input("Enable all these plugins? [y/N] ")
|
||||||
|
if response.lower() != 'y':
|
||||||
|
print("Cancelled.")
|
||||||
|
return 0
|
||||||
|
|
||||||
|
# Enable plugins
|
||||||
|
if "enabledPlugins" not in settings:
|
||||||
|
settings["enabledPlugins"] = {}
|
||||||
|
|
||||||
|
for plugin in plugins_to_enable:
|
||||||
|
settings["enabledPlugins"][plugin] = True
|
||||||
|
|
||||||
|
# Save settings
|
||||||
|
save_json_file(settings_path, settings)
|
||||||
|
|
||||||
|
print()
|
||||||
|
print(f"✅ Enabled {len(plugins_to_enable)} plugins!")
|
||||||
|
print()
|
||||||
|
print("⚠️ Restart Claude Code for changes to take effect.")
|
||||||
|
return 0
|
||||||
|
|
||||||
|
|
||||||
|
if __name__ == "__main__":
|
||||||
|
exit(main())
|
||||||
4
i18n-expert/.security-scan-passed
Normal file
4
i18n-expert/.security-scan-passed
Normal file
@@ -0,0 +1,4 @@
|
|||||||
|
Security scan passed
|
||||||
|
Scanned at: 2026-01-22T21:40:43.577494
|
||||||
|
Tool: gitleaks + pattern-based validation
|
||||||
|
Content hash: 45d5d760e2e39bb19208667a84307dca17a9ee85e1a6b07accc664adf6c45a94
|
||||||
128
i18n-expert/SKILL.md
Normal file
128
i18n-expert/SKILL.md
Normal file
@@ -0,0 +1,128 @@
|
|||||||
|
---
|
||||||
|
name: i18n-expert
|
||||||
|
description: This skill should be used when setting up, auditing, or enforcing internationalization/localization in UI codebases (React/TS, i18next or similar, JSON locales), including installing/configuring the i18n framework, replacing hard-coded strings, ensuring en-US/zh-CN coverage, mapping error codes to localized messages, and validating key parity, pluralization, and formatting.
|
||||||
|
---
|
||||||
|
|
||||||
|
# I18n Expert
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
Deliver a complete i18n setup + audit pass: configure the i18n framework, replace user-facing strings with keys, ensure locale parity, and validate pluralization/formatting for en-US and zh-CN.
|
||||||
|
|
||||||
|
## Core Capabilities
|
||||||
|
|
||||||
|
- Library selection and setup (React, Next.js, Vue).
|
||||||
|
- Key architecture and locale file organization.
|
||||||
|
- Translation generation and quality strategy (AI, professional, manual).
|
||||||
|
- Routing and language detection/switching.
|
||||||
|
- SEO and metadata localization (when applicable).
|
||||||
|
- RTL support (only if RTL locales are in scope).
|
||||||
|
|
||||||
|
## Scope Inputs (ask if unclear)
|
||||||
|
|
||||||
|
- Framework and routing style.
|
||||||
|
- Existing i18n state (none, partial, legacy).
|
||||||
|
- Target locales (default: en-US + zh-CN).
|
||||||
|
- Translation quality needs (AI vs professional vs manual).
|
||||||
|
- Locale formats in use (JSON, YAML, PO, XLIFF).
|
||||||
|
- Formality/cultural requirements (if any).
|
||||||
|
|
||||||
|
## Workflow (Audit -> Fix -> Validate)
|
||||||
|
|
||||||
|
1) Confirm scope and locale targets
|
||||||
|
- Identify the i18n framework and locale locations.
|
||||||
|
- Confirm locales; default to en-US + zh-CN when specified.
|
||||||
|
|
||||||
|
2) Setup i18n baseline (if missing)
|
||||||
|
- Choose a framework-appropriate library (e.g., React: react-i18next; Next.js: next-intl; Vue: vue-i18n).
|
||||||
|
- Install packages and create the i18n entry/config file.
|
||||||
|
- Wire the provider at the app root and load locale resources.
|
||||||
|
- Add a language switcher and persistence (route/param/localStorage) as appropriate.
|
||||||
|
- Establish locale file layout and key namespaces.
|
||||||
|
- If routing is locale-aware, define the locale segment strategy early (subpath, subdomain, query param).
|
||||||
|
- If metadata is user-facing, include translation for titles/descriptions.
|
||||||
|
|
||||||
|
3) Audit key usage and locale parity
|
||||||
|
- Run:
|
||||||
|
```bash
|
||||||
|
python scripts/i18n_audit.py --src <src-root> --locale <path/to/en-US.json> --locale <path/to/zh-CN.json>
|
||||||
|
```
|
||||||
|
- Treat missing keys/parity gaps as blockers.
|
||||||
|
- Manually verify dynamic keys (`t(var)`).
|
||||||
|
|
||||||
|
4) Find raw user-facing strings
|
||||||
|
- Search:
|
||||||
|
```bash
|
||||||
|
rg -n --glob '<src>/**/*.{ts,tsx,js,jsx}' "<[^>]+>[^<{]*[A-Za-z][^<{]*<"
|
||||||
|
rg -n --glob '<src>/**/*.{ts,tsx,js,jsx}' "aria-label=\"[^\"]+\"|title=\"[^\"]+\"|placeholder=\"[^\"]+\""
|
||||||
|
```
|
||||||
|
- Localize accessibility labels.
|
||||||
|
|
||||||
|
5) Replace strings with keys
|
||||||
|
- Use `t('namespace.key')` for UI text.
|
||||||
|
- For plurals use `t('key', { count })` + `_one/_other` keys.
|
||||||
|
- Use Intl/app formatters for time/date/number.
|
||||||
|
|
||||||
|
6) Localize error handling (critical)
|
||||||
|
- Map error codes to localized keys; show localized UI only.
|
||||||
|
- Log raw error details only.
|
||||||
|
- Provide localized fallback for unknown codes.
|
||||||
|
|
||||||
|
7) Update locale files
|
||||||
|
- Add missing keys in both locales.
|
||||||
|
- Keep placeholders consistent; avoid renames unless requested.
|
||||||
|
- Generate translations using the agreed method; preserve placeholders and plural rules.
|
||||||
|
|
||||||
|
8) Validate
|
||||||
|
- Re-run the audit until missing/parity issues are zero.
|
||||||
|
- Validate JSON (e.g., `python -m json.tool <file>`).
|
||||||
|
- Update tests asserting visible text.
|
||||||
|
|
||||||
|
## Guardrails
|
||||||
|
|
||||||
|
- Never expose raw `error.message` to UI; show localized strings only.
|
||||||
|
- Do not add extra locales unless explicitly requested.
|
||||||
|
- Prefer structured namespaces (e.g., `errors.*`, `buttons.*`, `workspace.*`).
|
||||||
|
- Keep translations concise and consistent.
|
||||||
|
- Some technical/brand terms should remain untranslated (e.g., product name, API, MCP, Bash).
|
||||||
|
|
||||||
|
## Deliverables (expected outputs)
|
||||||
|
|
||||||
|
- i18n config/provider wiring.
|
||||||
|
- Locale files for each target language.
|
||||||
|
- Replaced UI strings with stable keys.
|
||||||
|
- Language switcher and persistence (if applicable).
|
||||||
|
- Updated tests for visible text.
|
||||||
|
|
||||||
|
## Architecture Guidance (keep concise)
|
||||||
|
|
||||||
|
- Key structure: prefer nested namespaces by area (e.g., `common.buttons.save`, `pricing.tier.pro`).
|
||||||
|
- File layout: one file per locale or per-locale namespaces; keep keys in sync across locales.
|
||||||
|
- Placeholders: preserve `{name}`/`{{name}}` exactly; validate plurals by locale rules.
|
||||||
|
- Formatting: use Intl/app helpers for date, time, number, and list formatting.
|
||||||
|
- SEO/metadata: localize titles and descriptions if the app exposes them.
|
||||||
|
- RTL: only needed for RTL locales; use logical CSS properties and test layout.
|
||||||
|
- Non-web surfaces (Electron main-process dialogs, CLI prompts, native menus) need localization too.
|
||||||
|
|
||||||
|
## Performance Notes (short)
|
||||||
|
|
||||||
|
- Lazy-load locale bundles when the app supports it.
|
||||||
|
- Split large locale files by namespace.
|
||||||
|
|
||||||
|
## Failure Modes (watchlist)
|
||||||
|
|
||||||
|
- Missing translations: fall back to default locale and log warnings.
|
||||||
|
- RTL layout issues: verify logical CSS and test pages.
|
||||||
|
- SEO missing: ensure alternates and metadata are localized when applicable.
|
||||||
|
|
||||||
|
## Validation Checklist (short)
|
||||||
|
|
||||||
|
- No missing keys and no raw UI strings.
|
||||||
|
- Locale switching works and persists.
|
||||||
|
- Plurals and formatting verified in both locales.
|
||||||
|
- Fallback locale configured.
|
||||||
|
|
||||||
|
## Resources
|
||||||
|
|
||||||
|
### scripts/
|
||||||
|
- `scripts/i18n_audit.py`: Extracts `t('key')` usage and compares against locale JSON files.
|
||||||
163
i18n-expert/scripts/i18n_audit.py
Normal file
163
i18n-expert/scripts/i18n_audit.py
Normal file
@@ -0,0 +1,163 @@
|
|||||||
|
#!/usr/bin/env python3
|
||||||
|
"""Audit i18n key usage vs locale JSON files.
|
||||||
|
|
||||||
|
Usage:
|
||||||
|
python scripts/i18n_audit.py --src ./src --locale ./locales/en-US/common.json --locale ./locales/zh-CN/common.json
|
||||||
|
"""
|
||||||
|
|
||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
import argparse
|
||||||
|
import json
|
||||||
|
import re
|
||||||
|
import sys
|
||||||
|
from pathlib import Path
|
||||||
|
from typing import Dict, Iterable, List, Set
|
||||||
|
|
||||||
|
KEY_PATTERNS = [
|
||||||
|
re.compile(r"(?<![\w.])t\(\s*['\"]([^'\"]+)['\"]"),
|
||||||
|
re.compile(r"\bi18n\.t\(\s*['\"]([^'\"]+)['\"]"),
|
||||||
|
re.compile(r"\bi18next\.t\(\s*['\"]([^'\"]+)['\"]"),
|
||||||
|
]
|
||||||
|
|
||||||
|
PLURAL_SUFFIXES = ("_zero", "_one", "_two", "_few", "_many", "_other")
|
||||||
|
|
||||||
|
|
||||||
|
def iter_source_files(root: Path, exts: Iterable[str]) -> Iterable[Path]:
|
||||||
|
for path in root.rglob("*"):
|
||||||
|
if path.is_dir():
|
||||||
|
continue
|
||||||
|
if "node_modules" in path.parts or ".git" in path.parts:
|
||||||
|
continue
|
||||||
|
if path.suffix.lstrip(".") in exts:
|
||||||
|
yield path
|
||||||
|
|
||||||
|
|
||||||
|
def extract_keys(paths: Iterable[Path]) -> Set[str]:
|
||||||
|
keys: Set[str] = set()
|
||||||
|
for path in paths:
|
||||||
|
try:
|
||||||
|
text = path.read_text(encoding="utf-8")
|
||||||
|
except UnicodeDecodeError:
|
||||||
|
continue
|
||||||
|
for pattern in KEY_PATTERNS:
|
||||||
|
for match in pattern.finditer(text):
|
||||||
|
keys.add(match.group(1))
|
||||||
|
return keys
|
||||||
|
|
||||||
|
|
||||||
|
def flatten_json(obj, prefix: str = "") -> Dict[str, object]:
|
||||||
|
keys: Dict[str, object] = {}
|
||||||
|
if isinstance(obj, dict):
|
||||||
|
for key, value in obj.items():
|
||||||
|
path = f"{prefix}.{key}" if prefix else key
|
||||||
|
keys.update(flatten_json(value, path))
|
||||||
|
else:
|
||||||
|
keys[prefix] = obj
|
||||||
|
return keys
|
||||||
|
|
||||||
|
|
||||||
|
def locale_name(path: Path) -> str:
|
||||||
|
name = path.stem
|
||||||
|
if path.name in {"common.json", "translation.json", "messages.json"}:
|
||||||
|
parent = path.parent.name
|
||||||
|
if parent:
|
||||||
|
return parent
|
||||||
|
return name
|
||||||
|
|
||||||
|
|
||||||
|
def has_plural_variant(key: str, key_set: Set[str]) -> bool:
|
||||||
|
return any(f"{key}{suffix}" in key_set for suffix in PLURAL_SUFFIXES)
|
||||||
|
|
||||||
|
|
||||||
|
def load_locale(path: Path) -> Set[str]:
|
||||||
|
with path.open(encoding="utf-8") as handle:
|
||||||
|
data = json.load(handle)
|
||||||
|
return set(flatten_json(data).keys())
|
||||||
|
|
||||||
|
|
||||||
|
def compute_missing(used: Set[str], locale_keys: Set[str]) -> List[str]:
|
||||||
|
missing = []
|
||||||
|
for key in sorted(used):
|
||||||
|
if key in locale_keys:
|
||||||
|
continue
|
||||||
|
if has_plural_variant(key, locale_keys):
|
||||||
|
continue
|
||||||
|
missing.append(key)
|
||||||
|
return missing
|
||||||
|
|
||||||
|
|
||||||
|
def main() -> int:
|
||||||
|
parser = argparse.ArgumentParser(description="Audit i18n keys against locale JSON files.")
|
||||||
|
parser.add_argument("--src", default=".", help="Source root to scan")
|
||||||
|
parser.add_argument(
|
||||||
|
"--locale",
|
||||||
|
action="append",
|
||||||
|
required=True,
|
||||||
|
help="Path to locale JSON (repeatable)",
|
||||||
|
)
|
||||||
|
parser.add_argument(
|
||||||
|
"--ext",
|
||||||
|
action="append",
|
||||||
|
default=["ts", "tsx", "js", "jsx"],
|
||||||
|
help="File extensions to scan (repeatable)",
|
||||||
|
)
|
||||||
|
parser.add_argument("--json", action="store_true", help="Emit JSON output")
|
||||||
|
args = parser.parse_args()
|
||||||
|
|
||||||
|
src_root = Path(args.src).resolve()
|
||||||
|
locale_paths = [Path(p).resolve() for p in args.locale]
|
||||||
|
|
||||||
|
source_files = list(iter_source_files(src_root, args.ext))
|
||||||
|
used_keys = extract_keys(source_files)
|
||||||
|
|
||||||
|
locale_key_map: Dict[str, Set[str]] = {}
|
||||||
|
for path in locale_paths:
|
||||||
|
locale_key_map[locale_name(path)] = load_locale(path)
|
||||||
|
|
||||||
|
missing_by_locale = {
|
||||||
|
name: compute_missing(used_keys, keys) for name, keys in locale_key_map.items()
|
||||||
|
}
|
||||||
|
|
||||||
|
unused_by_locale = {
|
||||||
|
name: sorted(keys - used_keys) for name, keys in locale_key_map.items()
|
||||||
|
}
|
||||||
|
|
||||||
|
parity_missing: Dict[str, List[str]] = {}
|
||||||
|
locale_names = list(locale_key_map.keys())
|
||||||
|
for name in locale_names:
|
||||||
|
other_names = [n for n in locale_names if n != name]
|
||||||
|
other_keys = set().union(*(locale_key_map[n] for n in other_names))
|
||||||
|
parity_missing[name] = sorted(other_keys - locale_key_map[name])
|
||||||
|
|
||||||
|
output = {
|
||||||
|
"used_keys": sorted(used_keys),
|
||||||
|
"missing_by_locale": missing_by_locale,
|
||||||
|
"unused_by_locale": unused_by_locale,
|
||||||
|
"parity_missing": parity_missing,
|
||||||
|
}
|
||||||
|
|
||||||
|
if args.json:
|
||||||
|
json.dump(output, sys.stdout, indent=2, ensure_ascii=False)
|
||||||
|
sys.stdout.write("\n")
|
||||||
|
return 0
|
||||||
|
|
||||||
|
print(f"Scanned {len(source_files)} files")
|
||||||
|
print(f"Used keys: {len(used_keys)}")
|
||||||
|
for name in locale_names:
|
||||||
|
missing = missing_by_locale[name]
|
||||||
|
unused = unused_by_locale[name]
|
||||||
|
parity = parity_missing[name]
|
||||||
|
print(f"\nLocale: {name}")
|
||||||
|
print(f" Missing: {len(missing)}")
|
||||||
|
for key in missing[:50]:
|
||||||
|
print(f" - {key}")
|
||||||
|
if len(missing) > 50:
|
||||||
|
print(" ...")
|
||||||
|
print(f" Unused: {len(unused)}")
|
||||||
|
print(f" Parity missing: {len(parity)}")
|
||||||
|
return 0
|
||||||
|
|
||||||
|
|
||||||
|
if __name__ == "__main__":
|
||||||
|
raise SystemExit(main())
|
||||||
@@ -12,6 +12,95 @@ Enable reliable video and audio downloads from YouTube and HLS streaming platfor
|
|||||||
- HLS stream downloads with authentication headers
|
- HLS stream downloads with authentication headers
|
||||||
- Handling protected content and troubleshooting common download failures
|
- 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: ``.
|
||||||
|
|
||||||
|
**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):**
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
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
|
## When to Use This Skill
|
||||||
|
|
||||||
This skill should be invoked when users:
|
This skill should be invoked when users:
|
||||||
@@ -27,7 +116,7 @@ This skill should be invoked when users:
|
|||||||
|
|
||||||
## Prerequisites
|
## Prerequisites
|
||||||
|
|
||||||
### 1. Verify yt-dlp Installation
|
### 1. Verify yt-dlp Installation (Run this yourself)
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
which yt-dlp
|
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.
|
**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:
|
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:
|
For 1080p/1440p/4K access, install a PO token provider plugin into yt-dlp's Python environment:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Find yt-dlp's Python path
|
# Find yt-dlp's Python path (interpreter used by yt-dlp)
|
||||||
head -1 $(which yt-dlp)
|
head -1 $(which yt-dlp)
|
||||||
|
|
||||||
# Install plugin (adjust path to match yt-dlp version)
|
# Install plugin using the interpreter from the line above
|
||||||
/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
|
||||||
```
|
```
|
||||||
|
|
||||||
**Verification**: Run `yt-dlp -F "VIDEO_URL"` again. Look for formats 137 (1080p), 271 (1440p), or 313 (4K).
|
**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.
|
**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
|
## Common Tasks
|
||||||
|
|
||||||
### Audio-Only Download
|
### Audio-Only Download (Run this yourself)
|
||||||
|
|
||||||
Extract audio as MP3:
|
Extract audio as MP3:
|
||||||
|
|
||||||
@@ -123,25 +215,25 @@ Extract audio as MP3:
|
|||||||
yt-dlp -x --audio-format mp3 "VIDEO_URL"
|
yt-dlp -x --audio-format mp3 "VIDEO_URL"
|
||||||
```
|
```
|
||||||
|
|
||||||
### Custom Output Directory
|
### Custom Output Directory (Run this yourself)
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
yt-dlp -P ~/Downloads/YouTube "VIDEO_URL"
|
yt-dlp -P ~/Downloads/YouTube "VIDEO_URL"
|
||||||
```
|
```
|
||||||
|
|
||||||
### Download with Subtitles
|
### Download with Subtitles (Run this yourself)
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
yt-dlp --write-subs --sub-lang en "VIDEO_URL"
|
yt-dlp --write-subs --sub-lang en "VIDEO_URL"
|
||||||
```
|
```
|
||||||
|
|
||||||
### Playlist Download
|
### Playlist Download (Run this yourself)
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
yt-dlp -f "bestvideo[height<=1080]+bestaudio/best" "PLAYLIST_URL"
|
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:
|
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)
|
2. Install PO token provider (see Step 1 above)
|
||||||
3. Or use browser cookies method
|
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
|
### nsig Extraction Failed
|
||||||
|
|
||||||
**Symptoms**:
|
**Symptoms**:
|
||||||
@@ -183,7 +293,16 @@ WARNING: [youtube] nsig extraction failed: Some formats may be missing
|
|||||||
**Solution**:
|
**Solution**:
|
||||||
1. Update yt-dlp to latest version
|
1. Update yt-dlp to latest version
|
||||||
2. Install PO token provider
|
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
|
### Slow Downloads or Network Errors
|
||||||
|
|
||||||
@@ -204,7 +323,7 @@ WARNING: android client https formats require a GVS PO Token
|
|||||||
|
|
||||||
### scripts/download_video.py
|
### 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:**
|
**Basic usage:**
|
||||||
```bash
|
```bash
|
||||||
@@ -214,20 +333,34 @@ scripts/download_video.py "VIDEO_URL"
|
|||||||
**Arguments:**
|
**Arguments:**
|
||||||
- `url` - YouTube video URL (required)
|
- `url` - YouTube video URL (required)
|
||||||
- `-o, --output-dir` - Output directory
|
- `-o, --output-dir` - Output directory
|
||||||
|
- `--output-template` - Output filename template (yt-dlp syntax)
|
||||||
- `-f, --format` - Format specification
|
- `-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
|
- `-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
|
- `-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
|
## Quality Expectations
|
||||||
|
|
||||||
| Setup | 360p | 720p | 1080p | 1440p | 4K |
|
| Setup | 360p | 720p | 1080p | 1440p | 4K |
|
||||||
|-------|------|------|-------|-------|-----|
|
|-------|------|------|-------|-------|-----|
|
||||||
| No setup (default) | ✗ | ✗ | ✗ | ✗ | ✗ |
|
| **Auto PO token (default)** | ✓ | ✓ | ✓ | ✓ | ✓ |
|
||||||
| Android client only | ✓ | ✗ | ✗ | ✗ | ✗ |
|
| Android client only | ✓ | ✗ | ✗ | ✗ | ✗ |
|
||||||
| **PO token provider** | ✓ | ✓ | ✓ | ✓ | ✓ |
|
| PO token provider (manual) | ✓ | ✓ | ✓ | ✓ | ✓ |
|
||||||
| Browser cookies | ✓ | ✓ | ✓ | ✓ | ✓ |
|
| Browser cookies | ✓ | ✓ | ✓ | ✓ | ✓ |
|
||||||
|
|
||||||
## HLS Stream Downloads (m3u8)
|
## HLS Stream Downloads (m3u8)
|
||||||
|
|||||||
@@ -16,6 +16,41 @@ With PO token provider: **Full access** to all quality levels including 4K.
|
|||||||
|
|
||||||
## Recommended Solution: PO Token Provider Plugin
|
## 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
|
### Installation
|
||||||
|
|
||||||
Install a PO token provider plugin to handle token generation automatically. The plugin must be installed into yt-dlp's own Python environment.
|
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
|
```bash
|
||||||
# For Homebrew-installed yt-dlp (macOS)
|
# 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
|
# For pip-installed yt-dlp
|
||||||
python3 -m pip install bgutil-ytdlp-pot-provider --user
|
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
|
- **Method**: Launches browser to mint tokens
|
||||||
- **Best for**: Users comfortable with browser automation
|
- **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`
|
- **Installation**: `pip install yt-dlp-get-pot-rustypipe`
|
||||||
- **Method**: Uses rustypipe-botguard
|
- **Method**: Uses rustypipe-botguard
|
||||||
|
|||||||
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user