Claude Compound Engineering Template

A comprehensive template for building extensible Claude Code projects with agents, skills, plugins, and custom commands. Designed for team collaboration and context sharing.

Overview

This template provides a structured foundation for:

• Subagents: Specialized AI agents for specific tasks
• Skills: Reusable capabilities with supporting resources
• MCP Plugins: Model Context Protocol servers to extend Claude's capabilities
• Slash Commands: Custom commands for common workflows
• Hooks: Event-driven automation (12 hook types)
• Rules: Path-scoped project conventions
• Team Collaboration: Shared config with personal customization layer

Quick Start

# Clone this template
git clone <repository-url>
cd claude-compound-template

# Set up personal configuration
cp .claude/CLAUDE.local.md.template .claude/CLAUDE.local.md
cp .claude/settings.local.json.template .claude/settings.local.json

# Install plugin dependencies (optional)
cd plugins/database-mcp && npm install && npm run build
cd ../api-mcp && npm install && npm run build

# Set required environment variables
export DATABASE_URL="your-database-url"
export API_KEY="your-api-key"

# Start using Claude Code
claude

Project Structure

.
├── CLAUDE.md                        # Project instructions (loaded every session)
├── .mcp.json                        # MCP server configurations
├── .gitignore
│
├── .claude/
│   ├── settings.json                # Permissions, hooks (shared with team)
│   ├── settings.local.json          # Personal settings (gitignored)
│   ├── CLAUDE.local.md              # Personal preferences (gitignored)
│   │
│   ├── commands/                    # Custom slash commands
│   │   ├── review.md                # /review - Code review
│   │   ├── explain.md               # /explain - Code explanation
│   │   ├── test.md                  # /test - Test generation
│   │   ├── docs.md                  # /docs - Documentation
│   │   ├── refactor.md              # /refactor - Refactoring
│   │   ├── debug.md                 # /debug - Debugging
│   │   └── migrate.md               # /migrate - Migrations
│   │
│   ├── agents/                      # Subagent definitions
│   │   ├── research.md              # Research agent
│   │   ├── code-reviewer.md         # Code review agent
│   │   └── test-writer.md           # Test writing agent
│   │
│   ├── skills/                      # Skill definitions
│   │   ├── database-ops/            # Database operations skill
│   │   │   ├── SKILL.md
│   │   │   ├── scripts/
│   │   │   └── references/
│   │   └── api-client/              # API client skill
│   │       ├── SKILL.md
│   │       └── scripts/
│   │
│   └── rules/                       # Path-scoped project rules
│       ├── code-style.md            # *.{ts,tsx,js,jsx}
│       ├── testing.md               # *.{test,spec}.*
│       ├── security.md              # Global security rules
│       ├── api/
│       │   └── endpoints.md         # src/api/**/*
│       └── frontend/
│           └── components.md        # src/components/**/*
│
├── plugins/                         # MCP server implementations
│   ├── database-mcp/
│   │   ├── package.json
│   │   ├── tsconfig.json
│   │   └── src/index.ts
│   └── api-mcp/
│       ├── package.json
│       ├── tsconfig.json
│       └── src/index.ts
│
├── hooks/                           # Hook scripts
│   ├── README.md
│   ├── session-start.sh             # SessionStart hook
│   ├── user-prompt-submit.sh        # UserPromptSubmit hook
│   ├── pre-bash.sh                  # PreToolUse for Bash
│   ├── pre-commit.sh                # PreToolUse for git commit
│   ├── post-edit.sh                 # PostToolUse for Edit
│   └── notification.sh              # Notification hook
│
├── prompts/                         # Reusable prompt templates
│   └── templates/
│       └── bug-report.md
│
└── tools/                           # Utility scripts
    └── README.md

Custom Slash Commands

All commands support YAML frontmatter with description, allowed-tools, and argument-hint.

