monorepo-management
Manage monorepos and multi-package repositories with workspace tools, dependency management, selective builds, and change detection. Covers npm/pnpm workspaces, Turborepo, and Python monorepo patterns. Triggers on monorepo setup, workspace management, or multi-package repository requests.
Best use case
monorepo-management is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Manage monorepos and multi-package repositories with workspace tools, dependency management, selective builds, and change detection. Covers npm/pnpm workspaces, Turborepo, and Python monorepo patterns. Triggers on monorepo setup, workspace management, or multi-package repository requests.
Teams using monorepo-management should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/monorepo-management/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How monorepo-management Compares
| Feature / Agent | monorepo-management | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Manage monorepos and multi-package repositories with workspace tools, dependency management, selective builds, and change detection. Covers npm/pnpm workspaces, Turborepo, and Python monorepo patterns. Triggers on monorepo setup, workspace management, or multi-package repository requests.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Monorepo Management
Organize and build multi-package repositories efficiently.
## When to Monorepo
| Situation | Monorepo | Polyrepo |
|-----------|----------|----------|
| Shared libraries across packages | Yes | No |
| Tight coupling between packages | Yes | No |
| Independent release cycles needed | No | Yes |
| Different teams, different cadences | No | Yes |
| Atomic cross-package changes | Yes | No |
| < 20 packages | Yes | Either |
| > 100 packages | Depends | Often better |
## JavaScript/TypeScript Workspaces
### pnpm Workspaces
```yaml
# pnpm-workspace.yaml
packages:
- "packages/*"
- "apps/*"
- "tools/*"
```
```json
// package.json (root)
{
"private": true,
"scripts": {
"build": "turbo build",
"test": "turbo test",
"lint": "turbo lint"
}
}
```
### Package Structure
```
monorepo/
├── pnpm-workspace.yaml
├── turbo.json
├── package.json
├── packages/
│ ├── ui/ # Shared UI components
│ │ ├── package.json
│ │ └── src/
│ ├── config/ # Shared config (ESLint, TS)
│ │ └── package.json
│ └── utils/ # Shared utilities
│ └── package.json
├── apps/
│ ├── web/ # Next.js app
│ │ └── package.json
│ └── api/ # Express API
│ └── package.json
└── tools/
└── scripts/ # Build/deploy scripts
```
### Internal Package References
```json
// apps/web/package.json
{
"dependencies": {
"@myorg/ui": "workspace:*",
"@myorg/utils": "workspace:*"
}
}
```
## Turborepo Configuration
```json
// turbo.json
{
"$schema": "https://turbo.build/schema.json",
"tasks": {
"build": {
"dependsOn": ["^build"],
"outputs": ["dist/**", ".next/**"]
},
"test": {
"dependsOn": ["build"],
"outputs": []
},
"lint": {
"outputs": []
},
"dev": {
"persistent": true,
"cache": false
}
}
}
```
### Filtered Builds
```bash
# Build only packages affected by changes
turbo build --filter=...[HEAD~1]
# Build a specific package and its dependencies
turbo build --filter=@myorg/web
# Build everything that depends on a package
turbo build --filter=...@myorg/ui
```
## Python Monorepo Patterns
### Using a Shared Virtualenv
```
monorepo/
├── pyproject.toml # Root with all optional deps
├── packages/
│ ├── core/
│ │ ├── pyproject.toml
│ │ └── src/core/
│ ├── api/
│ │ ├── pyproject.toml
│ │ └── src/api/
│ └── worker/
│ ├── pyproject.toml
│ └── src/worker/
└── tests/
```
```toml
# Root pyproject.toml
[project]
name = "monorepo"
dependencies = []
[project.optional-dependencies]
core = ["./packages/core"]
api = ["./packages/api"]
worker = ["./packages/worker"]
dev = ["pytest", "ruff", "mypy"]
all = ["monorepo[core,api,worker,dev]"]
```
```bash
pip install -e ".[all]"
```
### Namespace Packages
```
packages/core/src/myorg/core/__init__.py
packages/api/src/myorg/api/__init__.py
# Both install into the `myorg` namespace
```
## Dependency Management
### Version Consistency
```json
// .syncpackrc (syncpack)
{
"versionGroups": [
{
"dependencies": ["react", "react-dom"],
"packages": ["**"],
"pinVersion": "^18.3.0"
}
]
}
```
```bash
# Check version consistency
syncpack list-mismatches
# Fix mismatches
syncpack fix-mismatches
```
### Dependency Graph
```bash
# Visualize internal dependencies
turbo ls --graph
# nx
nx graph
```
## CI/CD for Monorepos
### Change Detection
```bash
#!/usr/bin/env bash
set -euo pipefail
# Detect which packages changed
CHANGED=$(git diff --name-only HEAD~1 | grep '^packages/' | cut -d/ -f2 | sort -u)
for pkg in $CHANGED; do
echo "Building packages/$pkg"
cd "packages/$pkg" && npm run build && cd ../..
done
```
### GitHub Actions Matrix
```yaml
jobs:
detect-changes:
runs-on: ubuntu-latest
outputs:
packages: ${{ steps.changes.outputs.packages }}
steps:
- uses: actions/checkout@v4
with: { fetch-depth: 2 }
- id: changes
run: |
PKGS=$(git diff --name-only HEAD~1 | grep '^packages/' | cut -d/ -f2 | sort -u | jq -R -s -c 'split("\n") | map(select(. != ""))')
echo "packages=$PKGS" >> $GITHUB_OUTPUT
build:
needs: detect-changes
if: needs.detect-changes.outputs.packages != '[]'
strategy:
matrix:
package: ${{ fromJson(needs.detect-changes.outputs.packages) }}
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: cd packages/${{ matrix.package }} && npm ci && npm run build
```
## Anti-Patterns
- **No task runner** — Manual build ordering doesn't scale; use Turborepo or Nx
- **Circular dependencies** — Packages must form a DAG; validate in CI
- **Everything in one package.json** — Separate packages even in a monorepo
- **No change detection in CI** — Building everything on every commit wastes time
- **Version drift** — Enforce consistent dependency versions with syncpack or similar
- **Implicit dependencies** — Always declare package-level dependencies explicitlyRelated Skills
monorepo-devops-pack
Curated bundle for managing monorepos with containerized deployment pipelines. Includes monorepo management, Docker containerization, CI/CD deployment, and coding standards. Use when setting up or improving multi-package repository infrastructure.
configuration-management
Manage application configuration across environments with layered config loading, environment variables, secrets management, and validation. Covers 12-factor app patterns and config file formats. Triggers on configuration management, environment variables, or settings architecture requests.
taxonomy-modeling-design
Phase 2 of the pentaphase structural-overhaul protocol. Classifies entities, standardizes attributes, establishes relationships, and designs the access framework. Use when the user invokes phase 2 of an overhaul, asks to "design the taxonomy" or "model the structure", or has completed a landscape audit and is ready to redesign. Consumes phase-1-landscape-report.md; produces phase-2-taxonomy-model.md.
systemic-ingestion-normalization
Phase 4 of the pentaphase structural-overhaul protocol. Purges redundancies, enriches and aligns legacy entities to the new schema, executes phased ingestion into the new environment, and audits integrity. Use when the user invokes phase 4 of an overhaul, asks to "migrate the data" or "ingest into the new system", or has a configured environment ready to accept legacy entities. Consumes phase-3-environment-spec.md; produces phase-4-ingestion-report.md.
system-environment-configuration
Phase 3 of the pentaphase structural-overhaul protocol. Translates the taxonomy model into objective technical criteria, evaluates candidate mechanisms or frameworks, instantiates the chosen architecture, and programs validation rules. Use when the user invokes phase 3 of an overhaul, asks to "select a system" or "configure the environment", or has a taxonomy model and is ready to choose technology. Consumes phase-2-taxonomy-model.md; produces phase-3-environment-spec.md.
pentaphase-orchestrator
Threads the full five-phase structural-overhaul protocol — landscape discovery, taxonomy design, environment configuration, systemic ingestion, governance evolution — for any substrate the user names. Use when the user requests a structural overhaul, system redesign, or end-to-end restructuring of a documentation system, asset registry, code monorepo, knowledge base, or operational workflow; or when they explicitly invoke the pentaphase methodology. Coordinates handoffs between phase-skills and seats validation gates between phases.
landscape-discovery-audit
Phase 1 of the pentaphase structural-overhaul protocol. Inventories assets, maps current flow, identifies friction, and defines value metrics for any substrate. Use when the user invokes phase 1 of an overhaul, requests a baseline audit, asks to "discover the landscape" of a system, or wants to understand current state before redesigning. Produces phase-1-landscape-report.md.
governance-evolution-protocol
Phase 5 of the pentaphase structural-overhaul protocol. Codifies operational protocols, onboards the ecosystem of participants, programs behavior monitoring, and establishes an iteration cadence so the substrate evolves rather than calcifies. Use when the user invokes phase 5 of an overhaul, asks to "establish governance" or "lock in the protocols", or has completed ingestion and is ready to declare the substrate operational. Consumes phase-4-ingestion-report.md; produces phase-5-governance-charter.md, which closes the protocol.
dimension-surfacing
Surfaces the parallel domain dimensions implicit in a dense or minimal prompt. Use when a user prompt is small on the surface but plainly implies multiple independent domains needing different expertise; when explicitly invoked by the coliseum-orchestrator skill as Phase 1; or when the user asks "what dimensions does this prompt encode" or "what axes does this break into." Produces a named dimension set where each dimension is independently executable and not a paraphrase of another.
coliseum-dispatch
Dispatches a composed set of assignment envelopes to domain-expert subagents in parallel, in a single message with multiple Agent tool calls. Enforces the no-pingpong gate via the pingpong-detector agent before any dispatch fires. Use when invoked by the coliseum-orchestrator as Phase 3; when envelopes are already composed and the next step is parallel execution; or when the user asks to "fan out" or "dispatch in parallel." Produces a dispatch log capturing what was sent, when, and where returns land.
assignment-composition
Wraps each surfaced dimension as a self-contained 9-section autonomous-work-assignment envelope — scope, context, success criteria, allowed tools, return format, handoff — all the recipient subagent needs to execute without coming back. Use when invoked by coliseum-orchestrator as Phase 2; when dimensions are named and the next step is to make each independently dispatchable; or when the user asks "compose this as an assignment." The no-pingpong gate validates each envelope before dispatch.
workspace-autopsy-governance
Conducts a full automated autopsy of the current workspace directory to map files, identifies structural issues, proposes a restructuring plan (the signal), and establishes unified governance using templates. Use this skill when a user asks to map, restructure, reorganize, or apply new governance to an existing messy repository.