Skip to main content
skill CX Codex

pnpm-workspace — Claude Code skill: what it does, how to install

pnpm-workspace teaches coding agents to configure pnpm monorepos and version catalogs. Useful when managing multi-package repositories.

MIT 195 installs ★ 29 updated 2026-08-17

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add oakoss/agent-skills --skill pnpm-workspace -a claude-code
Open on GitHub

What pnpm-workspace does

The skill gives an agent clear guidance on structuring monorepos with pnpm-workspace.yaml. It details how to link local packages using workspace: declarations and maintain single version sources using catalogs.

Command filtering rules prevent wasteful full repository rebuilds. The agent learns patterns to select targets by package name or git diffs relative to branches like origin/main.

Deployments on pnpm 10 will fail without setting inject-workspace-packages=true in .npmrc to hard-link dependencies. The instructions flag this requirement along with allowBuilds configuration for blocked install scripts.

What it helps with

  • configure local package links using the workspace: protocol
  • centralize dependency versions through workspace catalogs
  • target package builds based on git diffs against main branches
  • resolve pnpm 10 script blocking and deployment link issues

Example prompts for the agent

  • Run build scripts only for packages changed against origin/main.
  • Move duplicate dependency versions into the root catalog: configuration.
  • Execute test suites across @scope/web and every local package it depends on.

How to install pnpm-workspace

1Skills CLI (Vercel)

npx skills add oakoss/agent-skills --skill pnpm-workspace -a claude-code

2Manually: put the files in place

~/.claude/skills/pnpm-workspace/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/pnpm-workspace/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about pnpm-workspace

How do I install pnpm-workspace in Claude Code?

Run npx skills add oakoss/agent-skills --skill pnpm-workspace -a claude-code in your terminal.

When should this workspace skill be avoided?

Skip this skill for standalone single-package repositories or projects remaining on npm or yarn workspaces. It also does not suit setups that require floating dependency versions across separate packages.

What breaks during a pnpm 10 migration?

Version 10 blocks package lifecycle scripts unless explicitly listed under allowBuilds. Deployments also require inject-workspace-packages=true in .npmrc instead of default symlinks.

Source text

SKILL.md · MIT
---
name: pnpm-workspace
description: 'pnpm workspace monorepo management with filtering, catalogs, and shared configs. Use when setting up monorepos, managing workspace dependencies, filtering package commands, or sharing configuration across packages.'
license: MIT
metadata:
  author: oakoss
  version: '1.2'
  source: https://pnpm.io/workspaces
user-invocable: false
---

# pnpm Workspace

## Overview

pnpm workspaces provide built-in monorepo support through `pnpm-workspace.yaml`, the `workspace:` protocol for local package linking, and powerful filtering to run commands across specific packages. Catalogs enforce consistent dependency versions across all workspace packages.

**When to use:** Multi-package repositories, shared libraries with consuming apps, consistent dependency management across packages, running commands on subsets of packages.

**When NOT to use:** Single-package projects, projects already using npm/yarn workspaces (migration required), projects that need floating dependency versions per package.

## Quick Reference

| Pattern                  | API / Config                                   | Key Points                                              |
| ------------------------ | ---------------------------------------------- | ------------------------------------------------------- |
| Define workspace         | `pnpm-workspace.yaml` with `packages` globs    | Globs match directories containing `package.json`       |
| Link local package       | `"dep": "workspace:*"`                         | Always resolves to local workspace package              |
| Link with version range  | `"dep": "workspace:^1.0.0"`                    | Fails install if local version does not satisfy range   |
| Default catalog          | `catalog:` key in `pnpm-workspace.yaml`        | Single source of truth for dependency versions          |
| Named catalog            | `catalogs:` key with named groups              | Multiple version sets (e.g., `react18`, `react17`)      |
| Use catalog in package   | `"dep": "catalog:"` or `"dep": "catalog:name"` | Resolved to actual version on `pnpm publish`            |
| Filter by name           | `--filter <name>` or `-F <name>`               | Exact name or glob pattern (`@scope/*`)                 |
| Filter with dependencies | `--filter "foo..."`                            | Package and all its dependencies                        |
| Filter with dependents   | `--filter "...foo"`                            | Package and all packages that depend on it              |
| Filter by directory      | `--filter "./packages/app"`                    | All packages under a directory path                     |
| Filter by git changes    | `--filter "[origin/main]"`                     | Packages changed since a commit or branch               |
| Exclude from filter      | `--filter "!foo"`                              | Remove matching packages from selection                 |
| Run script in package    | `pnpm --filter <pkg> <script>`                 | Runs script only in matched packages                    |
| Recursive run            | `pnpm -r run <script>`                         | Runs script in all workspace packages                   |
| Install all              | `pnpm install`                                 | Single lockfile for entire workspace                    |
| Publish workspace pkg    | `pnpm publish`                                 | Replaces `workspace:` and `catalog:` with real versions |
| Inject workspace deps    | `inject-workspace-packages=true` in `.npmrc`   | Hard-links instead of symlinks; required for deploy     |
| Script security (v10+)   | `allowBuilds` in `package.json`                | Lifecycle scripts blocked by default; opt-in per dep    |

