Agent skills install from the npm packages the project already has

[wmadden-electric]

In a project that has @prisma/orm-postgres installed, this now works — no network, no extra tooling:

$ prisma skills sync
Synced 1 skill.
  project  /work/my-app
  check    enabled

  Skill      Package               Version   Installed into
  prisma-8   @prisma/orm-postgres  8.1.0     .claude/skills, .cursor/skills, .agents/skills, .windsurf/skills

And after pnpm up @prisma/orm-postgres bumps the package but nobody re-runs sync, every prisma command appends one line to stderr:

Prisma agent skills are out of date (installed @prisma/orm-postgres 8.1.0, synced 8.0.0). Run: prisma skills sync

Base: this PR is stacked on #218 (claude/kind-jennings-32a0e4) and shows only its own diff; GitHub retargets it to main when #218 merges.

The decision

Agent skills now travel inside the npm packages they describe, and this PR adds the CLI half of that: prisma skills sync copies them into place, prisma skills list reports status, prisma init sets a project up once, and a staleness notice after every command keeps the copies from silently rotting.

An agent skill is a directory with a SKILL.md — instructions that teach a coding agent (Claude Code, Cursor, Codex, Windsurf) how to use a library. Each harness auto-indexes skills from a known project directory (.claude/skills/, .cursor/skills/, .agents/skills/, .windsurf/skills/); a skill anywhere else is invisible. So a skill is only useful if something copies it into those directories and keeps the copy matching the installed package version. Until now that something was prisma orm init shelling out to a third-party CLI that cloned our skills from GitHub at a ref named after the package version — a convention, not a guarantee — and nothing ever detected that the copies had gone stale.

How sync decides what to install

Sync resolves a hardcoded allowlist of four packages — @prisma/orm-postgres, @prisma/orm-sqlite, @prisma/orm-mongo, @prisma/composer — by name from the project root and each workspace member directory. It never scans node_modules: a skill is instructions an agent will follow, so a scanner would let any transitive dependency inject instructions into the agent. That invariant is stated (and marked permanent) at the allowlist declaration, and this PR's trust boundary is exactly the code's — the only skills installed come from packages the user deliberately installed.

Each shipped SKILL.md carries a version stamp in its frontmatter, under the Agent Skills spec's metadata map (custom top-level keys are not spec-defined):

metadata:
  library: "@prisma/orm-postgres"
  library_version: "8.1.0"

Sync compares the installed package's version against the stamp in each harness copy and re-copies on mismatch. Pruning removes only copies whose stamp names an allowlisted package that is no longer installed — a skill some other tool put there is never touched. The synced copies are ordinary files git tracks; sync removes the * ignore file an earlier revision wrote into its copies, but leaves any .gitignore a user authored in place. If two workspace members pin different versions of one package, the highest wins and sync warns. Yarn PnP works because all reads go through Node's resolution and fs layers (there is a test that fakes the PnP zip filesystem to prove it).

Sync refuses what it does not own. A target directory whose SKILL.md is unstamped, unreadable, or stamped by a non-allowlisted package — a hand-written skill colliding on name — is left byte-for-byte intact, reported in a refused array and a SKILLS.UNMANAGED_DIRECTORY diagnostic, and the summary line never claims "up to date" without naming it. A directory whose SKILL.md is genuinely absent (an interrupted copy) is repaired.

prisma init

prisma init initializes a repository for Prisma development, purely locally — no platform calls. Two steps, each with an opt-out (--no-postinstall, --no-skills), always exit 0, never prompts, idempotent:

1. Adds "postinstall": "prisma skills sync || exit 0" to the current directory's package.json, so skills resync on every install and upgrade. A different existing postinstall script is never clobbered or chained — init reports it and tells the user what to append. BOM, CRLF, indentation, and trailing-newline style are preserved; an unreadable, unwritable, or malformed manifest is a diagnostic, not a failure.
2. Runs the skills sync in-process at the discovered workspace root. A sync failure is a diagnostic on a successful init.

This is a new command reusing a retired name: #218 deleted the old compute-config wizard, and nothing from it returns. Sync itself still never touches package.json (a test pins byte-identity across a sync run) — writing the hook is exclusively the act of a user running init.

The prisma agent group is deleted

prisma agent install|update|status — the old installer that shelled out to npx skills@latest for the v6/v7 skills — is gone (operator ruling, 2026-08-21). The post-login tip that advertised it now offers prisma skills sync instead, only when installed packages actually have stale copies, and can no longer fail a login that already succeeded.

The staleness notice

