Let's see what this thing can actually do. I'll show you three workflows you'll use constantly:
This is the big one. Type /workflows:review and watch it spawn 10+ specialized reviewers:
Sometimes you just need one expert. Call them directly:
# Rails code review with Kieran's conventions
claude agent kieran-rails-reviewer "Review the UserController"
@@ -160,7 +157,7 @@ claude agent best-practices-researcher "Find pagination patterns for Rails"
Invoke a Skill
- Skills provide domain expertise on demand:
+ Skills are like loading a reference book into Claude's brain. When you need deep knowledge in a specific domain:
# Generate images with Gemini
skill: gemini-imagegen
@@ -179,7 +176,7 @@ skill: create-agent-skills
MCP Server Configuration
- If MCP servers don't auto-load, add them manually to your .claude/settings.json:
+ If the MCP servers didn't load automatically, paste this into .claude/settings.json:
{
@@ -199,7 +196,7 @@ skill: create-agent-skills
Environment Variables
-
Some skills require environment variables:
+
Right now, only one skill needs an API key. If you use Gemini's image generation:
@@ -226,39 +223,35 @@ skill: create-agent-skills
Every unit of engineering work should make subsequent units of work easier—not harder.
- This philosophy manifests in four key practices:
+ Here's how it works in practice—the four-step loop you'll run over and over:
-
Plan
+
1. Plan
- Understand the change needed and its impact before writing code.
- Use research agents to gather context, best practices, and examples.
+ Before you write a single line, figure out what you're building and why. Use research agents to gather examples, patterns, and context. Think of it as Google Search meets expert consultation.
-
Delegate
+
2. Delegate
- Use specialized AI agents to help with implementation.
- Each agent brings deep expertise in its domain.
+ Now build it—with help. Each agent specializes in something (Rails, security, design). You stay in the driver's seat, but you've got a team of specialists riding shotgun.
-
Assess
+
3. Assess
- Run comprehensive reviews with multiple perspectives.
- Security, performance, architecture—all covered by specialized agents.
+ Before you ship, run the gauntlet. Security agent checks for vulnerabilities. Performance agent flags N+1 queries. Architecture agent questions your design choices. All at once, all in parallel.
-
Codify
+
4. Codify
- Document learnings and patterns for future use.
- Each solved problem becomes reusable knowledge.
+ You just solved a problem. Write it down. Next time you (or your teammate) face this, you'll have a runbook. That's the "compounding" part—each solution makes the next one faster.
@@ -269,8 +262,7 @@ skill: create-agent-skills
Using Agents
- Agents are specialized personas that can be invoked to perform specific tasks.
- They're designed to bring deep expertise in their domain.
+ Think of agents as coworkers with different job titles. You wouldn't ask your security engineer to design your UI, right? Same concept here—each agent has a specialty, and you call the one you need.
Invoking Agents
@@ -334,8 +326,7 @@ claude agent git-history-analyzer "Show changes to user model"
Using Commands
- Slash commands automate complex multi-step workflows. They orchestrate
- multiple agents, tools, and processes into a single command.
+ Commands are macros that run entire workflows for you. One command can spin up a dozen agents, coordinate their work, collect results, and hand you a summary. It's automation all the way down.
Running Commands
@@ -353,14 +344,14 @@ claude agent git-history-analyzer "Show changes to user model"
The Review Workflow
- The /workflows:review command is the most comprehensive. It:
+ Let me show you what happens when you run /workflows:review. Here's the sequence:
- - Detects the review target (PR, branch, or current changes)
- - Sets up a git worktree for isolated analysis
- - Runs 10 or more review agents in parallel
- - Synthesizes findings by severity (P1/P2/P3)
- - Creates structured todo files for each finding
- - Generates a summary report
+ - Detection - Figures out what you want reviewed (PR number, branch name, or current changes)
+ - Isolation - Spins up a git worktree so the review doesn't mess with your working directory
+ - Parallel execution - Launches 10+ agents simultaneously (security, performance, architecture, accessibility...)
+ - Synthesis - Sorts findings by severity (P1 = blocks merge, P2 = should fix, P3 = nice-to-have)
+ - Persistence - Creates todo files so you don't lose track of issues
+ - Summary - Hands you a readable report with action items
@@ -375,9 +366,7 @@ claude agent git-history-analyzer "Show changes to user model"
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.
+ Here's the difference: agents are who does the work, skills are what they know. When you invoke a skill, you're loading a reference library into Claude's context—patterns, templates, examples, workflows. It's like handing Claude a technical manual.
Invoking Skills
@@ -390,13 +379,13 @@ skill: gemini-imagegen
Skill Structure
- Skills typically contain:
+ Peek inside a skill directory and you'll usually find:
- - SKILL.md - Main documentation and instructions
- - references/ - Supporting documentation
- - templates/ - Code templates and patterns
- - workflows/ - Step-by-step procedures
- - scripts/ - Executable scripts (if needed)
+ - SKILL.md - The main instructions (what Claude reads first)
+ - references/ - Deep dives on concepts and patterns
+ - templates/ - Copy-paste code snippets
+ - workflows/ - Step-by-step "how to" guides
+ - scripts/ - Actual executable code (when words aren't enough)
@@ -411,8 +400,7 @@ skill: gemini-imagegen
Code Review Workflow Guide
- The code review workflow is the heart of Compounding Engineering.
- Here's how to get the most out of it.
+ You'll spend most of your time here. This workflow is why the plugin exists—to turn code review from a bottleneck into a superpower.
Basic Review
@@ -425,15 +413,15 @@ skill: gemini-imagegen
Understanding Findings
- Findings are categorized by severity:
+ Every finding gets a priority label. Here's what they mean:
- - 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.
+ - P1 Critical - Don't merge until this is fixed. Think: SQL injection, data loss, crashes in production.
+ - P2 Important - Fix before shipping. Performance regressions, N+1 queries, shaky architecture.
+ - P3 Nice-to-Have - Would be better, but ship without it if you need to. Documentation, minor cleanup, style issues.
Working with Todo Files
- Review findings are stored as todo files in the todos/ directory:
+ After a review, you'll have a todos/ directory full of markdown files. Each one is a single issue to fix:
# List all pending todos
ls todos/*-pending-*.md
@@ -451,8 +439,7 @@ ls todos/*-pending-*.md
Creating Custom Agents
- You can create custom agents tailored to your team's needs.
- Agents are defined as markdown files with YAML frontmatter.
+ The built-in agents cover a lot of ground, but every team has unique needs. Maybe you want a "rails-api-reviewer" that enforces your company's API standards. That's 10 minutes of work.
Agent File Structure
@@ -476,19 +463,18 @@ You are [role description].
Agent Location
- Place custom agents in:
+ Drop your agent file in one of these directories:
- .claude/agents/ - Project-specific agents~/.claude/agents/ - User-wide agents.claude/agents/ - Just for this project (committed to git)~/.claude/agents/ - Available in all your projects (stays on your machine)
-
Use the Command
+
The Easy Way
- The easiest way to create agents is with the /create-agent-skill command
- or the create-agent-skills skill.
+ Don't write the YAML by hand. Just run /create-agent-skill and answer a few questions. The command generates the file, validates the format, and puts it in the right place.
@@ -499,8 +485,7 @@ You are [role description].
Creating Custom Skills
- Skills are more complex than agents. They can include references,
- templates, workflows, and scripts.
+ Skills are heavier than agents—they're knowledge bases, not just prompts. You're building a mini library that Claude can reference. Worth the effort for things you do repeatedly.
Skill Directory Structure
@@ -542,10 +527,9 @@ Use templates from the `templates/` directory.
-
Expert Guidance
+
Get Help Building Skills
- Use skill: create-agent-skills for comprehensive guidance
- on creating effective skills, including best practices and validation.
+ Type skill: create-agent-skills and Claude loads expert guidance on skill architecture, best practices, file organization, and validation. It's like having a senior engineer walk you through it.
diff --git a/docs/pages/mcp-servers.html b/docs/pages/mcp-servers.html
index 94b5a11..ecc2f3c 100644
--- a/docs/pages/mcp-servers.html
+++ b/docs/pages/mcp-servers.html
@@ -73,9 +73,7 @@
MCP Servers Reference
- Model Context Protocol (MCP) servers extend Claude Code's capabilities with
- browser automation and framework documentation lookup. The plugin bundles
- two MCP servers that start automatically when enabled.
+ Think of MCP servers as power tools that plug into Claude Code. Want Claude to actually open a browser and click around your app? That's Playwright. Need the latest Rails docs without leaving your terminal? That's Context7. The plugin bundles both servers—they just work when you install.
@@ -83,8 +81,7 @@
Known Issue: Auto-Loading
- MCP servers may not load automatically when the plugin is installed.
- See Manual Configuration for the workaround.
+ Sometimes MCP servers don't wake up automatically. If Claude can't take screenshots or look up docs, you'll need to add them manually. See Manual Configuration for the fix.
Playwright
- Browser automation via @playwright/mcp. Enables taking screenshots,
- clicking elements, filling forms, and executing JavaScript in a real browser.
+ You know how you can tell a junior developer "open Chrome and click the login button"? Now you can tell Claude the same thing. Playwright gives Claude hands to control a real browser—clicking buttons, filling forms, taking screenshots, running JavaScript. It's like pair programming with someone who has a browser open next to you.
Tools Provided
@@ -108,49 +104,53 @@
browser_navigate |
- Navigate to a URL in the browser |
+ Go to any URL—your localhost dev server, production, staging, that competitor's site you're studying |
browser_take_screenshot |
- Capture a screenshot of the current page or element |
+ Capture what you're seeing right now. Perfect for "does this look right?" design reviews |
browser_click |
- Click on an element using CSS selector or text |
+ Click buttons, links, whatever. Claude finds it by text or CSS selector, just like you would |
browser_fill_form |
- Fill form fields with values |
+ Type into forms faster than you can. Great for testing signup flows without manual clicking |
browser_snapshot |
- Get an accessibility tree snapshot of the page |
+ Get the page's accessibility tree—how screen readers see it. Useful for understanding structure without HTML noise |
browser_evaluate |
- Execute JavaScript code in the browser context |
+ Run any JavaScript in the page. Check localStorage, trigger functions, read variables—full console access |
-
Use Cases
+
When You'll Use This
- - Design Iteration - Take screenshots for UI comparison
- - Testing - Automate browser interactions
- - Debugging - Inspect page state and DOM
- - Data Extraction - Scrape content from web pages
+ - Design reviews without leaving the terminal - "Take a screenshot of the new navbar on mobile" gets you a PNG in seconds
+ - Testing signup flows while you code - "Fill in the registration form with test@example.com and click submit" runs the test for you
+ - Debugging production issues - "Navigate to the error page and show me what's in localStorage" gives you the state without opening DevTools
+ - Competitive research - "Go to competitor.com and screenshot their pricing page" builds your swipe file automatically
Example Usage
-
# The tools are available when the MCP server is running
-# Claude Code will use them automatically when appropriate
+ # Just talk to Claude naturally—it knows when to use Playwright
-# Example: Taking a screenshot for design review
+# Design review
"Take a screenshot of the login page"
-# Example: Testing a form
-"Navigate to /signup and fill in the email field with test@example.com"
+# Testing a form
+"Navigate to /signup and fill in the email field with test@example.com"
+
+# Debug JavaScript state
+"Go to localhost:3000 and run console.log(window.currentUser)"
+
+# The browser runs in the background. You'll get results without switching windows.
Configuration
@@ -170,8 +170,7 @@
Context7
- Framework documentation lookup via Context7 MCP. Provides access to
- documentation for more than 100 frameworks and libraries.
+ Ever ask Claude about a framework and get an answer from 2023? Context7 fixes that. It's a documentation service that keeps Claude current with 100+ frameworks—Rails, React, Next.js, Django, whatever you're using. Think of it as having the official docs piped directly into Claude's brain.
Tools Provided
@@ -185,17 +184,17 @@
resolve-library-id |
- Find the library ID for a framework or package |
+ Maps "Rails" to the actual library identifier Context7 uses. You don't call this—Claude does it automatically |
get-library-docs |
- Get documentation for a specific library |
+ Fetches the actual documentation pages. Ask "How does useEffect work?" and this grabs the latest React docs |
- Supported Frameworks
- Context7 supports more than 100 frameworks including:
+ What's Covered
+ Over 100 frameworks and libraries. Here's a taste of what you can look up:
Backend
@@ -243,12 +242,15 @@
Example Usage
-
# Claude Code will use Context7 automatically for documentation lookups
+ # Just ask about the framework—Claude fetches current docs automatically
+
"Look up the Rails ActionCable documentation"
"How does the useEffect hook work in React?"
-"What are the best practices for PostgreSQL indexes?"
+"What are the best practices for PostgreSQL indexes?"
+
+# You get answers based on the latest docs, not Claude's training cutoff
Configuration
@@ -266,12 +268,11 @@
Manual Configuration
- If MCP servers don't auto-load with the plugin, add them manually to your
- .claude/settings.json file.
+ If the servers don't load automatically (you'll know because Claude can't take screenshots or fetch docs), you need to wire them up yourself. It's a two-minute copy-paste job.
Project-Level Configuration
- Add to .claude/settings.json in your project:
+ To enable for just this project, add this to .claude/settings.json in your project root:
{
"mcpServers": {
@@ -290,7 +291,7 @@
Global Configuration
- Add to ~/.claude/settings.json to enable for all projects:
+ Or enable everywhere—every project on your machine gets these servers. Add to ~/.claude/settings.json:
{
"mcpServers": {
@@ -329,16 +330,18 @@
Verifying MCP Servers
- After configuration, restart Claude Code and verify the servers are loaded:
+ After you add the config, restart Claude Code. Then test that everything works:
-
# Check if MCP tools are available
+ # Ask Claude what it has
"What MCP tools do you have access to?"
-# Test Playwright
+# Test Playwright (should work now)
"Take a screenshot of the current directory listing"
-# Test Context7
-"Look up Rails Active Record documentation"
+# Test Context7 (should fetch real docs)
+"Look up Rails Active Record documentation"
+
+# If either fails, double-check your JSON syntax and file paths
Skill Reference
- Complete documentation for all 11 intelligent skills. Skills provide deep domain expertise
- that Claude Code can invoke on-demand, including references, templates, and workflows.
+ Think of skills as reference manuals that Claude Code can read mid-conversation. When you're writing Rails code and want DHH's style, or building a gem like Andrew Kane would, you don't need to paste documentation—just invoke the skill. Claude reads it, absorbs the patterns, and writes code that way.
@@ -95,8 +94,7 @@ skill: create-agent-skills
Skills vs Agents
- Agents are specialized personas invoked with claude agent [name].
- Skills are bodies of knowledge (references, templates, workflows) invoked with skill: [name].
+ Agents are personas—they do things. Skills are knowledge—they teach Claude how to do things. Use claude agent [name] when you want someone to review your code. Use skill: [name] when you want to write code in a particular style yourself.
- Write Ruby and Rails code in DHH's distinctive 37signals style.
- Triggers on Ruby/Rails code generation or when mentioning DHH, 37signals, Basecamp, HEY.
+ You want Rails controllers that are five lines, not fifty. Models that handle authorization, broadcasting, and business logic without service objects everywhere. This skill teaches Claude to write code the way DHH writes it at 37signals—REST-pure, Hotwire-first, no architectural astronautics.
Key Patterns
@@ -196,8 +192,7 @@ skill: create-agent-skills
Ruby
- Write Ruby gems following Andrew Kane's proven patterns and philosophy.
- Based on 100+ gems with 374M+ downloads.
+ Andrew Kane has written 100+ Ruby gems with 374 million downloads. Every gem follows the same patterns: minimal dependencies, class macro DSLs, Rails integration without Rails coupling. When you're building a gem and want it to feel production-ready from day one, this is how you do it.
Philosophy
@@ -232,8 +227,7 @@ skill: create-agent-skills
AI
- Build type-safe, composable LLM applications with DSPy.rb.
- Use when implementing predictable AI features in Ruby.
+ You're adding AI features to your Rails app, but you don't want brittle prompt strings scattered everywhere. DSPy.rb gives you type-safe signatures, composable predictors, and tool-using agents. This skill shows you how to use it—from basic inference to ReAct agents that iterate until they get the answer right.
Predictor Types
@@ -276,8 +270,7 @@ skill: create-agent-skills
Design
- Create distinctive, production-grade frontend interfaces.
- Generates creative, polished code that avoids generic AI aesthetics.
+ You've seen what AI usually generates: Inter font, purple gradients, rounded corners on everything. This skill teaches Claude to design interfaces that don't look like every other AI-generated site. It's about purposeful typography, unexpected color palettes, and interfaces with personality.
Design Thinking
@@ -311,7 +304,7 @@ skill: create-agent-skills
Docs
- Capture solved problems as categorized documentation with YAML frontmatter for fast lookup.
+ You just fixed a weird build error after an hour of debugging. Tomorrow you'll forget how you fixed it. This skill automatically detects when you solve something (phrases like "that worked" or "it's fixed") and documents it with YAML frontmatter so you can find it again. Think of it as a photographic memory for solved problems.
Content & Workflow (3)
- Skills for content editing, task tracking, and parallel development.
+ Writing, editing, and organizing work. These skills handle everything from style guide compliance to git worktree management—the meta-work that makes the real work easier.
- Review and edit copy to ensure adherence to Every's style guide.
- Provides systematic line-by-line review.
+ You wrote a draft, but you're not sure if it matches Every's style guide. Should "internet" be capitalized? Is this comma splice allowed? This skill does a four-phase line-by-line review: context, detailed edits, mechanical checks, and actionable recommendations. It's like having a copy editor who never gets tired.
Four-Phase Review
@@ -380,8 +372,7 @@ skill: create-agent-skills
Workflow
- File-based todo tracking system in the todos/ directory.
- Integrates with code review and slash commands.
+ Your todo list is a bunch of markdown files in a todos/ directory. Each filename encodes status, priority, and description. No database, no UI, just files with YAML frontmatter. When you need to track work without setting up Jira, this is the system.
File Format
@@ -426,8 +417,7 @@ dependencies: []
Git
- Manage Git worktrees for isolated parallel development.
- Handles creating, listing, switching, and cleaning up worktrees.
+ You're working on a feature branch, but you need to review a PR without losing your current work. Git worktrees let you have multiple branches checked out simultaneously in separate directories. This skill manages them—create, switch, cleanup—so you can context-switch without stashing or committing half-finished code.
Commands
@@ -462,7 +452,7 @@ bash scripts/worktree-manager.sh cleanup
Image Generation (1)
- AI-powered image generation and editing.
+ Generate images with AI. Not stock photos you found on Unsplash—images you describe and the model creates.
- Generate and edit images using Google's Gemini API (Nano Banana).
- Supports text-to-image, image editing, multi-turn refinement, and composition.
+ Need a logo with specific text? A product mockup on a marble surface? An illustration in a kawaii style? This skill wraps Google's Gemini image generation API. You describe what you want, it generates it. You can edit existing images, refine over multiple turns, or compose from reference images. All through simple Python scripts.
Features