## Common Mistakes

| Mistake                                                 | Correct Pattern                                                         |
| ------------------------------------------------------- | ----------------------------------------------------------------------- |
| Using `workspace:*` then publishing as-is               | pnpm automatically replaces `workspace:*` with real versions on publish |
| Forgetting to list directory in `packages:`             | Every package directory must match a glob in `pnpm-workspace.yaml`      |
| Using `npm install` in workspace packages               | Always use `pnpm install` from the workspace root                       |
| Hardcoding versions duplicated across packages          | Use `catalog:` to centralize version definitions                        |
| Running `pnpm install` inside a sub-package             | Run from workspace root; use `--filter` to target packages              |
| Expecting `--filter` to match directory names           | `--filter` matches `package.json` `name` field, not directory names     |
| Not escaping `!` in zsh for exclude filters             | Use `\!` or quote the filter: `--filter="!foo"`                         |
| Using `workspace:` for non-workspace deps               | `workspace:` protocol only works for packages defined in the workspace  |
| Lifecycle scripts failing after pnpm 10 upgrade         | pnpm 10 blocks scripts by default; add deps to `allowBuilds` in config  |
| Using `pnpm deploy` without `inject-workspace-packages` | Set `inject-workspace-packages=true` in `.npmrc` (required in pnpm 10)  |

## Delegation

- **Workspace scaffolding**: Use `Explore` agent to discover existing package structure
- **Dependency auditing**: Use `Task` agent to check version consistency across packages

> If the `turborepo` skill is available, delegate build orchestration, task caching, and CI optimization to it.
> If the `changesets` skill is available, delegate versioning, changelog generation, and npm publishing to it.

## References

- [Workspace setup, workspace protocol, and catalogs](references/workspace-setup.md)
- [Filtering packages for targeted commands](references/filtering.md)
- [Shared configuration across workspace packages](references/shared-configs.md)
- [Monorepo integration: pnpm + Turborepo + Changesets pipeline](references/monorepo-integration.md)

© oakoss · MIT · oakoss/agent-skills

Similar skills

All skills for DevOps and infrastructure →

From the same set106

The whole set →
react-patterns react-patterns is a Claude Code skill that covers React 19 patterns, state choices, data loading with use(), and reducing needless re-renders when building or reviewing components. CX Codex +1 201installs ci-cd-architecture ci-cd-architecture is a Claude Code skill for planning CI/CD pipelines, comparing deployment platforms, and securing GitHub Actions. It supports preparing a project for production or changing its delivery setup. CX Codex +1 199installs openapi Guides the agent in writing OpenAPI 3.1 schemas and generating TypeScript clients. Ideal for REST API contract design and schema validation. CX Codex +1 197installs css-animation-patterns css-animation-patterns is a Claude Code skill for CSS animation work. It guides agents on composite properties, transitions, and newer motion APIs. CX Codex +1 196installs icon-design icon-design matches UI concepts to semantically correct icons from Lucide, Heroicons, or Phosphor with safe tree-shaking import habits. CX Codex +1 187installs pdf-tools pdf-tools — a skill for Claude Code, Codex, Cursor, GitHub Copilot and Gemini CLI that covers the full PDF lifecycle: text and table extraction, generation, modification, form filling and encryption. CX Codex +1 186installs ssh-remote ssh-remote guides coding agents through OpenSSH setups, Ed25519 key pairs, port forwarding, and rsync transfers. CX Codex +1 183installs tanstack-hotkeys An agent skill for adding keyboard shortcuts to React with TanStack Hotkeys: single bindings, key sequences, user-recorded shortcuts. CX Codex +1 179installs

Project sponsors

Companies that keep this analytics open