It prints to stderr, after the command's own output, never changes the exit code, and is deliberately not TTY-dependent — its main reader is an agent running the CLI without one. Off switches: --quiet, --json / --format json, --version, PRISMA_SKILLS_CHECK=0, CI/GITHUB_ACTIONS, skills: { check: false } in prisma.config.ts (an explicit --config <path> is honored), a persistent opt-out written by prisma skills sync --disable (stored in .prisma/skills.json), and any skills command itself. Flag scanning stops at a bare --. The per-command cost is stat calls and small file reads; prisma.config.ts is only evaluated after staleness is already established. With the init-written postinstall as the primary trigger, the notice is the backstop for projects that never ran init or removed the script.

Pin and state dir find the project root

.prisma/local.json (the link pin) and the state dir are now discovered by walking up from the cwd to the nearest directory containing .prisma/ — a pure filesystem check, no config file is read — so a repo linked at its root works from apps/api/. Nearest wins deliberately: a subdirectory linked to a different project beats the root. Commands that rewrite or delete the pin operate on the file they found, not on the cwd. When no .prisma/ exists, behavior is unchanged.

The rename: CLI_NAME is now prisma

The published package (prisma) has installed a bin named prisma since 8.0.0-rc.3, but every string the CLI printed still said prisma-cli. This PR moves CLI_NAME, so help text, error guidance, and the notice above all name the binary users actually have. There is no compatibility layer: the CLI is pre-rc and owes old spellings nothing, so every producer of error guidance was fixed to emit the current commands directly, and the display-time rewriter that used to patch up legacy spellings (renameAppCopy and friends) was deleted rather than extended. fromLegacyCliError survives only as a structural converter (legacy error shape → CliError); it no longer rewrites or filters any copy. Deliberate survivals, so nobody "finishes" the rename by mistake: the @prisma/cli package's own bin and README, the update-check entrypoint matcher and cache directory, git@github.com:prisma/prisma-cli.git repo URLs, and the utm_source/utm_campaign sign-in tags.

Tests

90+ new tests: npm/pnpm/Yarn-PnP fixture projects, every sync/check state (stale, never-synced, in-sync, refused, opted out), the collision and unreadable-skill refusals (chmod-based), pruning on package removal, a two-member monorepo with the version-conflict warning, every off switch, init's full package.json edge-case matrix (foreign script, non-object scripts, BOM, CRLF, read-only file, missing manifest), a credential-free e2e driving the built binary through init twice, a readdir-count regression test bounding workspace-glob expansion, and the legacy-error mapper suite.

For other owners

• The feedback client's user-agent changed from prisma-cli/<version> to prisma/<version> — wire-visible; whoever reads that dashboard should know.
• isLikelyGlobalNpmEntrypoint (update-check) still matches only prisma-cli install paths, so a globally installed prisma gets the docs-link fallback instead of a concrete update command. Pre-existing, untouched here, newly conspicuous.
• The browser login success page still shows a static npx skills add prisma/skills copy button — the last surface promoting the retired installer; its removal is pending an operator decision.
• Init stops touching agent skills; the family-level prisma init owns skills setup prisma#30097 (orm init) drops its scaffold-time sync call per operator ruling — follow-up on that PR.

Merge order: #218 merges first (this PR is stacked on it), then this PR, then prisma/prisma#30096 (packaging) and prisma/composer#251's npm release — both ship skills only this CLI can read.

Alternatives considered

• Keep fetching from GitHub via npx skills add (status quo): version matched by ref-name convention only, unmanaged copies, network access during init, and an unpinned third-party CLI in our init path.
• Discover skills by scanning node_modules: prompt-injection by construction — any transitive dependency could plant instructions. Permanently rejected.
• Symlinks into node_modules instead of copies: no node_modules under Yarn PnP, symlink creation needs elevation on Windows, and only Claude Code documents following symlinked skills. Version-stamped, checked, auto-resynced copies are a managed cache.
• A line in AGENTS.md telling agents to run sync each session: rejected by the team — agents shouldn't carry maintenance duties.
• A postinstall in our own packages: dependency lifecycle scripts are blocked by default in pnpm 10+, bun, and Deno. Permanently rejected.
• Writing a postinstall from prisma orm init or from sync itself (the original design): rejected — a routine command silently editing your package.json, or re-adding a script you removed, is not acceptable. The operator's final ruling: the hook is written only by prisma init, a command whose whole point the user invokes deliberately; nothing automatic ever edits the manifest, and the staleness notice covers everyone else.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 0ca6e80e-b6ed-49a3-9abf-1d5671aa0399

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[pkg-pr-new]

Open in StackBlitz

npx https://pkg.pr.new/@prisma/cli@219

npx https://pkg.pr.new/@prisma/cli-engine@219

commit: 8842b4c