monorepo-initialization

Monorepo Initialization Skill

Purpose

Systematically initialize AGENTS.md files throughout a monorepo, creating a hierarchical context system where:

• Root AGENTS.md coordinates all agents
• Each package/service has its own AGENTS.md with hierarchy metadata
• All files link back to root CLAUDE.md (philosophy)
• AI agents can navigate context efficiently across packages

This enables large projects to maintain clear, navigable agent guidance without overwhelming token budgets.

When to Use

• New monorepo setup - Initialize entire project structure
• Adding new packages - Run on new subdirectory
• Improving agent context - Refresh existing AGENTS.md files
• Scaling team - Ensure new members understand cross-package dependencies
• Microservices - Document each service's agent context independently

The Problem

Without structured AGENTS.md hierarchy:

• Agents get confused about project structure
• Context is scattered or missing
• Cross-package dependencies aren't clear
• Scaling to 5+ packages becomes difficult
• New team members waste time understanding structure

With this skill:

• Agents understand full project structure
• Each package has focused, actionable guidance
• Dependencies and integration points are documented
• Scales to 20+ packages without confusion

Process

Phase 1: Discovery (5-10 minutes)

Script automatically scans for:

• Project files: package.json, go.mod, Cargo.toml, pyproject.toml, pom.xml
• Directories: src/, lib/, components/, services/
• Config files: .cursorrules, .github/copilot-instructions.md
• Documentation: README.md, docs/

Scoring heuristic:

Project file present:     +10 points
src/lib/components dir:   +5 points
Config file present:      +3 points
>10 source files:         +3 points
README/docs present:      +2 points
Threshold: > 5 points = initialize

Phase 2: Root Analysis

Create root AGENTS.md containing:

• Project overview
• All agents and their modes
• Available commands and skills
• Directory structure index (table of all packages)
• Hierarchy linking explanation

Example:

# Project Agents

## Directory Structure

| Package | Level | Purpose | Key Files |
|---------|-------|---------|-----------|
| `packages/api` | API Services | REST backend | src/routes/, src/models/ |
| `packages/web` | Frontend | React UI | src/components/, src/pages/ |

## Hierarchy Linking

Each package maintains its own AGENTS.md with:
- **Hierarchy Level**: Role in system (e.g., "API Services")
- **Parent**: Link to this AGENTS.md
- **Philosophy**: Link to CLAUDE.md

See individual AGENTS.md files for package-specific guidance.

Phase 3: Package Initialization

For each important subdirectory, create localized AGENTS.md (~20 lines):

Metadata (Required per Anthropic hierarchy docs):

---
hierarchy:
  level: "API Services"
  parent: "../AGENTS.md"
  philosophy: "../../CLAUDE.md"
---

# API Service Agents

Content:

• Framework/tech stack used
• Build/lint/test commands with examples
• Code style guidelines (imports, formatting, naming)
• Common patterns specific to this package
• Integration points with other packages
• Key files and their purposes

Example for API package:

# API Service Agents

**Hierarchy Level**: API Services (REST backend, database layer)  
**Parent**: [../AGENTS.md](../AGENTS.md)  
**Philosophy**: [CLAUDE.md](../../CLAUDE.md)

## Tech Stack

- Express.js (server framework)
- TypeScript (type safety)
- Prisma (ORM)
- PostgreSQL (database)

## Key Commands

```bash
# Development
npm run dev              # Start dev server on :3000
npm run build            # Compile TypeScript
npm run test             # Run Jest tests
npm run test:watch       # Watch mode

# Single test example
npm test -- routes.test.ts

# Linting & formatting
npm run lint             # ESLint check
npm run format           # Prettier format

Code Style

Imports: Absolute paths from src/, relative for same package

import { UserService } from '@api/services'  // Cross-package
import { helper } from '../utils'             // Local

Naming: camelCase functions, PascalCase classes, UPPER_SNAKE_CASE constants

Types: Explicit return types for all functions, use Zod for runtime validation

Patterns

• Services: Business logic in /services, thin controllers
• Models: Prisma schemas in /prisma/schema.prisma
• Error handling: Use custom AppError class with status codes
• Logging: Use logger instance (shared/logger)

Integration Points

• Web package: Uses /api/* routes via fetch
• Shared package: Uses types and utilities from shared
• Database: Migrations in /prisma/migrations

AI Agent Guidance

For Claude/GPT working in this package:

1. Follow Express.js patterns (middleware, routing)
2. Always add types (no any)
3. Write tests alongside features
4. Update Prisma schema, run migrations
5. Reference /shared for shared types/utilities

### Phase 4: Root CLAUDE.md Update

Update (or create) root CLAUDE.md to document the hierarchy:

```markdown
# Project Philosophy