Command	Description	Allowed Tools
/review <file>	Security & quality code review	Read, Glob, Grep
/explain <file>	Detailed code explanation	Read, Glob, Grep
/test <file>	Generate comprehensive tests	Read, Write, Glob, Grep, Bash
/docs <file>	Generate documentation	Read, Write, Glob, Grep
/refactor <file>	Refactoring suggestions	Read, Write, Edit, Glob, Grep
/debug <error>	Debug and root cause analysis	Read, Glob, Grep, Bash
/migrate <desc>	Migration planning	Read, Write, Edit, Glob, Grep, Bash

Subagents

Subagents are markdown files with YAML frontmatter in .claude/agents/:

---
name: code-reviewer
description: Expert code review specialist
tools: Read, Glob, Grep, Bash
model: sonnet
---

System prompt content...

Agent	Purpose	Tools
research	Web research and synthesis	WebSearch, WebFetch, Read, Write, Glob
code-reviewer	Security and quality reviews	Read, Glob, Grep, Bash
test-writer	Comprehensive test generation	Read, Write, Glob, Grep, Bash

Skills

Skills are directories in .claude/skills/ with a SKILL.md file:

---
name: database-ops
description: Database operations and queries
---

Skill instructions...

Skill	Purpose
database-ops	Database queries, schema inspection
api-client	HTTP requests, API integration

Rules (Path-Scoped)

Rules in .claude/rules/ are automatically loaded. Use YAML frontmatter to scope rules to specific paths:

---
paths: "src/api/**/*.ts"
---

# These rules only apply to API files

Rule	Scope
code-style.md	**/*.{ts,tsx,js,jsx}
testing.md	**/*.{test,spec}.*
security.md	Global
api/endpoints.md	src/api/**/*
frontend/components.md	src/components/**/*

Hooks

All 12 hook types are supported. See hooks/README.md for details.

Hook	When	Can Block
SessionStart	Session begins	No
UserPromptSubmit	User sends prompt	Yes
PreToolUse	Before tool runs	Yes
PostToolUse	After tool succeeds	No
Notification	Notifications sent	No

MCP Configuration

MCP servers are configured in .mcp.json at project root:

{
  "mcpServers": {
    "database": {
      "command": "node",
      "args": ["plugins/database-mcp/dist/index.js"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

Team Collaboration

Shared Configuration (Version Controlled)

File/Directory	Purpose
.claude/settings.json	Team permissions, hooks
.claude/commands/	Team slash commands
.claude/agents/	Team subagents
.claude/skills/	Team skills
.claude/rules/	Project conventions
.mcp.json	MCP servers
CLAUDE.md	Project instructions

Personal Configuration (Gitignored)

File	Purpose
.claude/CLAUDE.local.md	Personal preferences
.claude/settings.local.json	Personal settings

Environment Variables

Required for MCP servers:

export DATABASE_URL="postgresql://..."
export API_KEY="your-api-key"
export GITHUB_TOKEN="ghp_..."

Development

Building Plugins

cd plugins/database-mcp
npm install
npm run build

Creating Commands

Create .claude/commands/your-command.md:

---
description: What the command does
allowed-tools: Read, Write
argument-hint: <required-arg> [optional-arg]
---

Command prompt content with $ARGUMENTS placeholder

Creating Subagents

Create .claude/agents/your-agent.md:

---
name: your-agent
description: What the agent does
tools: Read, Write, Bash
model: inherit
---

Agent system prompt...

Creating Skills

Create .claude/skills/your-skill/SKILL.md:

---
name: your-skill
description: What the skill provides
---

Skill documentation and instructions...

Best Practices

1. Security: Never commit secrets; use environment variables with ${VAR} syntax
2. Rules: Keep rules focused; use path scoping to reduce noise
3. Hooks: Keep interactive hooks fast (< 1 second)
4. Commands: Use allowed-tools to limit command scope
5. Documentation: Keep CLAUDE.md concise (loaded every session)
6. Testing: Test hooks and commands locally before committing

License

MIT