claude-engineering-plugin/CLAUDE.md

Every Marketplace - Claude Code Plugin Marketplace

This repository is a Claude Code plugin marketplace that distributes the compounding-engineering plugin to developers building with AI-powered tools.

Repository Structure

every-marketplace/
├── .claude-plugin/
│   └── marketplace.json          # Marketplace catalog (lists available plugins)
└── plugins/
    └── compounding-engineering/   # The actual plugin
        ├── .claude-plugin/
        │   └── plugin.json        # Plugin metadata
        ├── agents/                # 17 specialized AI agents
        ├── commands/              # 6 slash commands
        ├── skills/                # 1 skill (gemini-imagegen)
        ├── README.md              # Plugin documentation
        └── CHANGELOG.md           # Version history

Philosophy: Compounding Engineering

Each unit of engineering work should make subsequent units of work easier—not harder.

When working on this repository, follow the compounding engineering process:

1. Plan → Understand the change needed and its impact
2. Delegate → Use AI tools to help with implementation
3. Assess → Verify changes work as expected
4. Codify → Update this CLAUDE.md with learnings

Working with This Repository

Adding a New Plugin

1. Create plugin directory: plugins/new-plugin-name/
2. Add plugin structure:

   plugins/new-plugin-name/
   ├── .claude-plugin/plugin.json
   ├── agents/
   ├── commands/
   └── README.md
   

3. Update .claude-plugin/marketplace.json to include the new plugin
4. Test locally before committing

Updating the Compounding Engineering Plugin

When agents, commands, or skills are added/removed, follow this checklist:

1. Count all components accurately

# Count agents
ls plugins/compounding-engineering/agents/*.md | wc -l

# Count commands
ls plugins/compounding-engineering/commands/*.md | wc -l

# Count skills
ls -d plugins/compounding-engineering/skills/*/ 2>/dev/null | wc -l

2. Update ALL description strings with correct counts

The description appears in multiple places and must match everywhere:

• plugins/compounding-engineering/.claude-plugin/plugin.json → description field
• .claude-plugin/marketplace.json → plugin description field
• plugins/compounding-engineering/README.md → intro paragraph

Format: "Includes X specialized agents, Y commands, and Z skill(s)."

3. Update version numbers

When adding new functionality, bump the version in:

• plugins/compounding-engineering/.claude-plugin/plugin.json → version
• .claude-plugin/marketplace.json → plugin version

4. Update documentation

• plugins/compounding-engineering/README.md → list all components
• plugins/compounding-engineering/CHANGELOG.md → document changes
• CLAUDE.md → update structure diagram if needed

5. Validate JSON files

cat .claude-plugin/marketplace.json | jq .
cat plugins/compounding-engineering/.claude-plugin/plugin.json | jq .

6. Verify before committing

# Ensure counts in descriptions match actual files
grep -o "Includes [0-9]* specialized agents" plugins/compounding-engineering/.claude-plugin/plugin.json
ls plugins/compounding-engineering/agents/*.md | wc -l

Marketplace.json Structure

The marketplace.json follows the official Claude Code spec:

{
  "name": "marketplace-identifier",
  "owner": {
    "name": "Owner Name",
    "url": "https://github.com/owner"
  },
  "metadata": {
    "description": "Marketplace description",
    "version": "1.0.0"
  },
  "plugins": [
    {
      "name": "plugin-name",
      "description": "Plugin description",
      "version": "1.0.0",
      "author": { ... },
      "homepage": "https://...",
      "tags": ["tag1", "tag2"],
      "source": "./plugins/plugin-name"
    }
  ]
}

Only include fields that are in the official spec. Do not add custom fields like:

• downloads, stars, rating (display-only)
• categories, featured_plugins, trending (not in spec)
• type, verified, featured (not in spec)

Plugin.json Structure

Each plugin has its own plugin.json with detailed metadata:

{
  "name": "plugin-name",
  "version": "1.0.0",
  "description": "Plugin description",
  "author": { ... },
  "keywords": ["keyword1", "keyword2"],
  "components": {
    "agents": 15,
    "commands": 6,
    "hooks": 2
  },
  "agents": {
    "category": [
      {
        "name": "agent-name",
        "description": "Agent description",
        "use_cases": ["use-case-1", "use-case-2"]
      }
    ]
  },
  "commands": {
    "category": ["command1", "command2"]
  }
}

Testing Changes

Test Locally

1. Install the marketplace locally:

   claude /plugin marketplace add /Users/yourusername/every-marketplace
   

2. Install the plugin:

   claude /plugin install compounding-engineering
   

3. Test agents and commands:

   claude /review
   claude agent kieran-rails-reviewer "test message"
   

Validate JSON

Before committing, ensure JSON files are valid:

cat .claude-plugin/marketplace.json | jq .
cat plugins/compounding-engineering/.claude-plugin/plugin.json | jq .

Common Tasks

Adding a New Agent

1. Create plugins/compounding-engineering/agents/new-agent.md
2. Update plugin.json agent count and agent list
3. Update README.md agent list
4. Test with claude agent new-agent "test"

Adding a New Command

1. Create plugins/compounding-engineering/commands/new-command.md
2. Update plugin.json command count and command list
3. Update README.md command list
4. Test with claude /new-command

Adding a New Skill

1. Create skill directory: plugins/compounding-engineering/skills/skill-name/
2. Add skill structure:

   skills/skill-name/
   ├── SKILL.md           # Skill definition with frontmatter (name, description)
   └── scripts/           # Supporting scripts (optional)
   

3. Update plugin.json description with new skill count
4. Update marketplace.json description with new skill count
5. Update README.md with skill documentation
6. Update CHANGELOG.md with the addition
7. Test with claude skill skill-name

Skill file format (SKILL.md):

---
name: skill-name
description: Brief description of what the skill does
---

# Skill Title

Detailed documentation...

Updating Tags/Keywords

Tags should reflect the compounding engineering philosophy:

• Use: ai-powered, compounding-engineering, workflow-automation, knowledge-management
• Avoid: Framework-specific tags unless the plugin is framework-specific

Commit Conventions

Follow these patterns for commit messages:

• Add [agent/command name] - Adding new functionality
• Remove [agent/command name] - Removing functionality
• Update [file] to [what changed] - Updating existing files
• Fix [issue] - Bug fixes
• Simplify [component] to [improvement] - Refactoring

Include the Claude Code footer:

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Resources to search for when needing more information

• Claude Code Plugin Documentation
• Plugin Marketplace Documentation
• Plugin Reference

Key Learnings

This section captures important learnings as we work on this repository.

2024-11-22: Added gemini-imagegen skill and fixed component counts

Added the first skill to the plugin and discovered the component counts were wrong (said 15 agents, actually had 17). Created a comprehensive checklist for updating the plugin to prevent this in the future.

Learning: Always count actual files before updating descriptions. The counts appear in multiple places (plugin.json, marketplace.json, README.md) and must all match. Use the verification commands in the checklist above.

2024-10-09: Simplified marketplace.json to match official spec

The initial marketplace.json included many custom fields (downloads, stars, rating, categories, trending) that aren't part of the Claude Code specification. We simplified to only include:

• Required: name, owner, plugins
• Optional: metadata (with description and version)
• Plugin entries: name, description, version, author, homepage, tags, source

Learning: Stick to the official spec. Custom fields may confuse users or break compatibility with future versions.