[Your guiding principles and vision...]

## Agent Coordination

See **[AGENTS.md](./AGENTS.md)** for:
- Agents and their modes (plan/build/review)
- Available commands and skills
- Directory context index

This CLAUDE.md defines **philosophy**. AGENTS.md documents **agents and tools**.

## Agent Contexts (Hierarchical)

Each package/service maintains specialized agent context:

| Directory | AGENTS.md | Level | Purpose |
|-----------|-----------|-------|---------|
| Root | [AGENTS.md](./AGENTS.md) | Coordination | Project overview, cross-package agents |
| `packages/api` | [packages/api/AGENTS.md](./packages/api/AGENTS.md) | API Services | REST backend, database layer |
| `packages/web` | [packages/web/AGENTS.md](./packages/web/AGENTS.md) | Frontend | React UI, styling, client logic |
| `packages/shared` | [packages/shared/AGENTS.md](./packages/shared/AGENTS.md) | Shared Utilities | Types, helpers, common code |

Each subdirectory's AGENTS.md includes hierarchy metadata:
- **Hierarchy Level**: Role in system architecture
- **Parent**: Link to parent AGENTS.md for coordination
- **Philosophy**: Link to this CLAUDE.md for guiding principles

This three-tier system (philosophy → coordination → specialization) allows AI agents to:
1. Understand project vision and values (CLAUDE.md)
2. Understand cross-package structure (root AGENTS.md)
3. Get specialized guidance for their specific package (package AGENTS.md)

Phase 5: Verification & Cleanup

Verify all links work:

✓ Root AGENTS.md exists and links to all packages
✓ Root CLAUDE.md lists all AGENTS.md files
✓ Each package AGENTS.md has hierarchy metadata
✓ No broken relative paths
✓ Build commands are tested (where applicable)

Cleanup:

git add .
git commit -m "chore: initialize monorepo AGENTS.md hierarchy"

Usage

CLI (from root):

# Initialize entire project (interactive)
/monorepo-initialization

# Dry-run: preview without changes
/monorepo-initialization --dry-run

# Initialize with specific depth
/monorepo-initialization --depth=3

# Re-initialize (overwrite existing)
/monorepo-initialization --preserve=false

# Initialize specific directory
/monorepo-initialization packages/my-new-service

OpenCode:

use_skill("monorepo-initialization", {
    "depth": 2,
    "dry_run": False,
    "preserve": False
})

Claude Code:

Use monorepo-initialization skill to set up AGENTS.md hierarchy for new packages

Options

Flag	Description	Default
--depth N	Maximum recursion depth	2
--dry-run	Preview without making changes	false
--preserve	Keep existing AGENTS.md files	false
--batch-size N	Process N directories at a time	3
--min-score N	Minimum importance score to initialize	5
--include <pattern>	Additional patterns to scan	-
--exclude <pattern>	Skip matching directories	node_modules,.git,dist,build

Directory Scoring

Automatically scores directories to determine importance:

Indicator	Points
Has package.json/go.mod/Cargo.toml/etc	+10
Has src/, lib/, components/, or services/	+5
Has .cursorrules or copilot-instructions.md	+3
Has >10 source files (.ts,.js,.py,.go,.rs)	+3
Has README.md or docs/	+2

Only directories scoring > 5 are initialized (configurable via --min-score).

Output Example

🔍 Scanning monorepo structure...
📊 Found 8 directories above threshold (score > 5)

📁 Root
   ✓ AGENTS.md created (project coordination, 8 packages)
   ✓ CLAUDE.md updated (hierarchy linking)

