refactor(CLAUDE.md): slim from 1549 to 318 lines via progressive disclosure
Move verbose sections to references/ files, keeping concise pointers in CLAUDE.md. Zero content loss — all documentation preserved in reference files that Claude loads on demand. Moved to references/: - plugin-architecture.md (296 lines) — architecture docs - plugin-troubleshooting.md (441 lines) — installation debugging - new-skill-guide.md (241 lines) — detailed templates/checklists - promotion-policy.md (60 lines) — third-party request policy - youtube-downloader/references/internal-sop.md — yt-dlp SOP Also fixed: Available Skills #36-42 indentation, deduplicated 4x versioning sections into one, removed stale notes. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
daymade
241
references/new-skill-guide.md
Normal file
241
references/new-skill-guide.md
Normal file
@@ -0,0 +1,241 @@
|
|||||||
|
# Adding a New Skill to Marketplace - Detailed Guide
|
||||||
|
|
||||||
|
**CRITICAL**: When adding a skill to this marketplace, you MUST update all of these files. Missing any file will result in incomplete integration.
|
||||||
|
|
||||||
|
## Files to Update
|
||||||
|
|
||||||
|
```
|
||||||
|
✅ CHANGELOG.md (Add version entry)
|
||||||
|
✅ README.md (7 locations: badges, description, install, skill section, use case, docs link, requirements)
|
||||||
|
✅ README.zh-CN.md (7 locations: same as above, translated) ⚠️ CRITICAL
|
||||||
|
✅ CLAUDE.md (3 locations: overview, marketplace config, available skills)
|
||||||
|
✅ .claude-plugin/marketplace.json (CRITICAL: metadata + new plugin entry)
|
||||||
|
✅ skill-name/ (The actual skill directory)
|
||||||
|
✅ skill-name/skill-name.zip (Packaged skill)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Step-by-Step Process
|
||||||
|
|
||||||
|
### 1. Refine the Skill (if needed)
|
||||||
|
```bash
|
||||||
|
cd skill-creator
|
||||||
|
python3 scripts/security_scan.py ../skill-name --verbose
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Package the Skill
|
||||||
|
```bash
|
||||||
|
cd skill-creator
|
||||||
|
python3 scripts/package_skill.py ../skill-name
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Update CHANGELOG.md
|
||||||
|
|
||||||
|
Add new version entry at the top (after [Unreleased]):
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## [X.Y.0] - YYYY-MM-DD
|
||||||
|
|
||||||
|
### Added
|
||||||
|
- **New Skill**: skill-name - Brief description
|
||||||
|
- Feature 1
|
||||||
|
- Feature 2
|
||||||
|
- Bundled scripts/references/assets
|
||||||
|
|
||||||
|
### Changed
|
||||||
|
- Updated marketplace skills count from N to N+1
|
||||||
|
- Updated marketplace version from X.(Y-1).0 to X.Y.0
|
||||||
|
- Updated README.md badges (skills count, version)
|
||||||
|
- Updated README.md to include skill-name in skills listing
|
||||||
|
- Updated README.zh-CN.md badges (skills count, version)
|
||||||
|
- Updated README.zh-CN.md to include skill-name in skills listing
|
||||||
|
- Updated CLAUDE.md skills count from N to N+1
|
||||||
|
- Added skill-name use case section to README.md
|
||||||
|
- Added skill-name use case section to README.zh-CN.md
|
||||||
|
- Added dependencies to requirements section (if any, both EN and ZH)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. Update README.md
|
||||||
|
|
||||||
|
**a. Update badges (top of file):**
|
||||||
|
```markdown
|
||||||
|
[]
|
||||||
|
[]
|
||||||
|
```
|
||||||
|
|
||||||
|
**b. Update description:**
|
||||||
|
```markdown
|
||||||
|
Professional Claude Code skills marketplace featuring N production-ready skills...
|
||||||
|
```
|
||||||
|
|
||||||
|
**c. Add installation command:**
|
||||||
|
```markdown
|
||||||
|
# Brief description
|
||||||
|
claude plugin install skill-name@daymade-skills
|
||||||
|
```
|
||||||
|
|
||||||
|
**d. Add skill section (### N. **skill-name**):**
|
||||||
|
```markdown
|
||||||
|
### N. **skill-name** - One-line Title
|
||||||
|
|
||||||
|
Brief description paragraph.
|
||||||
|
|
||||||
|
**When to use:**
|
||||||
|
- Use case 1
|
||||||
|
- Use case 2
|
||||||
|
|
||||||
|
**Key features:**
|
||||||
|
- Feature 1
|
||||||
|
- Feature 2
|
||||||
|
|
||||||
|
**Example usage:**
|
||||||
|
\`\`\`bash
|
||||||
|
# Example commands
|
||||||
|
\`\`\`
|
||||||
|
|
||||||
|
**🎬 Live Demo**
|
||||||
|
|
||||||
|
*Coming soon* (or add demo GIF)
|
||||||
|
|
||||||
|
📚 **Documentation**: See [skill-name/references/](./skill-name/references/)...
|
||||||
|
|
||||||
|
**Requirements**: Dependencies (e.g., Python 3.8+, FFmpeg, etc.)
|
||||||
|
```
|
||||||
|
|
||||||
|
**e. Add use case section:**
|
||||||
|
```markdown
|
||||||
|
### For [Use Case Category]
|
||||||
|
Use **skill-name** to [describe primary use case]. Combine with **other-skill** to [describe integration].
|
||||||
|
```
|
||||||
|
|
||||||
|
**f. Add documentation quick link and update requirements section (if needed).**
|
||||||
|
|
||||||
|
### 5. Update CLAUDE.md
|
||||||
|
|
||||||
|
- Update repository overview skill count
|
||||||
|
- Update marketplace configuration plugin count
|
||||||
|
- Add skill to Available Skills list
|
||||||
|
|
||||||
|
### 6. Update .claude-plugin/marketplace.json (MOST IMPORTANT)
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"name": "skill-name",
|
||||||
|
"description": "Clear description with trigger conditions. Use when [scenarios]",
|
||||||
|
"source": "./",
|
||||||
|
"strict": false,
|
||||||
|
"version": "1.0.0",
|
||||||
|
"category": "appropriate-category",
|
||||||
|
"keywords": ["keyword1", "keyword2", "keyword3"],
|
||||||
|
"skills": ["./skill-name"]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Categories:** `developer-tools`, `document-conversion`, `documentation`, `customization`, `communication`, `utilities`, `assets`, `design`, `productivity`, `security`, `media`
|
||||||
|
|
||||||
|
Validate: `python3 -m json.tool .claude-plugin/marketplace.json > /dev/null`
|
||||||
|
|
||||||
|
### 7. Update README.zh-CN.md
|
||||||
|
|
||||||
|
**CRITICAL**: Chinese documentation must be kept in sync with English version.
|
||||||
|
|
||||||
|
Same 7 locations as README.md, translated to professional technical Chinese. Keep code examples in English.
|
||||||
|
|
||||||
|
### 8. Commit and Release
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Commit marketplace update
|
||||||
|
git add .claude-plugin/marketplace.json skill-name/
|
||||||
|
git commit -m "Release vX.Y.0: Add skill-name
|
||||||
|
|
||||||
|
- Add skill-name vX.Y.Z
|
||||||
|
- Update marketplace to vX.Y.0"
|
||||||
|
|
||||||
|
# Commit documentation
|
||||||
|
git add README.md README.zh-CN.md CLAUDE.md CHANGELOG.md demos/
|
||||||
|
git commit -m "docs: Update README for vX.Y.0 with skill-name"
|
||||||
|
|
||||||
|
# Push
|
||||||
|
git push
|
||||||
|
|
||||||
|
# Create GitHub release
|
||||||
|
gh release create vX.Y.0 \
|
||||||
|
--title "Release vX.Y.0: Add skill-name - Description" \
|
||||||
|
--notes "$(cat <<'EOF'
|
||||||
|
## New Skill: skill-name
|
||||||
|
|
||||||
|
Features:
|
||||||
|
- Feature 1
|
||||||
|
- Feature 2
|
||||||
|
|
||||||
|
Installation:
|
||||||
|
```bash
|
||||||
|
claude plugin install skill-name@daymade-skills
|
||||||
|
```
|
||||||
|
|
||||||
|
Changelog: ...
|
||||||
|
EOF
|
||||||
|
)"
|
||||||
|
```
|
||||||
|
|
||||||
|
### 9. Generate Demo (Optional but Recommended)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
./cli-demo-generator/scripts/auto_generate_demo.py \
|
||||||
|
-c "command1" \
|
||||||
|
-c "command2" \
|
||||||
|
-o demos/skill-name/demo-name.gif \
|
||||||
|
--title "Skill Demo" \
|
||||||
|
--theme "Dracula"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Verification Checklist
|
||||||
|
|
||||||
|
Before committing, verify:
|
||||||
|
|
||||||
|
- [ ] CHANGELOG.md has new version entry
|
||||||
|
- [ ] README.md badges updated (skills count + version)
|
||||||
|
- [ ] README.md has skill section with number
|
||||||
|
- [ ] README.md has use case section
|
||||||
|
- [ ] README.md has documentation link
|
||||||
|
- [ ] README.md requirements updated (if needed)
|
||||||
|
- [ ] README.zh-CN.md badges updated (skills count + version)
|
||||||
|
- [ ] README.zh-CN.md has skill section with number
|
||||||
|
- [ ] README.zh-CN.md has use case section
|
||||||
|
- [ ] README.zh-CN.md has documentation link
|
||||||
|
- [ ] README.zh-CN.md requirements updated (if needed)
|
||||||
|
- [ ] README.zh-CN.md installation command added
|
||||||
|
- [ ] CLAUDE.md skill count updated in 3 places
|
||||||
|
- [ ] CLAUDE.md has skill in Available Skills list
|
||||||
|
- [ ] marketplace.json metadata.version updated
|
||||||
|
- [ ] marketplace.json metadata.description updated
|
||||||
|
- [ ] marketplace.json has new plugin entry
|
||||||
|
- [ ] marketplace.json validates (python3 -m json.tool)
|
||||||
|
- [ ] skill-name.zip package exists
|
||||||
|
- [ ] Security scan passed
|
||||||
|
|
||||||
|
## Common Mistakes to Avoid
|
||||||
|
|
||||||
|
1. **Forgetting marketplace.json** - Without this, `claude plugin install` fails
|
||||||
|
2. **Forgetting Chinese documentation** - README.zh-CN.md must be updated in sync (6 locations)
|
||||||
|
3. **Inconsistent version numbers** - CHANGELOG, README badges (both EN and ZH), CLAUDE.md, and marketplace.json must all match
|
||||||
|
4. **Inconsistent skill counts** - README description (both EN and ZH), badges, CLAUDE.md must all have same count
|
||||||
|
5. **Missing skill number in README** - Skills must be numbered sequentially in both EN and ZH versions
|
||||||
|
6. **Invalid JSON syntax** - Always validate marketplace.json after editing
|
||||||
|
7. **Forgetting to push** - Local changes are invisible until pushed to GitHub
|
||||||
|
|
||||||
|
## Quick Reference Commands
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 1. Refine and validate skill
|
||||||
|
cd skill-creator && python3 scripts/security_scan.py ../skill-name --verbose
|
||||||
|
|
||||||
|
# 2. Package skill
|
||||||
|
python3 scripts/package_skill.py ../skill-name
|
||||||
|
|
||||||
|
# 3. Validate marketplace.json
|
||||||
|
cd .. && python3 -m json.tool .claude-plugin/marketplace.json > /dev/null && echo "✅ Valid"
|
||||||
|
|
||||||
|
# 4. Verify Chinese documentation is in sync
|
||||||
|
grep "skills-[0-9]*" README.md README.zh-CN.md
|
||||||
|
grep "version-[0-9.]*" README.md README.zh-CN.md
|
||||||
|
```
|
||||||
296
references/plugin-architecture.md
Normal file
296
references/plugin-architecture.md
Normal file
@@ -0,0 +1,296 @@
|
|||||||
|
# Plugin and Skill Architecture
|
||||||
|
|
||||||
|
This document explains the architecture of Claude Code's extension system and how different components work together.
|
||||||
|
|
||||||
|
## Core Concepts
|
||||||
|
|
||||||
|
### 1. Skills
|
||||||
|
|
||||||
|
**What**: Functional units that extend Claude's capabilities with specialized knowledge and workflows.
|
||||||
|
|
||||||
|
**Structure**:
|
||||||
|
```
|
||||||
|
skill-name/
|
||||||
|
├── SKILL.md (required) # YAML frontmatter + Markdown instructions
|
||||||
|
├── scripts/ (optional) # Executable code (Python/Bash)
|
||||||
|
├── references/ (optional) # Documentation loaded as needed
|
||||||
|
└── assets/ (optional) # Templates and resources
|
||||||
|
```
|
||||||
|
|
||||||
|
**Loading mechanism** (Progressive Disclosure):
|
||||||
|
1. **Metadata** (~100 tokens): Always in context (name + description from YAML frontmatter)
|
||||||
|
2. **SKILL.md body** (<5k tokens): Loaded when Claude determines the skill applies
|
||||||
|
3. **Bundled resources**: Loaded only as needed by Claude
|
||||||
|
|
||||||
|
**Location**:
|
||||||
|
- **Personal**: `~/.claude/skills/` (user-specific, not shared)
|
||||||
|
- **Project**: `.claude/skills/` (checked into git, shared with team)
|
||||||
|
- **Plugin cache**: `~/.claude/plugins/cache/{marketplace}/{plugin}/{version}/{skill}/`
|
||||||
|
|
||||||
|
**Example**: When you ask "analyze my disk space", Claude loads the `macos-cleaner` skill's SKILL.md, then reads `references/cleanup_targets.md` as needed.
|
||||||
|
|
||||||
|
### 2. Plugins
|
||||||
|
|
||||||
|
**What**: Distribution units that package one or more skills for installation via marketplaces.
|
||||||
|
|
||||||
|
**Purpose**: Plugins enable:
|
||||||
|
- One-command installation (`claude plugin install skill-name@marketplace-name`)
|
||||||
|
- Version management
|
||||||
|
- Dependency tracking
|
||||||
|
- Marketplace distribution
|
||||||
|
|
||||||
|
**Relationship to Skills**:
|
||||||
|
```
|
||||||
|
Plugin (marketplace.json entry)
|
||||||
|
├── Skill 1 (./skill-name-1/)
|
||||||
|
├── Skill 2 (./skill-name-2/)
|
||||||
|
└── Skill 3 (./skill-name-3/)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Configuration** (in `.claude-plugin/marketplace.json`):
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"name": "my-plugin",
|
||||||
|
"description": "Use when...",
|
||||||
|
"version": "1.0.0",
|
||||||
|
"category": "utilities",
|
||||||
|
"keywords": ["keyword1", "keyword2"],
|
||||||
|
"skills": ["./skill-1", "./skill-2"]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Example**: The `skill-creator` plugin contains one skill (`./skill-creator`), while a hypothetical `developer-tools` plugin might contain multiple skills like `./git-helper`, `./code-reviewer`, `./test-runner`.
|
||||||
|
|
||||||
|
### 3. Agents (Subagents)
|
||||||
|
|
||||||
|
**What**: Specialized autonomous agents invoked via the `Task` tool for complex, multi-step operations.
|
||||||
|
|
||||||
|
**Types**:
|
||||||
|
- **Bash**: Command execution specialist
|
||||||
|
- **general-purpose**: Research, search, multi-step tasks
|
||||||
|
- **Explore**: Fast codebase exploration
|
||||||
|
- **Plan**: Software architecture planning
|
||||||
|
- **skill-creator**: Meta-agent for creating skills
|
||||||
|
- **Custom**: Domain-specific agents (e.g., `test-runner`, `build-validator`)
|
||||||
|
|
||||||
|
**When to use**:
|
||||||
|
- Tasks requiring multiple rounds of tool calls
|
||||||
|
- Open-ended exploration (finding files, searching code)
|
||||||
|
- Planning before implementation
|
||||||
|
- Autonomous execution without user intervention
|
||||||
|
|
||||||
|
**Example**:
|
||||||
|
```python
|
||||||
|
# Instead of manually searching multiple times:
|
||||||
|
Task(
|
||||||
|
subagent_type="Explore",
|
||||||
|
description="Find error handling code",
|
||||||
|
prompt="Search the codebase for error handling patterns and list all files that handle HTTP errors"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. Commands
|
||||||
|
|
||||||
|
**What**: Slash commands (e.g., `/commit`, `/review-pr`) that trigger skills.
|
||||||
|
|
||||||
|
**Relationship**: Commands are shortcuts to invoke skills.
|
||||||
|
- `/commit` → invokes `commit` skill
|
||||||
|
- `/review-pr` → invokes `review-pr` skill
|
||||||
|
|
||||||
|
**Configuration**: Defined in plugin's `commands/` directory or skill metadata.
|
||||||
|
|
||||||
|
## Architecture Diagram
|
||||||
|
|
||||||
|
```
|
||||||
|
Marketplace (GitHub)
|
||||||
|
↓ (git clone)
|
||||||
|
~/.claude/plugins/marketplaces/{marketplace-name}/
|
||||||
|
↓ (plugin install)
|
||||||
|
~/.claude/plugins/cache/{marketplace-name}/{plugin}/{version}/
|
||||||
|
├── skill-1/
|
||||||
|
│ ├── SKILL.md
|
||||||
|
│ ├── scripts/
|
||||||
|
│ └── references/
|
||||||
|
└── skill-2/
|
||||||
|
└── SKILL.md
|
||||||
|
↓ (Claude loads)
|
||||||
|
Claude Code Context
|
||||||
|
├── Metadata (always loaded)
|
||||||
|
├── SKILL.md (loaded when relevant)
|
||||||
|
└── Resources (loaded as needed)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Installation Flow
|
||||||
|
|
||||||
|
### Step 1: User initiates installation
|
||||||
|
```bash
|
||||||
|
claude plugin install macos-cleaner@daymade-skills
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 2: CLI locates marketplace
|
||||||
|
```bash
|
||||||
|
# Check ~/.claude/plugins/marketplaces/daymade-skills/
|
||||||
|
# If not exists, git clone from GitHub
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 3: Read marketplace.json
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"plugins": [
|
||||||
|
{
|
||||||
|
"name": "macos-cleaner",
|
||||||
|
"version": "1.0.0",
|
||||||
|
"skills": ["./macos-cleaner"]
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 4: Download to cache
|
||||||
|
```bash
|
||||||
|
# Clone entire marketplace repo to:
|
||||||
|
~/.claude/plugins/cache/daymade-skills/macos-cleaner/1.0.0/
|
||||||
|
|
||||||
|
# Extract skill to:
|
||||||
|
~/.claude/plugins/cache/daymade-skills/macos-cleaner/1.0.0/macos-cleaner/
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 5: Record installation
|
||||||
|
```json
|
||||||
|
// ~/.claude/plugins/installed_plugins.json
|
||||||
|
{
|
||||||
|
"plugins": {
|
||||||
|
"macos-cleaner@daymade-skills": [{
|
||||||
|
"scope": "user",
|
||||||
|
"installPath": "~/.claude/plugins/cache/daymade-skills/macos-cleaner/1.0.0",
|
||||||
|
"version": "1.0.0",
|
||||||
|
"installedAt": "2026-01-11T08:03:46.593Z"
|
||||||
|
}]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 6: Claude Code loads skill
|
||||||
|
```
|
||||||
|
When user asks: "My Mac is running out of space"
|
||||||
|
↓
|
||||||
|
Claude scans installed plugins metadata
|
||||||
|
↓
|
||||||
|
Finds "macos-cleaner" description matches
|
||||||
|
↓
|
||||||
|
Loads SKILL.md into context
|
||||||
|
↓
|
||||||
|
Executes workflow (analyze → report → confirm → cleanup)
|
||||||
|
↓
|
||||||
|
Loads references/scripts as needed
|
||||||
|
```
|
||||||
|
|
||||||
|
## Key Files and Locations
|
||||||
|
|
||||||
|
### Configuration Files
|
||||||
|
|
||||||
|
| File | Location | Purpose |
|
||||||
|
|------|----------|---------|
|
||||||
|
| `marketplace.json` | `~/.claude/plugins/marketplaces/{name}/.claude-plugin/` | Defines available plugins |
|
||||||
|
| `installed_plugins.json` | `~/.claude/plugins/` | Tracks installed plugins |
|
||||||
|
| `known_marketplaces.json` | `~/.claude/plugins/` | Lists registered marketplaces |
|
||||||
|
|
||||||
|
### Directory Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
~/.claude/
|
||||||
|
├── skills/ # Personal skills (not from marketplace)
|
||||||
|
├── plugins/
|
||||||
|
│ ├── marketplaces/ # Marketplace clones
|
||||||
|
│ │ ├── daymade-skills/ # Marketplace name
|
||||||
|
│ │ │ └── .claude-plugin/
|
||||||
|
│ │ │ └── marketplace.json
|
||||||
|
│ │ └── anthropic-agent-skills/
|
||||||
|
│ ├── cache/ # Installed plugins
|
||||||
|
│ │ └── daymade-skills/
|
||||||
|
│ │ └── macos-cleaner/
|
||||||
|
│ │ └── 1.0.0/ # Version
|
||||||
|
│ │ └── macos-cleaner/ # Skill directory
|
||||||
|
│ │ ├── SKILL.md
|
||||||
|
│ │ ├── scripts/
|
||||||
|
│ │ └── references/
|
||||||
|
│ ├── installed_plugins.json # Installation registry
|
||||||
|
│ └── known_marketplaces.json # Marketplace registry
|
||||||
|
```
|
||||||
|
|
||||||
|
## Data Flow
|
||||||
|
|
||||||
|
### Skill Activation
|
||||||
|
```
|
||||||
|
User message
|
||||||
|
↓
|
||||||
|
Claude analyzes installed plugin metadata
|
||||||
|
↓
|
||||||
|
Matches description to user intent
|
||||||
|
↓
|
||||||
|
Loads SKILL.md (progressive disclosure)
|
||||||
|
↓
|
||||||
|
Executes instructions
|
||||||
|
↓
|
||||||
|
Loads bundled resources (scripts, references) as needed
|
||||||
|
↓
|
||||||
|
Generates response
|
||||||
|
```
|
||||||
|
|
||||||
|
### Plugin Update
|
||||||
|
```
|
||||||
|
Local changes to skill
|
||||||
|
↓
|
||||||
|
git add & commit
|
||||||
|
↓
|
||||||
|
git push to GitHub
|
||||||
|
↓
|
||||||
|
User runs: claude plugin marketplace update {marketplace-name}
|
||||||
|
↓
|
||||||
|
CLI pulls latest from GitHub
|
||||||
|
↓
|
||||||
|
Updates ~/.claude/plugins/marketplaces/{marketplace-name}/
|
||||||
|
↓
|
||||||
|
User runs: claude plugin update {plugin-name@marketplace}
|
||||||
|
↓
|
||||||
|
Re-downloads to cache with new version number
|
||||||
|
↓
|
||||||
|
Updates installed_plugins.json
|
||||||
|
```
|
||||||
|
|
||||||
|
## Common Misconceptions
|
||||||
|
|
||||||
|
| Myth | Reality |
|
||||||
|
|------|---------|
|
||||||
|
| "Updating local files immediately updates the plugin" | Plugins are distributed via GitHub. Local changes require `git push` before users can install updates. |
|
||||||
|
| "Skills and plugins are the same thing" | Skills are functional units (SKILL.md + resources). Plugins are distribution packages (can contain multiple skills). |
|
||||||
|
| "marketplace.json is just metadata" | marketplace.json is the **source of truth** for plugin discovery. Without correct configuration here, `claude plugin install` will fail. |
|
||||||
|
| "Cache is just for performance" | Cache (`~/.claude/plugins/cache/`) is where installed plugins actually live. Deleting cache uninstalls all plugins. |
|
||||||
|
| "Skills in ~/.claude/skills/ work the same as plugin skills" | `~/.claude/skills/` = Personal skills (manual, no versioning). Plugin cache = Managed by CLI (versioned, updateable, shareable). |
|
||||||
|
|
||||||
|
## Best Practices
|
||||||
|
|
||||||
|
### For Skill Authors
|
||||||
|
|
||||||
|
1. **Clear metadata**: Description should clearly state "Use when..." to help Claude match user intent
|
||||||
|
2. **Progressive disclosure**: Keep SKILL.md lean, move details to `references/`
|
||||||
|
3. **Test locally first**: Copy to `~/.claude/skills/` for testing before packaging
|
||||||
|
4. **Version properly**: Use semver (MAJOR.MINOR.PATCH) in marketplace.json
|
||||||
|
5. **Document bundled resources**: All scripts and references should be mentioned in SKILL.md
|
||||||
|
|
||||||
|
### For Marketplace Maintainers
|
||||||
|
|
||||||
|
1. **Git workflow**: Always `git push` after updating marketplace.json
|
||||||
|
2. **Validate JSON**: Run `python -m json.tool marketplace.json` before committing
|
||||||
|
3. **Update cache**: Remind users to run `claude plugin marketplace update` after releases
|
||||||
|
4. **Version consistency**: Marketplace version ≠ plugin versions (they track independently)
|
||||||
|
|
||||||
|
### For Users
|
||||||
|
|
||||||
|
1. **Update marketplaces**: Run `claude plugin marketplace update {name}` periodically
|
||||||
|
2. **Check installed plugins**: Inspect `~/.claude/plugins/installed_plugins.json`
|
||||||
|
3. **Clear cache on issues**: `rm -rf ~/.claude/plugins/cache/{marketplace-name}` then reinstall
|
||||||
|
4. **Understand scopes**:
|
||||||
|
- `--scope user`: Only you (default)
|
||||||
|
- `--scope project`: Shared with team via `.claude/plugins/`
|
||||||
|
- `--scope local`: Gitignored, local only
|
||||||
441
references/plugin-troubleshooting.md
Normal file
441
references/plugin-troubleshooting.md
Normal file
@@ -0,0 +1,441 @@
|
|||||||
|
# Plugin and Skill Troubleshooting
|
||||||
|
|
||||||
|
Systematic debugging steps for common plugin and skill installation issues.
|
||||||
|
|
||||||
|
## Understanding the Architecture First
|
||||||
|
|
||||||
|
**CRITICAL**: Claude Code's plugin system is **GitHub-based**, not local-file-based.
|
||||||
|
|
||||||
|
```
|
||||||
|
GitHub Repository (source of truth)
|
||||||
|
↓ (git clone / git pull)
|
||||||
|
~/.claude/plugins/marketplaces/{marketplace-name}/
|
||||||
|
↓ (claude plugin install)
|
||||||
|
~/.claude/plugins/cache/{marketplace-name}/{plugin}/{version}/
|
||||||
|
↓ (Claude Code loads)
|
||||||
|
Active skill in Claude's context
|
||||||
|
```
|
||||||
|
|
||||||
|
**Key insight**: Local file changes are NOT visible to `claude plugin install` until pushed to GitHub.
|
||||||
|
|
||||||
|
## Common Error 1: "Plugin not found in marketplace"
|
||||||
|
|
||||||
|
**Error message**:
|
||||||
|
```
|
||||||
|
Installing plugin "skill-name@marketplace-name"...
|
||||||
|
✘ Failed to install plugin: Plugin "skill-name" not found in marketplace "marketplace-name"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Root causes** (in order of likelihood):
|
||||||
|
|
||||||
|
### Cause 1.1: Local changes not pushed to GitHub (MOST COMMON)
|
||||||
|
|
||||||
|
**Symptoms**:
|
||||||
|
- `git status` shows modified files or untracked directories
|
||||||
|
- marketplace.json updated locally but install fails
|
||||||
|
- All documentation updated but plugin not found
|
||||||
|
|
||||||
|
**Diagnosis**:
|
||||||
|
```bash
|
||||||
|
# Check if you have uncommitted changes
|
||||||
|
git status
|
||||||
|
|
||||||
|
# Check last commit vs remote
|
||||||
|
git log origin/main..HEAD
|
||||||
|
|
||||||
|
# Verify GitHub has latest marketplace.json
|
||||||
|
# Open: https://github.com/{owner}/{repo}/blob/main/.claude-plugin/marketplace.json
|
||||||
|
```
|
||||||
|
|
||||||
|
**Solution**:
|
||||||
|
```bash
|
||||||
|
# 1. Commit all changes
|
||||||
|
git add -A
|
||||||
|
git commit -m "Release vX.Y.Z: Add {skill-name}"
|
||||||
|
|
||||||
|
# 2. Push to GitHub
|
||||||
|
git push
|
||||||
|
|
||||||
|
# 3. Clear local marketplace cache
|
||||||
|
rm -rf ~/.claude/plugins/cache/{marketplace-name}
|
||||||
|
|
||||||
|
# 4. Update marketplace from GitHub
|
||||||
|
claude plugin marketplace update {marketplace-name}
|
||||||
|
|
||||||
|
# 5. Retry installation
|
||||||
|
claude plugin install {skill-name}@{marketplace-name}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Why this happens**: You updated marketplace.json locally, but Claude CLI pulls from GitHub, not your local filesystem.
|
||||||
|
|
||||||
|
### Cause 1.2: marketplace.json configuration error
|
||||||
|
|
||||||
|
**Symptoms**:
|
||||||
|
- Git is up-to-date but install still fails
|
||||||
|
- Other plugins from same marketplace install fine
|
||||||
|
|
||||||
|
**Diagnosis**:
|
||||||
|
```bash
|
||||||
|
# 1. Check marketplace.json syntax
|
||||||
|
python3 -m json.tool .claude-plugin/marketplace.json > /dev/null
|
||||||
|
|
||||||
|
# 2. Verify plugin entry exists
|
||||||
|
cat .claude-plugin/marketplace.json | jq '.plugins[] | select(.name == "skill-name")'
|
||||||
|
|
||||||
|
# 3. Check spelling matches exactly
|
||||||
|
# Plugin name in marketplace.json MUST match install command
|
||||||
|
```
|
||||||
|
|
||||||
|
**Common mistakes**:
|
||||||
|
```json
|
||||||
|
// ❌ Wrong: name mismatch
|
||||||
|
{
|
||||||
|
"name": "macos_cleaner", // Underscore
|
||||||
|
"skills": ["./macos-cleaner"] // Dash
|
||||||
|
}
|
||||||
|
|
||||||
|
// ✅ Correct: consistent naming
|
||||||
|
{
|
||||||
|
"name": "macos-cleaner",
|
||||||
|
"skills": ["./macos-cleaner"]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Solution**: Fix marketplace.json, then commit and push.
|
||||||
|
|
||||||
|
### Cause 1.3: Skill directory missing
|
||||||
|
|
||||||
|
**Symptoms**:
|
||||||
|
- marketplace.json has entry
|
||||||
|
- Git is up-to-date
|
||||||
|
- Plugin installs but skills don't load
|
||||||
|
|
||||||
|
**Diagnosis**:
|
||||||
|
```bash
|
||||||
|
# Check if skill directory exists
|
||||||
|
ls -la {skill-name}/
|
||||||
|
|
||||||
|
# Verify SKILL.md exists
|
||||||
|
ls -la {skill-name}/SKILL.md
|
||||||
|
```
|
||||||
|
|
||||||
|
**Solution**: Ensure skill directory and SKILL.md are committed to git.
|
||||||
|
|
||||||
|
## Common Error 2: Marketplace cache is stale
|
||||||
|
|
||||||
|
**Symptoms**:
|
||||||
|
- GitHub has latest changes
|
||||||
|
- Install finds plugin but gets old version
|
||||||
|
- Newly added plugins not visible
|
||||||
|
|
||||||
|
**Diagnosis**:
|
||||||
|
```bash
|
||||||
|
# Check cache timestamp
|
||||||
|
ls -la ~/.claude/plugins/cache/{marketplace-name}/
|
||||||
|
|
||||||
|
# Compare with last git push
|
||||||
|
git log -1 --format="%ai"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Solution**:
|
||||||
|
```bash
|
||||||
|
# Option 1: Update marketplace cache
|
||||||
|
claude plugin marketplace update {marketplace-name}
|
||||||
|
|
||||||
|
# Option 2: Clear cache and re-fetch
|
||||||
|
rm -rf ~/.claude/plugins/cache/{marketplace-name}
|
||||||
|
claude plugin marketplace update {marketplace-name}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Common Error 3: JSON syntax error
|
||||||
|
|
||||||
|
**Error message**:
|
||||||
|
```
|
||||||
|
Error parsing marketplace manifest
|
||||||
|
```
|
||||||
|
|
||||||
|
**Diagnosis**:
|
||||||
|
```bash
|
||||||
|
# Validate JSON syntax
|
||||||
|
python3 -m json.tool .claude-plugin/marketplace.json
|
||||||
|
|
||||||
|
# Check for common issues:
|
||||||
|
# - Missing commas
|
||||||
|
# - Trailing commas (in arrays/objects)
|
||||||
|
# - Unescaped quotes in strings
|
||||||
|
# - Missing closing braces
|
||||||
|
```
|
||||||
|
|
||||||
|
**Solution**: Fix JSON syntax, validate, commit, push.
|
||||||
|
|
||||||
|
## Systematic Debugging Process
|
||||||
|
|
||||||
|
When facing ANY plugin/skill issue, follow this checklist:
|
||||||
|
|
||||||
|
### Step 1: Verify marketplace registration
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# List registered marketplaces
|
||||||
|
claude plugin marketplace list
|
||||||
|
|
||||||
|
# Expected output should include your marketplace
|
||||||
|
```
|
||||||
|
|
||||||
|
If missing, register:
|
||||||
|
```bash
|
||||||
|
claude plugin marketplace add https://github.com/{owner}/{repo}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 2: Check Git status
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Are there uncommitted changes?
|
||||||
|
git status
|
||||||
|
|
||||||
|
# Is local ahead of remote?
|
||||||
|
git log origin/main..HEAD
|
||||||
|
|
||||||
|
# Push if needed
|
||||||
|
git push
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 3: Verify GitHub has latest
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Open in browser or use gh CLI
|
||||||
|
gh browse .claude-plugin/marketplace.json
|
||||||
|
|
||||||
|
# Or check with curl
|
||||||
|
curl https://raw.githubusercontent.com/{owner}/{repo}/main/.claude-plugin/marketplace.json | jq '.plugins[] | .name'
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 4: Clear and update cache
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Remove stale cache
|
||||||
|
rm -rf ~/.claude/plugins/cache/{marketplace-name}
|
||||||
|
|
||||||
|
# Re-fetch from GitHub
|
||||||
|
claude plugin marketplace update {marketplace-name}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 5: Validate configuration
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Check marketplace.json is valid JSON
|
||||||
|
python3 -m json.tool .claude-plugin/marketplace.json > /dev/null && echo "✅ Valid JSON"
|
||||||
|
|
||||||
|
# Check plugin entry exists
|
||||||
|
cat .claude-plugin/marketplace.json | jq '.plugins[] | select(.name == "skill-name")' || echo "❌ Plugin not found"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 6: Inspect installation state
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Check if plugin is installed
|
||||||
|
cat ~/.claude/plugins/installed_plugins.json | jq -r '.plugins | keys[]' | grep "skill-name"
|
||||||
|
|
||||||
|
# If installed, check details
|
||||||
|
cat ~/.claude/plugins/installed_plugins.json | jq '.plugins["skill-name@marketplace-name"]'
|
||||||
|
|
||||||
|
# Verify files exist
|
||||||
|
ls ~/.claude/plugins/cache/{marketplace-name}/{skill-name}/{version}/
|
||||||
|
```
|
||||||
|
|
||||||
|
## Debugging Commands Reference
|
||||||
|
|
||||||
|
| Purpose | Command |
|
||||||
|
|---------|---------|
|
||||||
|
| List marketplaces | `claude plugin marketplace list` |
|
||||||
|
| Update marketplace | `claude plugin marketplace update {name}` |
|
||||||
|
| Install plugin | `claude plugin install {plugin}@{marketplace}` |
|
||||||
|
| Uninstall plugin | `claude plugin uninstall {plugin}@{marketplace}` |
|
||||||
|
| Update plugin | `claude plugin update {plugin}@{marketplace}` |
|
||||||
|
| Validate manifest | `claude plugin validate {path}` |
|
||||||
|
| Check installed plugins | `cat ~/.claude/plugins/installed_plugins.json \| jq '.plugins \| keys'` |
|
||||||
|
| Inspect plugin details | `cat ~/.claude/plugins/installed_plugins.json \| jq '.plugins["{plugin}@{marketplace}"]'` |
|
||||||
|
| Clear marketplace cache | `rm -rf ~/.claude/plugins/cache/{marketplace-name}` |
|
||||||
|
| Verify JSON syntax | `python3 -m json.tool {file.json}` |
|
||||||
|
|
||||||
|
## File Locations
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Marketplace clones (git repositories)
|
||||||
|
~/.claude/plugins/marketplaces/{marketplace-name}/
|
||||||
|
|
||||||
|
# Installed plugin cache
|
||||||
|
~/.claude/plugins/cache/{marketplace-name}/{plugin-name}/{version}/
|
||||||
|
|
||||||
|
# Installation registry
|
||||||
|
~/.claude/plugins/installed_plugins.json
|
||||||
|
|
||||||
|
# Personal skills (not from marketplace)
|
||||||
|
~/.claude/skills/
|
||||||
|
|
||||||
|
# Project-scoped skills (shared with team)
|
||||||
|
.claude/skills/
|
||||||
|
```
|
||||||
|
|
||||||
|
## Common Pitfalls
|
||||||
|
|
||||||
|
### Pitfall 1: Confusing local skills with plugin skills
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# ❌ Wrong: Copying skill to personal directory doesn't make it installable
|
||||||
|
cp -r my-skill ~/.claude/skills/my-skill # Works, but not managed by plugin system
|
||||||
|
|
||||||
|
# ✅ Correct: Install via marketplace for version management
|
||||||
|
claude plugin install my-skill@my-marketplace
|
||||||
|
```
|
||||||
|
|
||||||
|
### Pitfall 2: Forgetting to push after updating marketplace.json
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# ❌ Wrong workflow
|
||||||
|
vim .claude-plugin/marketplace.json # Add new plugin
|
||||||
|
git add .claude-plugin/marketplace.json
|
||||||
|
git commit -m "Add plugin"
|
||||||
|
# FORGOT TO PUSH!
|
||||||
|
claude plugin install new-plugin@my-marketplace # ❌ Fails: not found
|
||||||
|
|
||||||
|
# ✅ Correct workflow
|
||||||
|
vim .claude-plugin/marketplace.json
|
||||||
|
git add -A
|
||||||
|
git commit -m "Add new plugin"
|
||||||
|
git push # ← CRITICAL STEP
|
||||||
|
claude plugin marketplace update my-marketplace
|
||||||
|
claude plugin install new-plugin@my-marketplace # ✅ Works
|
||||||
|
```
|
||||||
|
|
||||||
|
### Pitfall 3: Expecting instant propagation
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# ❌ Wrong expectation
|
||||||
|
git push # Push changes
|
||||||
|
claude plugin install new-plugin@my-marketplace # ❌ Fails: cache is stale
|
||||||
|
|
||||||
|
# ✅ Correct: Update cache first
|
||||||
|
git push
|
||||||
|
claude plugin marketplace update my-marketplace # Fetch latest from GitHub
|
||||||
|
claude plugin install new-plugin@my-marketplace # ✅ Works
|
||||||
|
```
|
||||||
|
|
||||||
|
### Pitfall 4: Inconsistent naming
|
||||||
|
|
||||||
|
```json
|
||||||
|
// marketplace.json
|
||||||
|
{
|
||||||
|
"name": "my_plugin", // Underscore
|
||||||
|
"skills": ["./my-plugin"] // Dash - will cause confusion
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# User tries to install
|
||||||
|
claude plugin install my-plugin@marketplace # ❌ Not found (name has underscore)
|
||||||
|
claude plugin install my_plugin@marketplace # ✅ Works, but confusing
|
||||||
|
```
|
||||||
|
|
||||||
|
**Best practice**: Use consistent kebab-case for both plugin name and skill directory.
|
||||||
|
|
||||||
|
## Real-World Example: macos-cleaner Installation Issue
|
||||||
|
|
||||||
|
**Scenario**: After creating macos-cleaner skill and updating all documentation, `claude plugin install macos-cleaner@daymade-skills` failed with "Plugin not found".
|
||||||
|
|
||||||
|
**Investigation**:
|
||||||
|
```bash
|
||||||
|
# 1. Check git status
|
||||||
|
git status
|
||||||
|
# Output: 16 modified/untracked files
|
||||||
|
|
||||||
|
# 2. Check marketplace cache
|
||||||
|
ls -la ~/.claude/plugins/cache/daymade-skills/
|
||||||
|
# Output: Last modified Dec 20 (weeks old!)
|
||||||
|
|
||||||
|
# 3. Check GitHub
|
||||||
|
# marketplace.json on GitHub: version 1.20.0 (old)
|
||||||
|
# Local marketplace.json: version 1.21.0 (new)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Root cause**: Local changes weren't pushed to GitHub. CLI was pulling from GitHub, not local files.
|
||||||
|
|
||||||
|
**Solution**:
|
||||||
|
```bash
|
||||||
|
# 1. Commit and push
|
||||||
|
git add -A
|
||||||
|
git commit -m "Release v1.21.0: Add macos-cleaner"
|
||||||
|
git push
|
||||||
|
|
||||||
|
# 2. Update marketplace
|
||||||
|
claude plugin marketplace update daymade-skills
|
||||||
|
|
||||||
|
# 3. Install
|
||||||
|
claude plugin install macos-cleaner@daymade-skills
|
||||||
|
# ✔ Successfully installed plugin: macos-cleaner@daymade-skills
|
||||||
|
```
|
||||||
|
|
||||||
|
**Verification**:
|
||||||
|
```bash
|
||||||
|
cat ~/.claude/plugins/installed_plugins.json | jq '.plugins["macos-cleaner@daymade-skills"]'
|
||||||
|
# Output: Installation details with correct version
|
||||||
|
|
||||||
|
ls ~/.claude/plugins/cache/daymade-skills/macos-cleaner/1.0.0/
|
||||||
|
# Output: All skill files present
|
||||||
|
```
|
||||||
|
|
||||||
|
**Lesson**: Always remember the GitHub-based architecture. Local changes are invisible until pushed.
|
||||||
|
|
||||||
|
## Advanced: Manual Cache Inspection
|
||||||
|
|
||||||
|
If automated commands don't reveal the issue, manually inspect:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 1. Check marketplace clone
|
||||||
|
cat ~/.claude/plugins/marketplaces/{marketplace-name}/.claude-plugin/marketplace.json | jq '.metadata.version'
|
||||||
|
|
||||||
|
# 2. Check what's in cache
|
||||||
|
ls -R ~/.claude/plugins/cache/{marketplace-name}/
|
||||||
|
|
||||||
|
# 3. Compare with GitHub
|
||||||
|
curl -s https://raw.githubusercontent.com/{owner}/{repo}/main/.claude-plugin/marketplace.json | jq '.metadata.version'
|
||||||
|
|
||||||
|
# 4. Check installation record
|
||||||
|
cat ~/.claude/plugins/installed_plugins.json | jq '.plugins' | grep -i "{skill-name}"
|
||||||
|
```
|
||||||
|
|
||||||
|
## When All Else Fails
|
||||||
|
|
||||||
|
1. **Complete cache reset**:
|
||||||
|
```bash
|
||||||
|
rm -rf ~/.claude/plugins/cache/*
|
||||||
|
claude plugin marketplace update {marketplace-name}
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Re-register marketplace**:
|
||||||
|
```bash
|
||||||
|
# Remove marketplace
|
||||||
|
# (No direct command, manual edit ~/.claude/plugins/known_marketplaces.json)
|
||||||
|
|
||||||
|
# Re-add
|
||||||
|
claude plugin marketplace add https://github.com/{owner}/{repo}
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Check Claude Code version**:
|
||||||
|
```bash
|
||||||
|
claude --version
|
||||||
|
# Plugins require Claude Code v2.0.12+
|
||||||
|
```
|
||||||
|
|
||||||
|
4. **Enable verbose logging** (if available):
|
||||||
|
```bash
|
||||||
|
CLAUDE_DEBUG=1 claude plugin install {plugin}@{marketplace}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Getting Help
|
||||||
|
|
||||||
|
If you're still stuck:
|
||||||
|
|
||||||
|
1. **Check GitHub issues**: https://github.com/anthropics/claude-code/issues
|
||||||
|
2. **Verify marketplace.json**: Run `claude plugin validate .claude-plugin/marketplace.json`
|
||||||
|
3. **Compare with working marketplace**: Study anthropic's official marketplace structure
|
||||||
|
4. **Document your debugging**: Include output from all diagnostic commands above
|
||||||
60
references/promotion-policy.md
Normal file
60
references/promotion-policy.md
Normal file
@@ -0,0 +1,60 @@
|
|||||||
|
# Handling Third-Party Marketplace Promotion Requests
|
||||||
|
|
||||||
|
This repository is a **personal curated marketplace**, NOT a community directory or ecosystem hub. All requests to add third-party marketplace links, skill collection references, or "Community Marketplaces" sections should be declined.
|
||||||
|
|
||||||
|
## Policy
|
||||||
|
|
||||||
|
**DO NOT accept:**
|
||||||
|
- PRs adding "Related Resources" or "Community Marketplaces" sections linking to third-party skill collections
|
||||||
|
- Issues requesting promotion of external marketplaces
|
||||||
|
- PRs adding links to other skill repositories in README.md
|
||||||
|
|
||||||
|
**Rationale:**
|
||||||
|
1. **Scope creep**: Shifts repository purpose from curated skills to ecosystem directory
|
||||||
|
2. **Implicit endorsement**: Listing implies quality/security review we cannot maintain
|
||||||
|
3. **Maintenance burden**: Would need to track and vet external projects over time
|
||||||
|
4. **Precedent setting**: Accepting one creates obligation to accept others
|
||||||
|
|
||||||
|
## Response Template
|
||||||
|
|
||||||
|
When declining, use this approach:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
Hi @{username},
|
||||||
|
|
||||||
|
Thank you for your interest and for sharing {project-name}! {Brief positive acknowledgment of their project}.
|
||||||
|
|
||||||
|
However, I'm keeping this repository focused as a **personal curated marketplace** rather than a directory of external skill collections. Adding third-party references would:
|
||||||
|
|
||||||
|
1. Shift the repository's scope from curated skills to ecosystem directory
|
||||||
|
2. Create implicit endorsement expectations I can't maintain
|
||||||
|
3. Set precedent for similar requests (reference other declined requests if applicable)
|
||||||
|
|
||||||
|
**What you can do instead:**
|
||||||
|
|
||||||
|
1. **Standalone marketplace** - Your repo already works as an independent marketplace:
|
||||||
|
```
|
||||||
|
/plugin marketplace add {owner}/{repo}
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Community channels** - Promote through:
|
||||||
|
- Claude Code GitHub discussions/issues (Anthropic's official repo)
|
||||||
|
- Developer communities (Reddit, Discord, etc.)
|
||||||
|
- Your own blog/social media
|
||||||
|
|
||||||
|
3. **Official registry** - If/when Anthropic launches an official skill registry, that would be the appropriate place for ecosystem-wide discovery.
|
||||||
|
|
||||||
|
Your marketplace can succeed on its own merits. Good luck with {project-name}!
|
||||||
|
```
|
||||||
|
|
||||||
|
## Workflow
|
||||||
|
|
||||||
|
1. **Review the request** - Confirm it's a third-party promotion (not a legitimate contribution)
|
||||||
|
2. **Add polite comment** - Use template above, customize for their specific project
|
||||||
|
3. **Close with reason** - Use "not planned" for issues, just close for PRs
|
||||||
|
4. **Reference precedent** - Link to previously declined requests for consistency (e.g., #7, PR #5)
|
||||||
|
|
||||||
|
## Examples
|
||||||
|
|
||||||
|
- **Issue #7**: "Add Community Marketplaces section - Protocol Thunderdome" → Declined, closed as "not planned"
|
||||||
|
- **PR #5**: "Add Trail of Bits Security Skills to Related Resources" → Declined, closed
|
||||||
12
youtube-downloader/references/internal-sop.md
Normal file
12
youtube-downloader/references/internal-sop.md
Normal file
@@ -0,0 +1,12 @@
|
|||||||
|
# YouTube Downloader Internal SOP
|
||||||
|
|
||||||
|
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.
|
||||||
Reference in New Issue
Block a user