- Migrated all valuable architecture content from AGENTS.md into CLAUDE.md
- Created new 'Plugin and Skill Architecture' section in CLAUDE.md
- Includes: Core Concepts (Skills, Plugins, Agents, Commands)
- Includes: Architecture diagrams, installation flow, data flow
- Includes: Common misconceptions and best practices
- Deleted original AGENTS.md file
- Created symlink AGENTS.md -> CLAUDE.md to avoid duplicate maintenance
- Updated internal references to point to CLAUDE.md sections
This consolidation ensures single source of truth for plugin/skill architecture documentation.
- 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>
