From ed16fce4b0b888f984316b179aee3a6c61156538 Mon Sep 17 00:00:00 2001
From: daymade <daymadev89@gmail.com>
Date: Sun, 11 Jan 2026 16:14:53 +0800
Subject: [PATCH] docs: Add comprehensive plugin/skill architecture and
 troubleshooting

- Add AGENTS.md: Complete architecture guide for Plugins, Skills, and Agents
  - Explain the relationship between plugins and skills
  - Document the GitHub-based marketplace mechanism
  - Detail installation flow and data flow
  - Clarify common misconceptions
  - Provide best practices for authors, maintainers, and users

- Update CLAUDE.md: Add "Plugin and Skill Troubleshooting" section
  - Systematic debugging process with real-world examples
  - Common errors with root cause analysis and solutions
  - "Plugin not found" error (most common: forgot to push)
  - Stale marketplace cache issues
  - JSON syntax errors
  - Step-by-step debugging checklist
  - Debugging commands reference table
  - File locations reference
  - Common pitfalls with wrong/correct examples
  - Real-world case study: macos-cleaner installation issue
  - Advanced cache inspection techniques

Key learnings from macos-cleaner deployment:
- Claude Code marketplace is GitHub-based, not local-file-based
- Local changes invisible until git push
- Cache requires explicit update after GitHub changes
- installed_plugins.json is source of truth for installations

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 AGENTS.md | 316 ++++++++++++++++++++++++++++++++++++++
 CLAUDE.md | 447 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 763 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..cb3785a
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,316 @@
+# Claude Code Architecture: Plugins, Skills, and Agents
+
+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 1: "Updating local files immediately updates the plugin"
+**Reality**: Plugins are distributed via GitHub. Local changes require `git push` before users can install updates.
+
+### ❌ Myth 2: "Skills and plugins are the same thing"
+**Reality**: Skills are functional units (SKILL.md + resources). Plugins are distribution packages (can contain multiple skills).
+
+### ❌ Myth 3: "marketplace.json is just metadata"
+**Reality**: marketplace.json is the **source of truth** for plugin discovery. Without correct configuration here, `claude plugin install` will fail with "Plugin not found".
+
+### ❌ Myth 4: "Cache is just for performance"
+**Reality**: Cache (`~/.claude/plugins/cache/`) is where installed plugins actually live. Deleting cache uninstalls all plugins.
+
+### ❌ Myth 5: "Skills in ~/.claude/skills/ work the same as plugin skills"
+**Reality**:
+- `~/.claude/skills/` = Personal skills (manual management, 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
+
+## Troubleshooting Guide
+
+See [CLAUDE.md § Plugin and Skill Troubleshooting](#plugin-and-skill-troubleshooting) for detailed debugging steps.
+
+## References
+
+- [Official Skills Documentation](https://code.claude.com/docs/en/skills)
+- [Plugin Reference](https://code.claude.com/docs/en/plugins-reference)
+- [Marketplace Discovery](https://code.claude.com/docs/en/discover-plugins)
+- [Anthropic Skills Best Practices](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices.md)
diff --git a/CLAUDE.md b/CLAUDE.md
index 5aa51ec..6d9f990 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -689,3 +689,450 @@ EOF
 Always consult Anthropic's skill authoring best practices before creating or updating skills:
 https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices.md
 - remember this release workflow in claude.md
+
+## Plugin and Skill Troubleshooting
+
+This section provides systematic debugging steps for common plugin and skill installation issues.
+
+### Understanding the Architecture First
+
+**CRITICAL**: Before troubleshooting, understand that 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}` |
+
+### Understanding 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
+
+For this project specifically, refer to:
+- [AGENTS.md](./AGENTS.md) - Architecture overview
+- [skill-creator/SKILL.md](./skill-creator/SKILL.md) - Skill creation guide
+- [CONTRIBUTING.md](./CONTRIBUTING.md) - Development workflow