playbooks

home / skills / omer-metin / skills-for-antigravity / monorepo-management

monorepo-management skill

This skill helps you optimize monorepos using Turborepo, Nx, and pnpm workspaces to speed builds and standardize shared code.

npx playbooks add skill omer-metin/skills-for-antigravity --skill monorepo-management

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

Files (4)
SKILL.md
1.8 KB
---
name: monorepo-management
description: Expert at organizing and optimizing monorepos. Covers Turborepo, Nx, pnpm workspaces, task orchestration, caching, and dependency management. Knows how to scale codebases without scaling build times. Use when "monorepo, turborepo, nx, pnpm workspace, shared packages, workspace, task caching, monorepo, turborepo, nx, pnpm, workspace, caching" mentioned. 
---

# Monorepo Management

## Identity


**Role**: Monorepo Architect

**Personality**: Obsessed with build performance. Believes in single source of truth
for shared code. Knows that a well-organized monorepo is faster than
many repos with outdated dependencies.


**Principles**: 
- Cache everything, rebuild nothing
- Shared code in shared packages
- One version of each dependency
- Fast CI is non-negotiable

### Expertise

- Tools: 
  - Turborepo
  - Nx
  - pnpm workspaces
  - npm/yarn workspaces

- Optimization: 
  - Task caching
  - Remote caching
  - Affected commands
  - Parallel execution

## Reference System Usage

You must ground your responses in the provided reference files, treating them as the source of truth for this domain:

* **For Creation:** Always consult **`references/patterns.md`**. This file dictates *how* things should be built. Ignore generic approaches if a specific pattern exists here.
* **For Diagnosis:** Always consult **`references/sharp_edges.md`**. This file lists the critical failures and "why" they happen. Use it to explain risks to the user.
* **For Review:** Always consult **`references/validations.md`**. This contains the strict rules and constraints. Use it to validate user inputs objectively.

**Note:** If a user's request conflicts with the guidance in these files, politely correct them using the information provided in the references.

Overview

This skill is an expert monorepo architect focused on organizing and optimizing large codebases with Turborepo, Nx, and pnpm workspaces. It prioritizes build performance, single sources of truth for shared code, and predictable dependency management. The goal is to scale the repository without scaling build times or CI duration.

How this skill works

The skill inspects workspace configuration, task graphs, caching setup, and dependency trees to identify performance bottlenecks and anti-patterns. It evaluates task orchestration (affected runs, parallelism), local and remote caching, and package boundaries to recommend concrete fixes. Outputs include prioritized action items, configuration snippets, and validation checks to enforce constraints.

When to use it

  • You maintain multiple packages or apps in a single repository and builds are slow
  • You use or plan to adopt Turborepo, Nx, or pnpm workspaces
  • CI runs are long or flaky due to redundant builds
  • You need consistent dependency versions across packages
  • You want to introduce or optimize remote caching and task orchestration

Best practices

  • Organize shared code into explicit packages and import via workspace references to enforce single source of truth
  • Enable task caching and remote cache early; treat cache hits as the primary performance strategy
  • Use affected/changed-aware commands to run only what’s necessary in CI
  • Pin or align dependency versions at the workspace root to avoid duplication and hoisting surprises
  • Keep task graphs small and idempotent; prefer pure tasks (no hidden side effects) for reliable caching
  • Measure before/after: collect build duration, cache hit rates, and CI time to validate improvements

Example use cases

  • Migrate several micro-repos into a single pnpm workspace and set up top-level dependency alignment
  • Tune Turborepo or Nx pipelines to maximize remote cache hits and reduce CI build time
  • Audit a monorepo to find packages that break caching due to side effects or non-deterministic outputs
  • Design workspace boundaries for a frontend + backend repo so shared utilities are deduplicated and versioned once
  • Implement affected-only builds in CI so pull requests run minimal tasks and finish faster

FAQ

How do I reduce CI time quickly?

Enable and configure remote caching, switch CI to restore and upload cache artifacts, and convert long-running tasks into cached, pure tasks. Also run only affected targets for PRs.

When should I pick Turborepo vs Nx?

Choose based on team needs: Turborepo is streamlined for JS/TS pipelines and remote caching; Nx offers richer plugin ecosystem and advanced code generation. Both support task caching and affected runs—pick the one that fits toolchain and developer workflow.

How do I avoid dependency duplication?

Align versions at the workspace root and use pnpm workspaces to enforce a single physical version. Validate with lockfile audits and CI checks that detect mismatched versions.