Agent-Skills.md

Agent Skills: Monorepo Navigator

>

engineeringID: borghei/claude-skills/monorepo-navigator

Repository

borghei/claude-skills
borgheiLicense: NOASSERTION
34669

Install this agent skill to your local

pnpm dlx add-skill https://github.com/borghei/Claude-Skills/tree/HEAD/engineering/monorepo-navigator

Skill Files

Browse the full folder contents for monorepo-navigator.

Download Skill

Loading file tree…

engineering/monorepo-navigator/SKILL.md

Skill Metadata

Name
monorepo-navigator
Description
>

Monorepo Navigator

Navigate, manage, and optimize monorepos at any scale. Covers Turborepo, Nx, pnpm workspaces, and Lerna/Changesets for cross-package impact analysis, selective builds on affected packages only, dependency graph visualization, remote caching configuration, migration from multi-repo to monorepo with preserved git history, and coordinated package publishing with automated changelogs.

Keywords: monorepo, Turborepo, Nx, pnpm workspaces, Changesets, dependency graph, remote cache, affected packages, selective builds, cross-package impact, npm publishing, workspace protocol

Core Capabilities

  • Impact analysis — determine which apps break when a shared package changes, trace dependency chains, visualize Mermaid graphs, and calculate blast radius.
  • Selective execution — run tests/builds only for affected packages, filter by changed files since a git ref, and skip unchanged packages in CI.
  • Build optimization — remote caching (Turborepo/Vercel, Nx Cloud), incremental builds with input/output config, dependency-aware parallel scheduling, and artifact sharing.
  • Publishing — Changesets for coordinated versioning, automated per-package changelogs, pre-release channels, and workspace:* replacement during publish.

When to Use

  • Multiple packages/apps share code (UI components, utils, types, API clients)
  • Build times are slow because everything rebuilds on every change
  • Migrating from multiple repos to a single monorepo
  • Publishing npm packages with coordinated versioning
  • Teams work across packages and need unified tooling

Clarify First

Before analyzing or configuring, confirm these inputs. If any is unknown or vague, ASK — do not assume:

  • [ ] Tooling — Turborepo, Nx, pnpm workspaces, or Changesets (drives the config and commands generated)
  • [ ] Task — impact/dependency analysis, build optimization, or publishing setup (selects dependency_graph.py vs impact_detector.py vs package_analyzer.py)
  • [ ] Repo root & git ref — the monorepo path and the baseline ref for "affected" detection (sets --ref and what counts as changed)

Stop rule: ask only the 2-3 that most change the output. If the user says "just draft it," proceed and list your assumptions at the top of the artifact.

Tools

| Tool | Purpose | Command | |------|---------|---------| | dependency_graph.py | Generate a Mermaid dependency graph of internal packages | python scripts/dependency_graph.py . --focus @repo/ui --direction dependents | | impact_detector.py | Detect which packages are affected by file changes | python scripts/impact_detector.py . --ref origin/main --affected-only | | package_analyzer.py | Analyze package structure, dependencies, and health | python scripts/package_analyzer.py . --only-shared |

References

Load the reference that matches the task — keep this file lean and pull detail on demand:

  • references/tooling-and-configuration.md — tool selection decision matrix, recommended repo structure, full turbo.json and pnpm-workspace config, key Turborepo/pnpm commands, impact-analysis commands, remote-caching setup, affected-only CI workflow, Changesets publishing, and multi-repo→monorepo migration steps. Read when configuring or operating a monorepo.
  • references/operations-and-best-practices.md — common pitfalls, best practices, troubleshooting table, and success criteria. Read when something misbehaves or when validating a setup.

Scope & Limitations

This skill covers:

  • Turborepo, Nx, and pnpm workspace configuration and optimization
  • Cross-package dependency analysis and impact visualization
  • Remote caching setup (Vercel, Nx Cloud, self-hosted)
  • Changesets-based coordinated versioning and npm publishing

This skill does NOT cover:

  • Application-level build configuration (webpack, Vite, esbuild internals) — see performance-profiler
  • CI/CD pipeline design beyond monorepo-specific filters — see ci-cd-pipeline-builder
  • Git branching strategies and release flow — see release-manager
  • Dependency vulnerability scanning and license auditing — see dependency-auditor

Integration Points

| Skill | Integration | Data Flow | |-------|------------|-----------| | ci-cd-pipeline-builder | Monorepo-aware CI workflows use --filter flags and remote caching tokens | Monorepo Navigator defines filter patterns and cache config that CI pipelines consume | | release-manager | Changesets versioning feeds into release orchestration and tag management | Release Manager triggers changeset version and changeset publish as part of release flow | | dependency-auditor | Workspace dependency graph informs vulnerability and license scanning scope | Monorepo Navigator exports the package dependency tree that Dependency Auditor analyzes | | performance-profiler | Build profiling data identifies slow packages for optimization | Performance Profiler measures per-package build times surfaced by Turborepo --summarize | | changelog-generator | Changesets produce per-package changelogs consumed by release notes | Changeset summaries flow into Changelog Generator for formatted release documentation | | tech-debt-tracker | Cross-package coupling and circular dependencies surface as tracked tech debt items | Monorepo Navigator's impact analysis identifies coupling hotspots that Tech Debt Tracker records |