monorepo-navigator

# Monorepo Navigator

**Tier:** POWERFUL  
**Category:** Engineering  
**Domain:** Monorepo Architecture / Build Systems  

---

## Overview

Navigate, manage, and optimize monorepos. Covers Turborepo, Nx, pnpm workspaces, and Lerna. Enables cross-package impact analysis, selective builds/tests on affected packages only, remote caching, dependency graph visualization, and structured migrations from multi-repo to monorepo. Includes Claude Code configuration for workspace-aware development.

---

## Core Capabilities

- **Cross-package impact analysis** — determine which apps break when a shared package changes
- **Selective commands** — run tests/builds only for affected packages (not everything)
- **Dependency graph** — visualize package relationships as Mermaid diagrams
- **Build optimization** — remote caching, incremental builds, parallel execution
- **Migration** — step-by-step multi-repo → monorepo with zero history loss
- **Publishing** — changesets for versioning, pre-release channels, npm publish workflows
- **Claude Code config** — workspace-aware CLAUDE.md with per-package instructions

---

## When to Use

Use when:
- Multiple packages/apps share code (UI components, utils, types, API clients)
- Build times are slow because everything rebuilds when anything changes
- Migrating from multiple repos to a single repo
- Need to publish packages to npm with coordinated versioning
- Teams work across multiple packages and need unified tooling

Skip when:
- Single-app project with no shared packages
- Team/project boundaries are completely isolated (polyrepo is fine)
- Shared code is minimal and copy-paste overhead is acceptable

---

## Tool Selection

| Tool | Best For | Key Feature |
|---|---|---|
| **Turborepo** | JS/TS monorepos, simple pipeline config | Best-in-class remote caching, minimal config |
| **Nx** | Large enterprises, plugin ecosystem | Project graph, code generation, affected commands |
| **pnpm workspaces** | Workspace protocol, disk efficiency | `workspace:*` for local package refs |
| **Lerna** | npm publishing, versioning | Batch publishing, conventional commits |
| **Changesets** | Modern versioning (preferred over Lerna) | Changelog generation, pre-release channels |

Most modern setups: **pnpm workspaces + Turborepo + Changesets**

---

## Turborepo
→ See references/monorepo-tooling-reference.md for details

## Workspace Analyzer

```bash
python3 scripts/monorepo_analyzer.py /path/to/monorepo
python3 scripts/monorepo_analyzer.py /path/to/monorepo --json
```

Also see `references/monorepo-patterns.md` for common architecture and CI patterns.

## Common Pitfalls

| Pitfall | Fix |
|---|---|
| Running `turbo run build` without `--filter` on every PR | Always use `--filter=...[origin/main]` in CI |
| `workspace:*` refs cause publish failures | Use `pnpm changeset publish` — it replaces `workspace:*` with real versions automatically |
| All packages rebuild when unrelated file changes | Tune `inputs` in turbo.json to exclude docs, config files from cache keys |
| Shared tsconfig causes one package to break all type-checks | Use `extends` properly — each package extends root but overrides `rootDir` / `outDir` |
| git history lost during migration | Use `git filter-repo --to-subdirectory-filter` before merging — never move files manually |
| Remote cache not working in CI | Check TURBO_TOKEN and TURBO_TEAM env vars; verify with `turbo run build --summarize` |
| CLAUDE.md too generic — Claude modifies wrong package | Add explicit "When working on X, only touch files in apps/X" rules per package CLAUDE.md |

---

## Best Practices

1. **Root CLAUDE.md defines the map** — document every package, its purpose, and dependency rules
2. **Per-package CLAUDE.md defines the rules** — what's allowed, what's forbidden, testing commands
3. **Always scope commands with --filter** — running everything on every change defeats the purpose
4. **Remote cache is not optional** — without it, monorepo CI is slower than multi-repo CI
5. **Changesets over manual versioning** — never hand-edit package.json versions in a monorepo
6. **Shared configs in root, extended in packages** — tsconfig.base.json, .eslintrc.base.js, jest.base.config.js
7. **Impact analysis before merging shared package changes** — run affected check, communicate blast radius
8. **Keep packages/types as pure TypeScript** — no runtime code, no dependencies, fast to build and type-check

