Agent skills install from the npm packages the project already has

.drive/projects/prisma-cli-v8/deferred.md

@@ -454,3 +454,20 @@ The cleanup PR removed the compute config and `init`, made service commands para
 - ~~**orm-toolchain's shipped help examples name retired spellings.**~~ Closed (2026-08-22) by prisma#30102: the family keys are the mount paths and the examples follow; `tests/orm-mount.test.ts` now asserts upstream stays clean.
 - ~~**The deployment-id targeting asymmetry is undocumented.**~~ Closed on the PR branch (2026-08-21): every deployment-id command (`promote|start|stop|delete|show`, `logs --deployment`) now resolves the id globally with no service parameter, per the "Subjects are positional" ruling.
 - **`GET /v1/deployments/{id}` omits the parent `appId`.** Verified against `@prisma/management-api-sdk@1.55.0`: the response carries id/status/url/previewDomain/envVars/createdAt and no owning-app pointer, so `showDeployment` finds the owner via `findAppForDeployment` — a scan of every project's service list and each service's deployments — and every id-targeted command pays it per run. The fix is in pdp-control-plane: include `appId` in the deployment representation; the CLI then swaps the scan for one `GET /v1/apps/{appId}`.
+
+## From the agent-skills delivery (project closed 2026-08-22)
+
+- **Config evaluation fails through unrealpath'd pnpm symlinks; the verified fix waits for the next engine release.** The engine's lazy `await import("c12")` (packages/cli-engine/src/config-loader.ts) resolves through a pnpm symlink without realpathing, so c12's own `pathe` import walks up from the symlink path and misses its store siblings — `CLI.CONFIG_UNREADABLE: Cannot find package 'pathe'`. Affects this repo's dev layout and pnpm `hoist=false` installs only; npm and default-pnpm installs work. The fix is one line, verified empirically: import c12 via `pathToFileURL(realpathSync(fileURLToPath(import.meta.resolve("c12"))))`. It was implemented on PR #219 and reverted because any engine change forces a version bump and the families (`@prisma/orm-toolchain`, `@prisma/composer-cli`) peer-pin the engine exactly, requiring a coordinated family release. Ship it with the next engine version train; the init e2e's rerun workaround (removing the config before the second binary run) comes out at the same time.
+
+
+The agent-skills project (skills sync/list, `prisma init`, the staleness notice; PR #219) closed with these items still open; details were in its own ledger, summarized here as the surviving record.
+
+- **When facade skill content diverges per database, split the skill by name — never add a carrier package** (operator concurred 2026-08-21). Today every facade ships an identical `prisma-8` skill and conflicts are arbitrated by highest version, safe only while content is identical and versions are lockstep. A transitive carrier package is unresolvable from the project root under pnpm; a direct-dependency skills package breaks the installed-version guarantee. The allowlist grows one deliberate line per facade either way.
+- **The browser login success page still shows a static `npx skills add prisma/skills` copy button** (`packages/cli/src/auth/login.ts` ~571) — the last surface promoting the retired third-party installer after the `agent` group's deletion. Decided 2026-08-24: the operator is having the responsible team remove it; not part of PR #219.
+- **Composer website hero copy** (prisma/composer `website/src/template.ts`): still says `npx skills add prisma/composer`; the replacement wording and its release timing belong to the site owner, and the new command only exists once the CLI ships.
+- **`check-skill-packaging.mjs` hardcodes `@prisma/composer`** (prisma/composer) while `stage-skills.mjs` is generic; generalize when a second skill-bearing composer package appears.
+- **Turbo race: `pnpm test` can rebuild `cli-engine` dist while `cli` tests import it** (intermittent `Failed to resolve entry for package "@prisma/cli-engine"`). Fix: `dependsOn` on the engine build in turbo.json.
+- **Windows CI: the credential-manager suite needs an owner** — two distinct timing-sensitive tests flaked on 2026-08-21 (`credential-manager.test.ts` "holds no lock while the workspace name is fetched", run 32477175789; `credential-manager-processes.test.ts` "exchanges one refresh token once", run 32497093995), both on pushes touching nothing near credentials.
+- **Windows CI: `skills-sync.test.ts` timed out once at the 5s default** (run 32474645762) with a teardown ENOTEMPTY from cleanup racing the timed-out test. If it recurs, raise the suite's per-test timeout on Windows rather than chasing the race.
+- **`isLikelyGlobalNpmEntrypoint` (update-check.ts) matches only `prisma-cli` install paths**, so a globally-installed `prisma` gets the docs-link fallback instead of a concrete update command; `selectUpdateInstruction` still names `@prisma/cli`. Newly conspicuous after the CLI_NAME → prisma rename.
+- **The feedback client's user-agent changed from `prisma-cli/<version>` to `prisma/<version>`** — wire-visible; whoever reads that dashboard should know.

.drive/projects/prisma-cli-v8/specs/config-file-resolution.md

@@ -0,0 +1,75 @@
+# Finding and resolving prisma.config.ts when a repository has more than one
+
+Status: design discussion. Nothing below is decided except where explicitly marked. This document exists so the discussion can start from the constraints and the options already explored, rather than rediscovering them.
+
+## Background: how the config file works in the Prisma 8 CLI
+
+`prisma.config.ts` is the Prisma 8 CLI's configuration file. It is real TypeScript that the CLI evaluates, and its default export must be wrapped in `definePrismaConfig(...)`, which stamps a version marker on the object. A `prisma.config.ts` without the marker — for example one written for Prisma 7, which uses the same filename — is rejected with a clear error rather than half-interpreted.
+
+Every top-level key in the config object is a **section**, and each section belongs to one part of the CLI: `skills` configures the agent-skills feature today, and the ORM will have its own section. The set of section names is closed — a key the CLI does not recognise is an error, on the theory that silently ignoring settings a user wrote is worse than failing.
+
+Today the CLI reads **exactly one file**: the one named with `--config`, otherwise `prisma.config.ts` in the directory the command runs in. It never looks anywhere else. Commands that have no config settings never read or evaluate the file at all.
+
+## The problem
+
+Two facts collide.
+
+**First: commands run from subdirectories.** If the config sits at the repository root and you run a command from `apps/api/`, a current-directory-only lookup finds nothing. The CLI needs to search upward. But the moment it searches upward, a repository can have several `prisma.config.ts` files on the path between the current directory and the root — and the CLI needs a rule for which one answers.
+
+**Second: different commands need different files.** Take this repository, which reflects the most common real-world layout:
+
+```
+acme/
+  prisma.config.ts          ← deploy target, platform settings
+  packages/
+    db/
+      prisma.config.ts      ← ORM settings (schema location, migrations)
+    api/
+```
+
+The ORM's settings live in the package that owns the database code — that is the mainstream pattern, not an edge case. But `prisma deploy`, `prisma project link`, and everything Composer-related is scoped to the repository as a whole; those settings live at the root. So when you run an ORM command from `packages/db`, the right file is `packages/db/prisma.config.ts` — and when you run `prisma deploy` from that same directory, the right file is the root one.
+
+No rule that picks **one file for everything** can satisfy both. That is the core finding of the design work so far, and the two rejected options below show each half of it failing.
+
+## Rejected: "the highest file wins"
+
+Rule: search upward from the current directory; the file closest to the filesystem root wins, unless a file on the way declares `root: true`, which stops the search there (like ESLint's old `root: true`).
+
+In the example repo, every command run inside `packages/db` — including ORM commands — reads the **root** config. The ORM settings in `packages/db/prisma.config.ts` are ignored completely. The only escape is declaring `root: true` in the package's file, which then hides the root config from that package entirely — so `deploy` breaks from inside the package instead. One file, all or nothing, in either direction. This breaks the mainstream ORM layout, so it was rejected. (It was briefly implemented; see the appendix.)
+
+## Rejected: "the nearest file wins"
+
+Rule: search upward; the first file found wins.
+
+Now the ORM case works: inside `packages/db`, the package's config answers. But run `prisma deploy` from `packages/db` and the CLI reads the package's config too — which has no deploy settings, and the root config that has them is never consulted. Root-scoped commands only work from the repository root. Rejected.
+
+A third option — letting each part of the CLI declare "I am root-scoped" or "I am nearest-scoped" and searching accordingly — was rejected as redundant: where a section is *written* already encodes that, without inventing a declaration mechanism that every feature has to get right.
+
+## Proposed (not decided): resolve per section, nearest definition wins
+
+Rule: search upward from the current directory and collect **every** `prisma.config.ts` on the path; a file declaring `root: true` ends the collection. Then resolve each **section** independently: a section comes from the nearest file that defines it. Sections are atomic — the nearest definition wins whole; there is no merging of a section across files.
+
+In the example repo, from inside `packages/db`:
+
+- ORM command → the `orm` section is defined in `packages/db/prisma.config.ts` → the package's settings apply. ✓
+- `prisma deploy` → the nested file has no deploy/Composer section → the search continues upward and finds it in the root file. ✓
+- `skills: { check: false }` written at the root reaches `packages/db` too, because the nested file only shadows the sections it actually defines. ✓
+
+The costs, stated plainly:
+
+1. A command may evaluate more than one file — every config on the path up to the stopping point. Config files are executable TypeScript, so that is real user code running and a transpile per file. It is bounded by directory depth and cacheable within a run, and only commands that actually consume config trigger any of it.
+2. A broken file anywhere on the path — Prisma 7 format, syntax error — fails the command with an error naming that file. The proposal is to fail early rather than skip broken files, on the theory that a half-read path is worse than an error that says exactly which file to fix.
+3. The loader's result stops being "one file's contents" and becomes a resolved view over several files, and every diagnostic must say which file it is about. That is genuine engineering work in the CLI engine.
+
+## Open questions for this discussion
+
+- Is per-section nearest-first the right model, or is there a simpler rule that satisfies both the nested-ORM layout and root-scoped commands?
+- Two files on the path define the same section: nearest silently wins, or wins with a printed notice?
+- Where does the upward search stop when no file declares `root: true` — filesystem root, home directory, or a repository boundary such as the directory containing `.git`? (Under a one-file rule this mattered little; under collect-everything, every file on the path gets evaluated, so the stopping point deserves a fresh look.)
+- What does `--config <file>` mean here: read only that file, or treat it as the nearest layer with the search continuing above it?
+- Does the unknown-section check run per file, so a typo'd key in a nested file still errors even though the command's sections resolved elsewhere?
+- Should `prisma init` scaffold a `prisma.config.ts` once this design lands, and does the `root: true` marker keep that name?
+
+## Appendix: prior implementation, kept as reference
+
+The "highest file wins" rule was implemented in the CLI engine and then removed when the discussion surfaced the nested-ORM problem (branch `claude/agent-skills-npm-packages-770857` in prisma/prisma-cli; commits `ba48d46` and `f72503c`, removed by `9b2f9d0` — recoverable from history). A code review of that implementation catalogued edge cases any future implementation should handle regardless of the chosen rule: resolve the search's starting directory through symlinks so errors name real paths; keep loader tests anchored so a stray config file in a real ancestor of the checkout cannot leak into them; enforce reserved-key handling on the engine side of the pluggable-loader boundary, not only inside the default loader; and name the offending value in validation errors. The full findings are in the same repository under `.drive/projects/agent-skills-npm-packages/reviews/code-review.md`, round "Init slice — Round 1".

biome.jsonc

@@ -69,6 +69,7 @@
       "includes": [
         "packages/cli-engine/src/exports/**",
         "packages/cli-telemetry/src/exports/**",
+        "packages/prisma/src/config.ts",
         "packages/cli/src/shell/cli-command.ts",
         "packages/cli/src/shell/command-arguments.ts",
         "packages/cli/src/shell/errors.ts",

docs/architecture/overview.md

@@ -22,8 +22,7 @@ flowchart TD
 ## Command Flow
 
 1. `packages/cli/src/bin.ts` starts the Node process and calls `main`.
-2. `packages/cli/src/main.ts` builds the CLI, runs the update check, and
-   hands the engine a runtime assembled from `process`.
+2. `packages/cli/src/main.ts` builds the CLI, runs the update check, hands the engine a runtime assembled from `process`, and after the command has run reports out-of-date agent skills.
 3. `packages/cli/src/cli.ts` mounts every command and command family.
 4. The engine parses argv, decides interactivity and credentials, dispatches
    the handler, and renders its result.
@@ -52,6 +51,7 @@ implementation.
 Local state boundaries are also explicit:
 
 - `.prisma/local.json` stores the linked project ID (a gitignored local pin, not a committed config file).
+- `.prisma/skills.json` stores whether the agent-skills staleness check is silenced for this project (written by `skills sync --disable`).
 - Active branch and app selection are local CLI state.
 - Secret values must not be printed in human output or structured output.
 

docs/product/cli-style-guide.md

@@ -83,8 +83,8 @@ project show → This directory is not linked to a Prisma Project.
 │  project:    Not linked
 
 Next steps:
-- Link an existing Project you choose: prisma-cli project link <id-or-name>
-- Create a new Project: prisma-cli project create billing-api
+- Link an existing Project you choose: prisma project link <id-or-name>
+- Create a new Project: prisma project create billing-api
 ```
 
 Rules:

docs/product/command-principles.md

@@ -28,7 +28,7 @@ Use the other convention docs for adjacent concerns:
 
 The long-term command surface grows through workflow groups such as:
 
-- `agent`
+- `skills`
 - `auth`
 - `project`
 - `branch`
@@ -38,7 +38,7 @@ The long-term command surface grows through workflow groups such as:
 - `app`
 - `git`
 
-The preview implements only `agent`, `auth`, `project`, `git`, `branch`, `database`, `bucket`, and `app`.
+The preview implements only `auth`, `project`, `git`, `branch`, `database`, `bucket`, `app`, `skills`, and `init`.
 
 ## Stable Nouns
 
@@ -93,6 +93,14 @@ No current branch command uses `use`; branch targeting follows explicit flags or
 
 Build and release an app into a target branch.
 
+### `init`
+
+Prepare the current repository for Prisma development, entirely locally: add the `postinstall` script that keeps the Prisma agent skills in sync (`prisma skills sync || exit 0`), scaffold a `prisma.config.ts` recording which agents get skills, then sync the skills once now.
+
+The scaffolded config imports `definePrismaConfig` from `prisma/config` and spells out `skills: { agents: [...] }`. The agents come from the `--skills` flag (`--skills=claude,cursor`, validated against the known agent names), or the default set when the flag is absent. `--skills=none` records the choice rather than merely skipping: the scaffold is written with `skills: { agents: [] }` — the committed record that no agent skills are wanted — and the sync is skipped on that run; with `agents: []` in place, later syncs, `skills list`, and the staleness notice all treat the project as having no skills to manage. There is no harness detection: the config is the only authority on which agents a project uses.
+
+`init` calls no platform API, never prompts, and never edits a file the user already owns: a `postinstall` script the user wrote and an existing `prisma.config.ts` are both left alone and reported as diagnostics — the config diagnostic shows the exact `skills: { agents: [...] }` snippet to add by hand. Everything lands in the current directory: the hook in its `package.json`, the config beside it, the skill copies in the agent directories under it. Rerunning is safe; each step reports what is already done and the command exits 0.
+
 ### `logs`
 
 Resolve a service version and show or stream its logs.

docs/product/error-conventions.md

@@ -66,7 +66,7 @@ Examples:
 - unexpected `undefined`
 - internal serialization or state invariant broken
 
-Bugs should fail fast and preserve stack traces. Catch them only at the outermost boundary for crash formatting. At that boundary, `--json` runs still emit the standard error envelope with code `UNEXPECTED_ERROR`, and both output modes point at `prisma-cli feedback` pre-filled with the failing command and error line (`--quiet` suppresses the human hint; expected failures never carry the feedback suggestion).
+Bugs should fail fast and preserve stack traces. Catch them only at the outermost boundary for crash formatting. At that boundary, `--json` runs still emit the standard error envelope with code `UNEXPECTED_ERROR`, and both output modes point at `prisma feedback` pre-filled with the failing command and error line (`--quiet` suppresses the human hint; expected failures never carry the feedback suggestion).
 
 ## Boundary Handling
 
@@ -107,7 +107,7 @@ This is usually a missing env var, a failed DB connection,
 or a crash on startup.
 
 See what happened
-prisma-cli app logs --deployment <id>
+prisma app logs --deployment <id>
 
 URL
 https://cv-...
@@ -231,7 +231,7 @@ These codes are the minimum stable set for the MVP:
 Recommended meanings:
 
 - `USAGE_ERROR`: invalid arguments or invalid command combination
-- `UNEXPECTED_ERROR`: the CLI crashed on an unexpected fault; the envelope carries a `recover` next action suggesting `prisma-cli feedback`
+- `UNEXPECTED_ERROR`: the CLI crashed on an unexpected fault; the envelope carries a `recover` next action suggesting `prisma feedback`
 - `FEEDBACK_SEND_FAILED`: the feedback service was unreachable, timed out, or returned a non-2xx response
 - `AUTH_REQUIRED`: command needs an authenticated session
 - `AUTH_CONFIG_INVALID`: environment auth configuration is present but unusable, such as an empty `PRISMA_SERVICE_TOKEN`