Getting Started with Compounding Engineering
++ This guide will help you install, configure, and start using the Compounding Engineering plugin + for Claude Code. In about 5 minutes, you'll have access to 24 specialized agents, 16 commands, + 11 skills, and 2 MCP servers. +
+ + +Installation
+ +Prerequisites
+-
+
- Claude Code installed and configured +
- A GitHub account (for marketplace access) +
- Node.js 18+ (for MCP servers) +
Step 1: Add the Marketplace
+First, add the Every Marketplace to your Claude Code installation:
+claude /plugin marketplace add https://github.com/EveryInc/every-marketplaceStep 2: Install the Plugin
+Install the compounding-engineering plugin from the marketplace:
+claude /plugin install compounding-engineeringStep 3: Verify Installation
+Verify the plugin is installed correctly:
+claude /plugin listYou should see compounding-engineering in the list of installed plugins.
Known Issue: MCP Servers
++ The bundled MCP servers (Playwright and Context7) may not load automatically. + See the MCP Configuration section for the workaround. +
+Quick Start
+ +Here are the most common ways to use the plugin:
+ +Run a Code Review
+The /workflows:review command runs a comprehensive code review using multiple agents in parallel:
# Review a PR by number
+/workflows:review 123
+
+# Review the current branch
+/workflows:review
+
+# Review a specific branch
+/workflows:review feature/my-featureUse a Specialized Agent
+Invoke agents directly for specific tasks:
+# Rails code review with Kieran's conventions
+claude agent kieran-rails-reviewer "Review the UserController"
+
+# Security audit
+claude agent security-sentinel "Audit authentication flow"
+
+# Research best practices
+claude agent best-practices-researcher "Find pagination patterns for Rails"Invoke a Skill
+Skills provide domain expertise on demand:
+# Generate images with Gemini
+skill: gemini-imagegen
+
+# Write Ruby in DHH's style
+skill: dhh-ruby-style
+
+# Create a new Claude Code skill
+skill: create-agent-skillsConfiguration
+ +MCP Server Configuration
+
+ If MCP servers don't auto-load, add them manually to your .claude/settings.json:
+
{
+ "mcpServers": {
+ "playwright": {
+ "type": "stdio",
+ "command": "npx",
+ "args": ["-y", "@playwright/mcp@latest"],
+ "env": {}
+ },
+ "context7": {
+ "type": "http",
+ "url": "https://mcp.context7.com/mcp"
+ }
+ }
+}Environment Variables
+Some skills require environment variables:
+| Variable | +Required For | +Description | +
|---|---|---|
GEMINI_API_KEY |
+ gemini-imagegen | +Google Gemini API key for image generation | +
The Compounding Engineering Philosophy
+ ++ Every unit of engineering work should make subsequent units of work easier—not harder. ++ +
This philosophy manifests in four key practices:
+ +Plan
++ Understand the change needed and its impact before writing code. + Use research agents to gather context, best practices, and examples. +
+Delegate
++ Use specialized AI agents to help with implementation. + Each agent brings deep expertise in its domain. +
+Assess
++ Run comprehensive reviews with multiple perspectives. + Security, performance, architecture—all covered by specialized agents. +
+Codify
++ Document learnings and patterns for future use. + Each solved problem becomes reusable knowledge. +
+Using Agents
+ ++ Agents are specialized personas that can be invoked to perform specific tasks. + They're designed to bring deep expertise in their domain. +
+ +Invoking Agents
+# Basic syntax
+claude agent [agent-name] "[optional message]"
+
+# Examples
+claude agent kieran-rails-reviewer
+claude agent security-sentinel "Audit the payment flow"
+claude agent git-history-analyzer "Show changes to user model"Agent Categories
+| Category | +Count | +Purpose | +
|---|---|---|
| Review | +10 | +Code review, security audits, performance analysis | +
| Research | +4 | +Best practices, documentation, git history | +
| Design | +3 | +UI iteration, Figma sync, design review | +
| Workflow | +6 | +Bug reproduction, PR resolution, linting | +
| Docs | +1 | +README generation | +
Using Commands
+ ++ Slash commands automate complex multi-step workflows. They orchestrate + multiple agents, tools, and processes into a single command. +
+ +Running Commands
+# Workflow commands (prefix: /workflows:)
+/workflows:plan
+/workflows:review 123
+/workflows:work
+/workflows:codify
+
+# Utility commands
+/changelog
+/triage
+/reproduce-bugThe Review Workflow
+The /workflows:review command is the most comprehensive. It:
-
+
- Detects the review target (PR, branch, or current changes) +
- Sets up a git worktree for isolated analysis +
- Runs 10+ review agents in parallel +
- Synthesizes findings by severity (P1/P2/P3) +
- Creates structured todo files for each finding +
- Generates a summary report +
Using Skills
+ ++ Skills provide domain expertise that Claude Code can invoke on-demand. + Unlike agents (which are personas), skills are bodies of knowledge with + templates, references, and workflows. +
+ +Invoking Skills
+# In your prompt, reference the skill
+skill: gemini-imagegen
+
+# Or ask Claude to use it
+"Use the dhh-ruby-style skill to refactor this code"Skill Structure
+Skills typically contain:
+-
+
- SKILL.md - Main documentation and instructions +
- references/ - Supporting documentation +
- templates/ - Code templates and patterns +
- workflows/ - Step-by-step procedures +
- scripts/ - Executable scripts (if needed) +
Code Review Workflow Guide
+ ++ The code review workflow is the heart of Compounding Engineering. + Here's how to get the most out of it. +
+ +Basic Review
+# Review a PR
+/workflows:review 123
+
+# Review current branch
+/workflows:reviewUnderstanding Findings
+Findings are categorized by severity:
+-
+
- P1 Critical - Blocks merge. Security vulnerabilities, data corruption risks, breaking changes. +
- P2 Important - Should fix. Performance issues, architectural concerns, reliability problems. +
- P3 Nice-to-Have - Enhancements. Minor improvements, cleanup, documentation. +
Working with Todo Files
+Review findings are stored as todo files in the todos/ directory:
# List all pending todos
+ls todos/*-pending-*.md
+
+# Triage findings
+/triage
+
+# Resolve todos in parallel
+/resolve_todo_parallelCreating Custom Agents
+ ++ You can create custom agents tailored to your team's needs. + Agents are defined as markdown files with YAML frontmatter. +
+ +Agent File Structure
+---
+name: my-custom-agent
+description: Brief description of what this agent does
+---
+
+# Agent Instructions
+
+You are [role description].
+
+## Your Responsibilities
+1. First responsibility
+2. Second responsibility
+
+## Guidelines
+- Guideline one
+- Guideline twoAgent Location
+Place custom agents in:
+-
+
.claude/agents/- Project-specific agents
+ ~/.claude/agents/- User-wide agents
+
Use the Command
+
+ The easiest way to create agents is with the /create-agent-skill command
+ or the create-agent-skills skill.
+
Creating Custom Skills
+ ++ Skills are more complex than agents. They can include references, + templates, workflows, and scripts. +
+ +Skill Directory Structure
+my-skill/
+ SKILL.md # Main skill file (required)
+ references/ # Supporting documentation
+ concept-one.md
+ concept-two.md
+ templates/ # Code templates
+ basic-template.md
+ workflows/ # Step-by-step procedures
+ workflow-one.md
+ scripts/ # Executable scripts
+ helper.pySKILL.md Format
+---
+name: my-skill
+description: Brief description shown when skill is invoked
+---
+
+# Skill Title
+
+Detailed instructions for using this skill.
+
+## Quick Start
+...
+
+## Reference Materials
+The skill includes references in the `references/` directory.
+
+## Templates
+Use templates from the `templates/` directory.Expert Guidance
+
+ Use skill: create-agent-skills for comprehensive guidance
+ on creating effective skills, including best practices and validation.
+