Agent Skills › avibebuilder/claude-prime › monorepo

monorepo

GitHub

专用于多包仓库（Monorepo）的协调技能，涵盖pnpm工作区、Turborepo构建缓存及跨包依赖管理。适用于配置共享、构建顺序修复、CI优化及版本解析调试。

.claude/starter-skills/monorepo/SKILL.md avibebuilder/claude-prime

触发场景

涉及packages, monorepo, workspace, turbo, turborepo, pnpm的多包查询跨包配置共享（ESLint, tsconfig等）修复包间构建顺序或添加新包调试pnpm catalog版本解析或CI缓存作用域

安装

npx skills add avibebuilder/claude-prime --skill monorepo -g -y

更多选项

非标准路径

npx skills add https://github.com/avibebuilder/claude-prime/tree/main/.claude/starter-skills/monorepo -g -y

不安装直接使用

npx skills use avibebuilder/claude-prime@monorepo

指定 Agent (Claude Code)

npx skills add avibebuilder/claude-prime --skill monorepo -a claude-code -g -y

安装 repo 全部 skill

npx skills add avibebuilder/claude-prime --all -g -y

预览 repo 内 skill

npx skills add avibebuilder/claude-prime --list

SKILL.md

Frontmatter

{
    "name": "monorepo",
    "description": "MUST use for ANY query mentioning packages, monorepo, workspace, catalog, turbo, turborepo, or pnpm in a multi-package context. MUST use when sharing config (ESLint, tsconfig, prettier) across packages, fixing build order between packages, adding new packages, scoping CI installs\/caching to changed packages, or debugging pnpm catalog version resolution. This skill OWNS all cross-package coordination problems — even when they look like build, CI, config, or dependency issues. If two or more packages interact in the query, this skill applies. Takes priority over other skills when the problem spans package boundaries."
}

Monorepo

Project-specific patterns for pnpm workspaces + Turborepo.

Architecture Decisions

Workspace Organization

Split apps from packages — apps/ for deployables, packages/ for shared libraries.
Namespace packages — Prefix with @org/ to avoid npm conflicts.
Single lockfile — pnpm-lock.yaml at root only. Never commit multiple lockfiles.
No cross-package file access — Never use ../ to reach into other packages; import via dependencies.

Dependency Management

Use workspace:* protocol — Always for internal package dependencies.
Hoist common devDependencies — Shared tooling (TypeScript, ESLint) in root.
Peer dependencies for frameworks — React, Vue, etc. as peers to avoid version conflicts.
Consider Catalogs (pnpm 9.5+) — Centralize versions in pnpm-workspace.yaml for large repos.

Turborepo Tasks

Use ^ for build dependencies — "dependsOn": ["^build"] for topological order.
Always define outputs — Without outputs, nothing gets cached.
Mark dev servers as persistent — "persistent": true, "cache": false.
Be explicit about environment — List all build-affecting vars in env or globalEnv.

Gotchas

Missing outputs in turbo.json silently disables caching for that task. The task runs every time and you won't get an error — just slow builds. Always verify outputs are configured.
pnpm install does NOT respect --filter for installation — it always installs the entire workspace. Filtering only works for pnpm run and pnpm exec.
workspace:* resolves to the CURRENT version of the local package, not "latest from npm". If the package has "version": "0.0.0", published packages will have "dependency": "0.0.0" — set meaningful versions before publishing.
Turborepo's env field in turbo.json uses GLOB patterns, not exact matches. "env": ["API_*"] captures API_KEY, API_URL, etc. Forgetting this causes over-invalidation.
turbo run build --filter=app-a builds app-a AND all its workspace dependencies. If a dependency fails, app-a won't build. Check transitive deps.
Adding a package to packages/ requires running pnpm install before the workspace recognizes it. The new package also needs a valid package.json with name matching the workspace pattern.
TypeScript project references (references in tsconfig.json) must match the workspace dependency graph. Mismatches cause type errors that only appear during tsc --build, not in IDE.
turbo.json's globalDependencies invalidates ALL tasks when listed files change. Don't put frequently-changed files here — use task-level inputs instead.
Shared Tailwind configs need @source directives pointing to consuming packages' source directories, otherwise classes used in shared packages are purged.
pnpm deploy (for production) copies a single package and its dependencies to a target directory. It does NOT run build scripts — build first, then deploy.
Remote cache (Vercel or self-hosted) requires outputs to be correct. If outputs are wrong, cached artifacts will be incomplete and downstream tasks break silently.
persistent: true tasks prevent turbo run from exiting. Don't include persistent tasks in CI pipelines unless they have a timeout.

References

When you need...	Read
workspace.yaml, workspace: protocol, filtering	pnpm-workspace.md
turbo.json schema, tasks, dependsOn	turborepo.md
Cache outputs/inputs, remote cache setup	caching.md
Directory layout, package naming, tsconfig	structure.md
Tailwind v4 shared theme package	tailwind-v4.md