{
  "format": "aiskill/v1",
  "skill": {
    "name": "monorepo-navigator",
    "slug": "monorepo-navigator",
    "version": "1.0.0",
    "description": "Navigate, manage, and optimize monorepos. Covers Turborepo, Nx, pnpm workspaces, and Lerna. Cross-package impact analysis, selective builds/tests on affected packages, remote caching, dependency graph visualization, and structured multi-repo to monorepo migrations. Use when setting up a new monorepo, optimizing CI for a large workspace, debugging cross-package dependency issues, or planning a multi-repo consolidation.",
    "category": "Development",
    "tags": [
      "dev-workflow",
      "data-viz"
    ],
    "platforms": [
      "chatgpt",
      "claude-code",
      "cursor"
    ],
    "tested_environment": "Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and compatible agents",
    "license": "MIT"
  },
  "prompts": {
    "system": "# Monorepo Navigator\r\n\r\n**Tier:** POWERFUL  \r\n**Category:** Engineering  \r\n**Domain:** Monorepo Architecture / Build Systems  \r\n\r\n---\r\n\r\n## Overview\r\n\r\nNavigate, manage, and optimize monorepos. Covers Turborepo, Nx, pnpm workspaces, and Lerna. Enables cross-package impact analysis, selective builds/tests on affected packages only, remote caching, dependency graph visualization, and structured migrations from multi-repo to monorepo. Includes Claude Code configuration for workspace-aware development.\r\n\r\n---\r\n\r\n## Core Capabilities\r\n\r\n- **Cross-package impact analysis** — determine which apps break when a shared package changes\r\n- **Selective commands** — run tests/builds only for affected packages (not everything)\r\n- **Dependency graph** — visualize package relationships as Mermaid diagrams\r\n- **Build optimization** — remote caching, incremental builds, parallel execution\r\n- **Migration** — step-by-step multi-repo → monorepo with zero history loss\r\n- **Publishing** — changesets for versioning, pre-release channels, npm publish workflows\r\n- **Claude Code config** — workspace-aware CLAUDE.md with per-package instructions\r\n\r\n---\r\n\r\n## When to Use\r\n\r\nUse when:\r\n- Multiple packages/apps share code (UI components, utils, types, API clients)\r\n- Build times are slow because everything rebuilds when anything changes\r\n- Migrating from multiple repos to a single repo\r\n- Need to publish packages to npm with coordinated versioning\r\n- Teams work across multiple packages and need unified tooling\r\n\r\nSkip when:\r\n- Single-app project with no shared packages\r\n- Team/project boundaries are completely isolated (polyrepo is fine)\r\n- Shared code is minimal and copy-paste overhead is acceptable\r\n\r\n---\r\n\r\n## Tool Selection\r\n\r\n| Tool | Best For | Key Feature |\r\n|---|---|---|\r\n| **Turborepo** | JS/TS monorepos, simple pipeline config | Best-in-class remote caching, minimal config |\r\n| **Nx** | Large enterprises, plugin ecosystem | Project graph, code generation, affected commands |\r\n| **pnpm workspaces** | Workspace protocol, disk efficiency | `workspace:*` for local package refs |\r\n| **Lerna** | npm publishing, versioning | Batch publishing, conventional commits |\r\n| **Changesets** | Modern versioning (preferred over Lerna) | Changelog generation, pre-release channels |\r\n\r\nMost modern setups: **pnpm workspaces + Turborepo + Changesets**\r\n\r\n---\r\n\r\n## Turborepo\r\n→ See references/monorepo-tooling-reference.md for details\r\n\r\n## Workspace Analyzer\r\n\r\n```bash\r\npython3 scripts/monorepo_analyzer.py /path/to/monorepo\r\npython3 scripts/monorepo_analyzer.py /path/to/monorepo --json\r\n```\r\n\r\nAlso see `references/monorepo-patterns.md` for common architecture and CI patterns.\r\n\r\n## Common Pitfalls\r\n\r\n| Pitfall | Fix |\r\n|---|---|\r\n| Running `turbo run build` without `--filter` on every PR | Always use `--filter=...[origin/main]` in CI |\r\n| `workspace:*` refs cause publish failures | Use `pnpm changeset publish` — it replaces `workspace:*` with real versions automatically |\r\n| All packages rebuild when unrelated file changes | Tune `inputs` in turbo.json to exclude docs, config files from cache keys |\r\n| Shared tsconfig causes one package to break all type-checks | Use `extends` properly — each package extends root but overrides `rootDir` / `outDir` |\r\n| git history lost during migration | Use `git filter-repo --to-subdirectory-filter` before merging — never move files manually |\r\n| Remote cache not working in CI | Check TURBO_TOKEN and TURBO_TEAM env vars; verify with `turbo run build --summarize` |\r\n| CLAUDE.md too generic — Claude modifies wrong package | Add explicit \"When working on X, only touch files in apps/X\" rules per package CLAUDE.md |\r\n\r\n---\r\n\r\n## Best Practices\r\n\r\n1. **Root CLAUDE.md defines the map** — document every package, its purpose, and dependency rules\r\n2. **Per-package CLAUDE.md defines the rules** — what's allowed, what's forbidden, testing commands\r\n3. **Always scope commands with --filter** — running everything on every change defeats the purpose\r\n4. **Remote cache is not optional** — without it, monorepo CI is slower than multi-repo CI\r\n5. **Changesets over manual versioning** — never hand-edit package.json versions in a monorepo\r\n6. **Shared configs in root, extended in packages** — tsconfig.base.json, .eslintrc.base.js, jest.base.config.js\r\n7. **Impact analysis before merging shared package changes** — run affected check, communicate blast radius\r\n8. **Keep packages/types as pure TypeScript** — no runtime code, no dependencies, fast to build and type-check",
    "user_template": ""
  },
  "variables": [],
  "install": {
    "steps": [
      {
        "title": "Download & unzip",
        "detail": "Download the .zip package from SkillVault and unzip it. The monorepo-navigator/ folder contains SKILL.md plus any companion scripts, references and assets."
      },
      {
        "title": "Copy into your agent skills directory",
        "detail": "Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code), .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or reload the session."
      },
      {
        "title": "Use it",
        "detail": "Describe the task in natural language; the agent loads the skill automatically when the request matches the skill description."
      }
    ]
  },
  "usage": {
    "steps": []
  },
  "metadata": {
    "author": "SkillVault",
    "source": "https://skillvault.top/skills/monorepo-navigator",
    "exported_at": "2026-11-03T07:45:03.140Z"
  }
}

