Search the docs, videos, blog, apps, teams, skills and release notes.
At a glance
What it is
Open source monorepo management expertise covering multi-package repository architecture, Changesets for versioning and changelogs, independent vs synchronized versioning, CI/CD optimization (caching, affected detection), workspace tooling (Turborepo, Nx, pnpm workspaces), and contributor experience in large repositories.
A skill is a written procedure a bot loads when a job calls for it. This one is a single file, SKILL.md, and the whole file is on this page.
The whole file, exactly as it downloads. Read it before you rely on it.
SKILL.md
576 lines · 1,904 words
You are an expert open source monorepo manager who helps teams structure multi-package repositories, manage independent versioning and releases, optimize CI/CD pipelines, and maintain excellent contributor experience as repositories grow in size and complexity.
Use this skill when:
User asks about monorepo oss manager techniques or best practices
Open source monorepo management expertise covering multi-package repository architecture, Changesets for versioning and changelogs, independent vs synchronized versioning, CI/CD optimization (caching, affected detection), workspace tooling (Turborepo, Nx, pnpm workspaces), and contributor experience in large repositories.
Nothing. It ships with Murage, which is open source. Your bots run on the AI plan you already have.
Yes. Open it in Settings → Skills to read, edit or duplicate it. Skill Guard scans it again after every edit.
Download the app, connect the AI you already pay for, and tell your Chief of Staff what needs doing. Plan on about ten minutes from install to a working team.
No account needed · Runs on the AI plan you already pay for
Paste it into your agent's instructions (CLAUDE.md, AGENTS.md or a custom GPT), or add it to a bot in Murage.
Ask Ember for the bot, then switch the skill on in its settings.
Step 1
Send your Chief of Staff this message. It proposes the bot and its role first, and creates it when you say go.
Send this to Ember
“Create a bot that uses the Monorepo OSS Manager skill, and show me the plan first.”
You're done when your Chief proposes the bot and its role, and the bot appears in your sidebar once you say go.
Step 2
You're done when you see the bot’s skills and the library.
Step 3
You're done when the skill shows as on for that bot.
Step 4
You're done when the bot takes the job and opens the skill when it needs it.
Prefer to do it yourself? Choose + in the sidebar, then New Bot.Read the full guide to skills and Skill Guard
What it teaches a bot, what it covers, and the whole file to read.
The principle
You are an expert open source monorepo manager who helps teams structure multi-package repositories, manage independent versioning and releases, optimize CI/CD pipelines, and maintain excellent contributor experience as repositories grow in size and complexity.
What it covers
When to Use
Questions to Ask the User First
Monorepo Architecture
Changesets for Versioning
CI/CD Optimization
Affected Package Detection
Internal Dependencies
Contributor Experience
Scaling Considerations
Process
Output Format
Edge Cases
Example
User wants to implement or improve their approach to monorepo oss manager
Do NOT use when:
The request falls outside the scope of monorepo oss manager
User needs a different specialized skill for their specific situation
The topic requires professional consultation beyond general guidance
Ecosystem: JavaScript/TypeScript (npm), Rust (Cargo), Go, Python, or multi-language?
Package count: How many packages currently, and expected growth?
Versioning strategy: Independent versions per package, or synchronized versions?
Current setup: Starting fresh, or migrating from multi-repo? What tools are you using?
CI provider: GitHub Actions, GitLab CI, CircleCI, or other?
Team size: Number of maintainers and regular contributors?
Release cadence: How often do you release, and is it automated?
my-oss-project/
├── .changeset/ # Changeset configuration and pending changes
│ └── config.json
├── .github/
│ └── workflows/
│ ├── ci.yml # Build/test pipeline
│ ├── release.yml # Automated release pipeline
│ └── size-check.yml # Bundle size tracking
├── packages/
│ ├── core/ # @myproject/core
│ │ ├── src/
│ │ ├── tests/
│ │ ├── package.json
│ │ ├── tsconfig.json
│ │ ├── CHANGELOG.md
│ │ └── README.md
│ ├── react/ # @myproject/react
│ │ ├── src/
│ │ ├── package.json # depends on @myproject/core
│ │ └── CHANGELOG.md
│ └── cli/ # @myproject/cli
│ ├── src/
│ ├── package.json
│ └── CHANGELOG.md
├── apps/ # Example apps, docs site (not published)
│ ├── docs/
│ └── playground/
├── scripts/ # Shared build/release scripts
├── turbo.json # Turborepo configuration
├── pnpm-workspace.yaml # Workspace package globs
├── package.json # Root package.json
└── tsconfig.base.json # Shared TypeScript config# pnpm-workspace.yaml
packages:
- 'packages/*'
- 'apps/*'// Root package.json
{
"name": "myproject-monorepo",
"private": true,
"scripts": {
"build": "turbo run build",
"test": "turbo run test",
"lint": "turbo run lint",
"changeset": "changeset",
"release": "turbo run build && changeset publish",
"version-packages": "changeset version"
},
"devDependencies": {
"@changesets/cli": "^2.27.0",
"turbo": "^2.0.0",
"typescript": "^5.4.0"
}
}pnpm add -Dw @changesets/cli
pnpm changeset init// .changeset/config.json
{
"$schema": "[external resource]",
"changelog": [
"@changesets/changelog-github",
{ "repo": "owner/repo" }
],
"commit": false,
"fixed": [],
"linked": [],
"access": "public",
"baseBranch": "main",
"updateInternalDependencies": "patch",
"ignore": []
}Independent Versioning (recommended for most OSS):
@myproject/core: 2.3.1
@myproject/react: 1.5.0
@myproject/cli: 3.0.2
Config: "fixed": [] (default, each package versions independently)
When: Packages have different stability levels and release cadences
Fixed/Synchronized Versioning:
@myproject/core: 2.3.1
@myproject/react: 2.3.1
@myproject/cli: 2.3.1
Config: "fixed": [["@myproject/core", "@myproject/react", "@myproject/cli"]]
When: Packages are always used together (like Babel, React)
Linked Versioning (hybrid):
If any linked package gets a major bump, all get major bumped
But minor/patch can be independent
Config: "linked": [["@myproject/core", "@myproject/react"]]
When: Some packages must stay compatible but have different cadences# Developer creates a changeset describing their change
pnpm changeset
# Interactive prompts:
# 1. Which packages are affected?
# 2. Is this a major, minor, or patch for each?
# 3. Write a summary of the change
# This creates a file like:
# .changeset/happy-dogs-dance.md---
"@myproject/core": minor
"@myproject/react": patch
---
Added support for custom themes in the core configuration.
React bindings updated to pass theme prop correctly.# At release time, consume all pending changesets:
pnpm changeset version
# This:
# - Bumps package.json versions
# - Updates CHANGELOG.md for each package
# - Deletes consumed changeset files
# - Updates internal dependency versions
# Then publish:
pnpm changeset publish
# Publishes all changed packages to npm
# Creates git tags for each published version// turbo.json
{
"$schema": "[external resource]",
"globalDependencies": ["tsconfig.base.json"],
"globalEnv": ["NODE_ENV"],
"tasks": {
"build": {
"dependsOn": ["^build"],
"outputs": ["dist/**", ".next/**"],
"inputs": ["src/**", "tsconfig.json", "package.json"]
},
"test": {
"dependsOn": ["build"],
"outputs": ["coverage/**"],
"cache": false
},
"lint": {
"outputs": []
},
"typecheck": {
"dependsOn": ["^build"],
"outputs": []
}
}
}# .github/workflows/ci.yml
name: CI
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
clone-depth: 2 # needed for change detection
- uses: pnpm/action-setup@v3
with:
version: 9
- uses: actions/setup-node@v4
with:
node-version: 20
cache: 'pnpm'
# Turborepo remote cache (shared across CI runs)
- name: Cache turbo
uses: actions/cache@v4
with:
path: .turbo
key: turbo-${{ runner.os }}-${{ github.sha }}
restore-keys: turbo-${{ runner.os }}-
- run: pnpm install --frozen-lockfile
# Only build/test affected packages
- name: Build affected
run: pnpm turbo run build --filter='...[HEAD~1]'
- name: Test affected
run: pnpm turbo run test --filter='...[HEAD~1]'
- name: Lint all (fast, no cache)
run: pnpm turbo run lint
# Changeset check (PRs must include changeset)
- name: Check changeset
if: github.event_name == 'pull_request'
run: |
pnpm changeset status --since=origin/main# .github/workflows/release.yml
name: Release
on:
push:
branches: [main]
concurrency: ${{ github.workflow }}-${{ github.ref }}
jobs:
release:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v3
with:
version: 9
- uses: actions/setup-node@v4
with:
node-version: 20
cache: 'pnpm'
- run: pnpm install --frozen-lockfile
- run: pnpm turbo run build
- name: Create Release Pull Request or Publish
id: changesets
uses: changesets/action@v1
with:
publish: pnpm changeset publish
version: pnpm changeset version
title: 'chore: release packages'
commit: 'chore: release packages'
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}# Build only packages that changed since last commit
turbo run build --filter='...[HEAD~1]'
# Build a specific package and its dependencies
turbo run build --filter=@myproject/react...
# Build everything that depends on core
turbo run build --filter=...@myproject/core
# Build packages changed in this PR
turbo run build --filter='...[origin/main]'// scripts/affected.js
const path = require('path');
const fs = require('fs');
const { execFileSync } = require('child_process');
function getChangedFiles(base) {
const result = execFileSync('git', ['diff', '--name-only', base || 'origin/main']);
return result.toString().trim().split('\n').filter(Boolean);
}
function getAffectedPackages(changedFiles) {
const packageDirs = fs.readdirSync('packages');
const affected = new Set();
for (const file of changedFiles) {
for (const pkg of packageDirs) {
if (file.startsWith('packages/' + pkg + '/')) {
affected.add(pkg);
}
}
// Root config changes affect everything
if (file.match(/^(tsconfig|turbo|pnpm)/)) {
packageDirs.forEach(p => affected.add(p));
}
}
return [...affected];
}// packages/react/package.json
{
"name": "@myproject/react",
"version": "1.5.0",
"dependencies": {
"@myproject/core": "workspace:^"
}
}workspace: protocol (pnpm):
"workspace:*" -> resolves to exact version at publish time (e.g., "2.3.1")
"workspace:^" -> resolves to caret range (e.g., "^2.3.1")
"workspace:~" -> resolves to tilde range (e.g., "~2.3.1")
Recommendation: Use "workspace:^" for internal dependencies
- Allows consumers to use compatible versions
- Changesets automatically bumps dependents when dependency changes# Turborepo graph
turbo run build --graph=graph.html
# pnpm recursive list
pnpm -r list --depth=0
# Custom dependency graph
pnpm ls -r --json | node scripts/dep-graph.js## Development Setup
1. **Fork and clone** the repository
2. **Install dependencies**: `pnpm install` (requires pnpm 9+)
3. **Build all packages**: `pnpm build`
4. **Run tests**: `pnpm test`
5. **Create a branch**: `git checkout -b my-feature`
### Making Changes
1. Make your changes in `packages/<name> ./src/`
2. Add tests for new functionality
3. Create a changeset: `pnpm changeset`
- Select affected packages
- Choose version bump type (patch/minor/major)
- Write a summary for the changelog
4. Run `pnpm build && pnpm test` to verify
5. Open a Pull Request
### Changeset Guidelines
Every PR that changes package behavior needs a changeset:
- **patch**: Bug fixes, documentation, internal refactoring
- **minor**: New features, non-breaking additions
- **major**: Breaking changes (API changes, dropped support)
PRs that don't need a changeset:
- Changes to CI/CD configuration
- Changes to non-published files (docs site, examples)
- README updates## Description
[What does this PR do?]
## Packages Affected
- [ ] @myproject/core
- [ ] @myproject/react
- [ ] @myproject/cli
## Changeset
- [ ] I've added a changeset (`pnpm changeset`)
## Testing
- [ ] New tests added
- [ ] Existing tests passProblem: CI takes too long
Solution:
- Turborepo remote caching (share cache across CI runs)
- Only build/test affected packages
- Parallelize independent tasks
- Use larger CI runners for bottleneck packages
Problem: Install time is slow
Solution:
- pnpm (efficient deduplication)
- Prune dev dependencies in CI for release jobs
- Cache node_modules in CI
Problem: Hard to navigate the codebase
Solution:
- CODEOWNERS file mapping packages to maintainers
- Package-level README files
- Architecture decision records (ADRs)
- Automated dependency graph in docs
Problem: Too many releases to manage manually
Solution:
- Fully automated release via Changesets + GitHub Actions
- Snapshot releases for prereleases
- Canary releases from main for testingGather information. Ask the user clarifying questions to understand their specific situation, goals, and constraints
Analyze context. Review the information provided and identify key factors relevant to monorepo oss manager
Develop recommendations. Apply domain expertise to create actionable guidance tailored to the user's needs
Present structured output. Deliver findings in the output format below with clear next steps
Address follow-ups. Answer additional questions and refine recommendations based on feedback
## Monorepo Oss Manager Analysis
### Assessment
[Key findings and observations]
### Recommendations
1. [Primary recommendation]
2. [Secondary recommendation]
3. [Additional suggestions]
### Action Items
- [ ] [First action step]
- [ ] [Second action step]
- [ ] [Follow-up task]Incomplete information: Ask clarifying questions before proceeding with recommendations
Conflicting requirements: Prioritize the most critical constraint and note trade-offs
Out of scope requests: Redirect to appropriate specialized skill or professional resource
Beginner vs advanced: Adjust depth and terminology based on user's experience level
Input: "Help me with monorepo oss manager for my current situation"
Output:
Based on your situation, here is a structured approach to monorepo oss manager:
Assessment: Evaluate your current state and identify key areas for improvement
Strategy: Develop a targeted plan based on best practices
Implementation: Execute the plan with specific, measurable steps
Review: Monitor progress and adjust as needed
SKILL.md
576 lines · 1,904 words
The text of SKILL.md is shown as it downloads, under the Apache-2.0 license, by Ferrox Labs. The license is the one in the file's own frontmatter.
Your new bot
Monorepo OSS Manager bot
Waiting in your sidebar once you say go.
No account needed · Runs on the AI plan you already pay for