playbooks

home / skills / yonatangross / orchestkit / monorepo-context

monorepo-context skill

/plugins/ork/skills/monorepo-context

This skill enables monorepo aware Claude Code sessions with per-service CLAUDE.md, multi-directory context, and root versus service separation.

npx playbooks add skill yonatangross/orchestkit --skill monorepo-context

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
2.2 KB
---
name: monorepo-context
description: Multi-directory context patterns for monorepos using CC 2.1.20 --add-dir. Covers per-service CLAUDE.md, workspace detection, and root vs service context separation.
context: fork
version: 1.0.0
author: OrchestKit
tags: [monorepo, multi-directory, context, workspace, add-dir]
user-invocable: false
---

# Monorepo Context Patterns

## Overview

Claude Code 2.1.20 introduces `--add-dir` for multi-directory context, enabling monorepo-aware sessions where each service maintains its own CLAUDE.md instructions.

## Monorepo Detection

Indicators that a project is a monorepo:

| Indicator | Tool |
|-----------|------|
| `pnpm-workspace.yaml` | pnpm |
| `lerna.json` | Lerna |
| `nx.json` | Nx |
| `turbo.json` | Turborepo |
| `rush.json` | Rush |
| 3+ nested `package.json` files | Generic |

## Per-Service CLAUDE.md

Each service can have its own context instructions:

```
monorepo/
  CLAUDE.md               # Root context (workspace-wide rules)
  packages/
    api/
      CLAUDE.md           # API-specific patterns
      package.json
    web/
      CLAUDE.md           # Frontend-specific patterns
      package.json
    shared/
      CLAUDE.md           # Shared library context
      package.json
```

## --add-dir Usage

Start Claude Code with additional directory context:

```bash
# From api service, add shared library context
claude --add-dir ../shared

# Multiple directories
claude --add-dir ../shared --add-dir ../web
```

## Environment Variable

Enable automatic CLAUDE.md loading from additional directories:

```bash
export CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1
```

When set, Claude Code reads CLAUDE.md from all `--add-dir` directories.

## Root vs Service Context Separation

### Root CLAUDE.md

- Workspace-wide conventions (commit messages, branch naming)
- Cross-service dependency rules
- CI/CD pipeline overview
- Shared tooling configuration

### Service CLAUDE.md

- Service-specific patterns and frameworks
- Local test commands
- API contracts and schemas
- Service-specific environment variables

## Related Skills

- `configure` - OrchestKit configuration including monorepo detection
- `project-structure-enforcer` - Folder structure enforcement

Overview

This skill provides practical patterns for managing multi-directory context in monorepos using Claude Code 2.1.20 with the --add-dir option. It explains workspace detection, per-service CLAUDE.md usage, and how to separate root-level and service-level context. The guidance is focused on predictable context loading and clear division of responsibilities across services and the workspace.

How this skill works

The skill inspects common monorepo indicators (pnpm-workspace.yaml, lerna.json, nx.json, turbo.json, rush.json, or multiple nested package.json files) to identify workspace layout. It documents how to start Claude Code with --add-dir to include additional directories and how to enable automatic CLAUDE.md loading via an environment variable. It also defines conventions for what belongs in a root CLAUDE.md versus service CLAUDE.md files.

When to use it

  • You maintain a monorepo with multiple services or packages.
  • You want Claude Code sessions to include context from shared libs or adjacent services.
  • You need consistent, workspace-wide rules alongside service-level instructions.
  • You want automated loading of CLAUDE.md files from added directories.
  • You are orchestrating cross-service CI/CD or dependency rules while keeping per-service development details localized.

Best practices

  • Keep workspace-wide policies in the root CLAUDE.md: commit conventions, branch rules, CI/CD overview, and shared tooling configs.
  • Place service-specific patterns in each service CLAUDE.md: frameworks, test commands, API contracts, and environment variables.
  • Use --add-dir from the service working directory to bring shared or sibling contexts into scope for a session.
  • Set CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 in CI or developer shells to auto-load CLAUDE.md files from added dirs.
  • Limit overlapping rules: prefer root for cross-cutting concerns and service files for implementation details to avoid conflicts.

Example use cases

  • Start a session in packages/api and add the shared library: claude --add-dir ../shared to include library patterns and types.
  • Run local debugging that needs both frontend and API contexts: claude --add-dir ../web --add-dir ../shared to surface frontend contracts and shared helpers.
  • Enforce workspace policies during reviews by relying on root CLAUDE.md for commit and branch rules while using service CLAUDE.md for API schema details.
  • Enable automatic CLAUDE.md loading in CI by exporting CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 so tests inherit service and shared guidance.

FAQ

How does Claude Code detect a monorepo?

It looks for common workspace files (pnpm-workspace.yaml, lerna.json, nx.json, turbo.json, rush.json) or multiple nested package.json files as heuristics.

What should go in the root CLAUDE.md vs a service CLAUDE.md?

Root CLAUDE.md should contain workspace-wide conventions and cross-service rules; service CLAUDE.md should contain framework specifics, local test commands, API contracts, and service environment details.