format: aiskill/v1
skill:
  name: monorepo-navigator
  slug: monorepo-navigator
  version: 1.0.0
  description: >-
    Navigate, manage, and optimize monorepos. Covers Turborepo, Nx, pnpm workspaces, and Lerna.
    Cross-package impact analysis, selective builds/tests on affected packages, remote caching,
    dependency graph visualization, and structured multi-repo to monorepo migrations. Use when
    setting up a new monorepo, optimizing CI for a large workspace, debugging cross-package
    dependency issues, or planning a multi-repo consolidation.
  category: Development
  tags:
    - dev-workflow
    - data-viz
  platforms:
    - chatgpt
    - claude-code
    - cursor
  tested_environment: >-
    Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and
    compatible agents
  license: MIT
prompts:
  system: "# Monorepo Navigator\r\n\r\n**Tier:** POWERFUL  \r\n**Category:** Engineering  \r\n**Domain:** Monorepo Architecture / Build Systems  \r\n\r\n---\r\n\r\n## Overview\r\n\r\nNavigate, manage, and optimize monorepos. Covers Turborepo, Nx, pnpm workspaces, and Lerna. Enables cross-package impact analysis, selective builds/tests on affected packages only, remote caching, dependency graph visualization, and structured migrations from multi-repo to monorepo. Includes Claude Code configuration for workspace-aware development.\r\n\r\n---\r\n\r\n## Core Capabilities\r\n\r\n- **Cross-package impact analysis** — determine which apps break when a shared package changes\r\n- **Selective commands** — run tests/builds only for affected packages (not everything)\r\n- **Dependency graph** — visualize package relationships as Mermaid diagrams\r\n- **Build optimization** — remote caching, incremental builds, parallel execution\r\n- **Migration** — step-by-step multi-repo → monorepo with zero history loss\r\n- **Publishing** — changesets for versioning, pre-release channels, npm publish workflows\r\n- **Claude Code config** — workspace-aware CLAUDE.md with per-package instructions\r\n\r\n---\r\n\r\n## When to Use\r\n\r\nUse when:\r\n- Multiple packages/apps share code (UI components, utils, types, API clients)\r\n- Build times are slow because everything rebuilds when anything changes\r\n- Migrating from multiple repos to a single repo\r\n- Need to publish packages to npm with coordinated versioning\r\n- Teams work across multiple packages and need unified tooling\r\n\r\nSkip when:\r\n- Single-app project with no shared packages\r\n- Team/project boundaries are completely isolated (polyrepo is fine)\r\n- Shared code is minimal and copy-paste overhead is acceptable\r\n\r\n---\r\n\r\n## Tool Selection\r\n\r\n| Tool | Best For | Key Feature |\r\n|---|---|---|\r\n| **Turborepo** | JS/TS monorepos, simple pipeline config | Best-in-class remote caching, minimal config |\r\n| **Nx** | Large enterprises, plugin ecosystem | Project graph, code generation, affected commands |\r\n| **pnpm workspaces** | Workspace protocol, disk efficiency | `workspace:*` for local package refs |\r\n| **Lerna** | npm publishing, versioning | Batch publishing, conventional commits |\r\n| **Changesets** | Modern versioning (preferred over Lerna) | Changelog generation, pre-release channels |\r\n\r\nMost modern setups: **pnpm workspaces + Turborepo + Changesets**\r\n\r\n---\r\n\r\n## Turborepo\r\n→ See references/monorepo-tooling-reference.md for details\r\n\r\n## Workspace Analyzer\r\n\r\n```bash\r\npython3 scripts/monorepo_analyzer.py /path/to/monorepo\r\npython3 scripts/monorepo_analyzer.py /path/to/monorepo --json\r\n```\r\n\r\nAlso see `references/monorepo-patterns.md` for common architecture and CI patterns.\r\n\r\n## Common Pitfalls\r\n\r\n| Pitfall | Fix |\r\n|---|---|\r\n| Running `turbo run build` without `--filter` on every PR | Always use `--filter=...[origin/main]` in CI |\r\n| `workspace:*` refs cause publish failures | Use `pnpm changeset publish` — it replaces `workspace:*` with real versions automatically |\r\n| All packages rebuild when unrelated file changes | Tune `inputs` in turbo.json to exclude docs, config files from cache keys |\r\n| Shared tsconfig causes one package to break all type-checks | Use `extends` properly — each package extends root but overrides `rootDir` / `outDir` |\r\n| git history lost during migration | Use `git filter-repo --to-subdirectory-filter` before merging — never move files manually |\r\n| Remote cache not working in CI | Check TURBO_TOKEN and TURBO_TEAM env vars; verify with `turbo run build --summarize` |\r\n| CLAUDE.md too generic — Claude modifies wrong package | Add explicit \"When working on X, only touch files in apps/X\" rules per package CLAUDE.md |\r\n\r\n---\r\n\r\n## Best Practices\r\n\r\n1. **Root CLAUDE.md defines the map** — document every package, its purpose, and dependency rules\r\n2. **Per-package CLAUDE.md defines the rules** — what's allowed, what's forbidden, testing commands\r\n3. **Always scope commands with --filter** — running everything on every change defeats the purpose\r\n4. **Remote cache is not optional** — without it, monorepo CI is slower than multi-repo CI\r\n5. **Changesets over manual versioning** — never hand-edit package.json versions in a monorepo\r\n6. **Shared configs in root, extended in packages** — tsconfig.base.json, .eslintrc.base.js, jest.base.config.js\r\n7. **Impact analysis before merging shared package changes** — run affected check, communicate blast radius\r\n8. **Keep packages/types as pure TypeScript** — no runtime code, no dependencies, fast to build and type-check"
  user_template: ""
variables: []
install:
  steps:
    - title: Download & unzip
      detail: >-
        Download the .zip package from SkillVault and unzip it. The monorepo-navigator/ folder
        contains SKILL.md plus any companion scripts, references and assets.
    - title: Copy into your agent skills directory
      detail: >-
        Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code),
        .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or
        reload the session.
    - title: Use it
      detail: >-
        Describe the task in natural language; the agent loads the skill automatically when the
        request matches the skill description.
usage:
  steps: []
metadata:
  author: SkillVault
  source: https://skillvault.top/skills/monorepo-navigator
  exported_at: "2026-11-03T07:45:03.140Z"