- 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>
