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
npx skills add oakoss/agent-skills --skill pnpm-workspace -a claude-codeWhat 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/weband 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-code2Manually: put the files in place
~/.claude/skills/pnpm-workspace/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/pnpm-workspace/
1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill pnpm-workspace -a codex2Manually: put the files in place
.agents/skills/pnpm-workspace/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill pnpm-workspace -a cursor2Manually: put the files in place
.cursor/skills/pnpm-workspace/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install oakoss/agent-skills skills/pnpm-workspace2Manually: put the files in place
.github/skills/pnpm-workspace/SKILL.md1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill pnpm-workspace -a gemini-cli2Platform CLI
gemini skills install https://github.com/oakoss/agent-skills --path skills/pnpm-workspaceManually: put the files in place
.devin/skills/pnpm-workspace/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill pnpm-workspace -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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