📦 Batch 1/3: [packages/api, packages/web, packages/shared]
   ✓ packages/api: AGENTS.md (Express.js, TypeScript, Prisma)
   ✓ packages/web: AGENTS.md (Next.js 14, React, Tailwind)
   ✓ packages/shared: AGENTS.md (TypeScript utilities, types)

📦 Batch 2/3: [packages/cli, packages/docs, services/worker]
   ✓ packages/cli: AGENTS.md (TypeScript CLI, Yargs)
   ✓ packages/docs: AGENTS.md (MDX docs site, Nextra)
   ✓ services/worker: AGENTS.md (Bull queue, async jobs)

📦 Batch 3/3: [.claude, scripts]
   ✓ .claude: AGENTS.md (custom Claude Code hooks)
   ✓ scripts: AGENTS.md (utility scripts, Bash)

✅ Summary: 1 root + 8 packages initialized
   📚 All packages linked hierarchically to CLAUDE.md
   🔗 Cross-package dependencies documented
   💾 Git commit ready: "chore: initialize monorepo AGENTS.md hierarchy"

What Gets Created

For each important directory:

my-monorepo/
├── AGENTS.md                    ← Root coordination
├── CLAUDE.md                    ← Updated with hierarchy
├── packages/
│   ├── api/
│   │   ├── AGENTS.md            ← New (API Services level)
│   │   └── src/
│   ├── web/
│   │   ├── AGENTS.md            ← New (Frontend level)
│   │   └── src/
│   ├── shared/
│   │   ├── AGENTS.md            ← New (Shared Utilities level)
│   │   └── src/
│   └── cli/
│       ├── AGENTS.md            ← New (CLI Tools level)
│       └── src/

Each AGENTS.md includes:

• Hierarchy metadata (level, parent, philosophy)
• Tech stack summary
• Build/test/lint commands
• Code style guidelines
• Common patterns
• Integration points
• AI agent guidance

Quality Checklist

Before running this skill, verify:

• Root CLAUDE.md exists or will be created
• Project structure is stable (won't add/remove packages soon)
• Key dependencies between packages are known

After running, verify:

• Each AGENTS.md is 15-25 lines (focused, not overwhelming)
• All hierarchy metadata is correct
• Links are valid (no broken references)
• Build commands are accurate
• Cross-package dependencies are noted
• Git commit message is clear

Best Practices

1. Run once per new package - Update root AGENTS.md when adding packages
2. Keep AGENTS.md lean - ~20 lines per file, link to docs for details
3. Update when tech changes - Refresh AGENTS.md if framework/language updates
4. Link to packages - Reference package-specific docs, not inline docs
5. Verify the hierarchy - Test that agents can navigate from root → package

Common Patterns

Adding a new package:

# Add your new package directory
mkdir -p packages/my-service/src

# Re-run monorepo-initialization
/monorepo-initialization

# Verifies all links still work, updates root AGENTS.md

Migrating existing project:

# Run on project with existing AGENTS.md files
/monorepo-initialization --preserve=true

# Won't overwrite existing files, just adds missing ones

Large monorepos (20+ packages):

# Increase recursion depth, process in batches
/monorepo-initialization --depth=3 --batch-size=5 --min-score=7

# Higher score = fewer but more important directories initialized

Success Metrics

After running:

• ✓ Root AGENTS.md exists and lists all packages
• ✓ All important directories have AGENTS.md
• ✓ Each AGENTS.md has hierarchy metadata
• ✓ CLAUDE.md links to package AGENTS.md files
• ✓ AI agents can understand project structure
• ✓ New team members can navigate contexts easily
• ✓ Cross-package dependencies are clear

This transforms your monorepo from "confusing structure" to "clear, navigable context for AI agents and humans alike."

Anti-Rationalization Table

Excuse	Counter
"I'll add AGENTS.md files as needed"	Proactive initialization prevents confusion. Set up the hierarchy before agents need it.
"The scoring heuristic is too complex"	The heuristic prevents initializing unimportant directories. It saves more time than it costs.
"One AGENTS.md at the root is enough"	Root-level guidance does not scale to 20+ packages. Each package needs focused guidance.
"I don't need to document build commands"	Agents need to know how to run tests and builds. Document them or agents guess wrong.
"The hierarchy metadata is boilerplate"	Hierarchy metadata enables agents to navigate from root to package. It is structural, not decorative.