feat(cli): add agent skills setup flow

Author: AmanVarshney01

docs/product/command-spec.md

@@ -10,6 +10,7 @@ This file is authoritative for command group scope during beta.
 
 The beta package includes these command groups:
 
+- `agent`
 - `auth`
 - `project` (includes `project env` subgroup)
 - `git`
@@ -373,6 +374,81 @@ prisma-cli --version --json
 
 `prisma-cli version` is the richer environment report; `prisma-cli --version` is the terse one-liner. Both report the same `cli.version`. Use the flag for quick checks, the subcommand for support tickets and bug reports.
 
+## `prisma-cli agent install --agent <agent> --all-agents --skill <skill> --global --copy`
+
+Purpose:
+
+- install Prisma context for AI coding agents
+
+Behavior:
+
+- writes managed Prisma sections to `AGENTS.md` and `CLAUDE.md`
+- installs Prisma skills from `prisma/skills` by invoking `skills@latest` through the detected project package manager:
+  `<runner> skills@latest add prisma/skills --skill "*" --agent codex --agent claude-code --yes`
+- detects the runner from the current directory and its ancestors:
+  - `bun.lock`, `bun.lockb`, or `packageManager: "bun@..."` -> `bunx`
+  - `pnpm-lock.yaml`, `pnpm-workspace.yaml`, or `packageManager: "pnpm@..."` -> `pnpm dlx`
+  - `yarn.lock` or `packageManager: "yarn@..."` -> `yarn dlx`
+  - `package-lock.json`, `npm-shrinkwrap.json`, `packageManager: "npm@..."`, or no package-manager signal -> `npx -y`
+- defaults to the `codex` and `claude-code` agent targets because those are the primary local agent workflows during beta
+- accepts repeated `--agent <agent>` flags to target specific skills CLI agents, such as `codex`, `claude-code`, or `cursor`
+- accepts `--all-agents` to pass `--agent "*"` to the skills CLI
+- accepts repeated `--skill <skill>` flags to install a subset such as `prisma-compute`
+- accepts `--global` and `--copy` and forwards them to the skills CLI
+- accepts `--skip-skills` to only write managed project files
+- accepts `--skip-project-files` to only install skills
+- accepts `--dry-run` to report planned project-file changes and the skills CLI command without writing files or spawning the installer
+- is idempotent; existing managed sections are replaced and unrelated user-authored content is preserved
+
+Examples:
+
+```bash
+prisma-cli agent install
+prisma-cli agent install --agent codex
+prisma-cli agent install --agent codex --agent cursor
+prisma-cli agent install --all-agents
+prisma-cli agent install --skill prisma-compute
+```
+
+## `prisma-cli agent update --agent <agent> --all-agents --skill <skill> --global --copy`
+
+Purpose:
+
+- refresh Prisma agent files and Prisma skills
+
+Behavior:
+
+- has the same flags and behavior as `agent install`
+- reruns the detected package-manager runner with `skills@latest add prisma/skills ...` instead of `skills update`, so it refreshes only Prisma's skills and works for project-scoped installs
+
+Examples:
+
+```bash
+prisma-cli agent update
+prisma-cli agent update --agent codex
+prisma-cli agent update --all-agents
+```
+
+## `prisma-cli agent status`
+
+Purpose:
+
+- show whether Prisma agent context is installed in the current project
+
+Behavior:
+
+- reports whether `AGENTS.md` and `CLAUDE.md` contain Prisma-managed sections
+- reports whether `skills-lock.json` references `prisma/skills`
+- reports whether the project has dismissed the interactive agent setup prompt
+- does not access the network and does not require authentication
+
+Examples:
+
+```bash
+prisma-cli agent status
+prisma-cli agent status --json
+```
+
 ## `prisma-cli auth login`
 
 Purpose:
@@ -386,6 +462,9 @@ Behavior:
 - resolves active workspace when required
 - confirms successful browser authentication and directs the user back to the terminal
 - returns the current auth state after login
+- in human output, when run from a project directory that does not already have Prisma agent context and has not dismissed the setup prompt, suggests `prisma-cli agent install`
+- does not install agent files during auth; auth is not project-scoped and must not mutate project guidance files
+- does not show the agent setup tip in `--json`, `--quiet`, CI, non-TTY output, or directories that do not look like projects
 
 Examples:
 
@@ -1066,6 +1145,8 @@ Behavior:
 - maps user-facing framework names to deploy build strategies
 - does not accept `--build-command` or `--output-directory`; custom build settings live in the `build` block of `prisma.compute.ts`
 - deploys arbitrary framework output with `framework: "custom"` when the config provides a built output directory and entrypoint; `build.command` is optional for prebuilt artifacts
+- in interactive human deploys, prompts once to install Prisma agent guidance for the project when it is missing; accepting runs `prisma-cli agent install` behavior from the project directory, declining records the prompt as dismissed in local CLI state
+- does not prompt for agent setup in `--json`, `--quiet`, CI, `--no-interactive`, or `--yes`, and does not treat `--yes` as permission to mutate agent guidance files
 - uses `src/index.ts` as the Hono deploy entrypoint when the app has no `package.json#main` or `package.json#module` and that file exists
 - supports vanilla Bun apps with `--framework bun` using `package.json#main` or `package.json#module`, or with `--entry <path>`
 - treats `--entry <path>` without `--framework` as a Bun app deploy

packages/cli/src/adapters/local-state.ts

@@ -22,6 +22,9 @@ export interface LocalState {
     selectedByProject: Record<string, SelectedAppState>;
     knownLiveDeploymentByProject: Record<string, Record<string, string>>;
   };
+  agent: {
+    setupPromptDismissedAt: string | null;
+  };
 }
 
 export interface SelectedAppState {
@@ -49,6 +52,9 @@ const DEFAULT_STATE: LocalState = {
     selectedByProject: {},
     knownLiveDeploymentByProject: {},
   },
+  agent: {
+    setupPromptDismissedAt: null,
+  },
 };
 
 export const DEFAULT_STATE_FILE_NAME = "state.json";
@@ -91,6 +97,9 @@ export class LocalStateStore {
           knownLiveDeploymentByProject:
             parsed.app?.knownLiveDeploymentByProject ?? {},
         },
+        agent: {
+          setupPromptDismissedAt: parsed.agent?.setupPromptDismissedAt ?? null,
+        },
       };
     } catch (error) {
       if ((error as NodeJS.ErrnoException).code === "ENOENT") {
@@ -253,4 +262,18 @@ export class LocalStateStore {
     await this.write(state);
     return state;
   }
+
+  async readAgentSetupPromptDismissedAt(): Promise<string | null> {
+    const state = await this.read();
+    return state.agent.setupPromptDismissedAt;
+  }
+
+  async setAgentSetupPromptDismissedAt(
+    dismissedAt: string,
+  ): Promise<LocalState> {
+    const state = await this.read();
+    state.agent.setupPromptDismissedAt = dismissedAt;
+    await this.write(state);
+    return state;
+  }
 }

packages/cli/src/cli.ts

@@ -2,6 +2,7 @@ import process from "node:process";
 
 import { Command, CommanderError, Option } from "commander";
 
+import { createAgentCommand } from "./commands/agent";
 import { createAppCommand } from "./commands/app";
 import { createAuthCommand } from "./commands/auth";
 import { createBranchCommand } from "./commands/branch";
@@ -81,6 +82,7 @@ export function createProgram(runtime: CliRuntime): Command {
   program.name("prisma").showSuggestionAfterError();
 
   program.addCommand(createVersionCommand(runtime));
+  program.addCommand(createAgentCommand(runtime));
   program.addCommand(createAuthCommand(runtime));
   program.addCommand(createProjectCommand(runtime));
   program.addCommand(createGitCommand(runtime));

packages/cli/src/commands/agent/index.ts

@@ -0,0 +1,162 @@
+import { Command, Option } from "commander";
+
+import {
+  type AgentInstallOptions,
+  runAgentInstall,
+  runAgentStatus,
+} from "../../controllers/agent";
+import {
+  renderAgentInstall,
+  renderAgentStatus,
+  serializeAgentInstall,
+  serializeAgentStatus,
+} from "../../presenters/agent";
+import { attachCommandDescriptor } from "../../shell/command-meta";
+import { runCommand } from "../../shell/command-runner";
+import {
+  addCompactGlobalFlags,
+  addGlobalFlags,
+} from "../../shell/global-flags";
+import { type CliRuntime, configureRuntimeCommand } from "../../shell/runtime";
+import type { AgentInstallResult, AgentStatusResult } from "../../types/agent";
+
+export function createAgentCommand(runtime: CliRuntime): Command {
+  const command = attachCommandDescriptor(
+    configureRuntimeCommand(new Command("agent"), runtime),
+    "agent",
+  );
+
+  addCompactGlobalFlags(command);
+
+  command.addCommand(createAgentInstallCommand(runtime));
+  command.addCommand(createAgentUpdateCommand(runtime));
+  command.addCommand(createAgentStatusCommand(runtime));
+
+  return command;
+}
+
+function createAgentInstallCommand(runtime: CliRuntime): Command {
+  const command = attachCommandDescriptor(
+    configureRuntimeCommand(new Command("install"), runtime),
+    "agent.install",
+  );
+
+  addAgentInstallOptions(command);
+
+  addGlobalFlags(command);
+
+  command.action(async (options) => {
+    await runCommand<AgentInstallResult>(
+      runtime,
+      "agent.install",
+      options as Record<string, unknown>,
+      (context) =>
+        runAgentInstall(context, options as AgentInstallOptions, "install"),
+      {
+        renderHuman: (context, descriptor, result) =>
+          renderAgentInstall(context, descriptor, result),
+        renderJson: (result) => serializeAgentInstall(result),
+      },
+    );
+  });
+
+  return command;
+}
+
+function createAgentUpdateCommand(runtime: CliRuntime): Command {
+  const command = attachCommandDescriptor(
+    configureRuntimeCommand(new Command("update"), runtime),
+    "agent.update",
+  );
+
+  addAgentInstallOptions(command);
+  addGlobalFlags(command);
+
+  command.action(async (options) => {
+    await runCommand<AgentInstallResult>(
+      runtime,
+      "agent.update",
+      options as Record<string, unknown>,
+      (context) =>
+        runAgentInstall(context, options as AgentInstallOptions, "update"),
+      {
+        renderHuman: (context, descriptor, result) =>
+          renderAgentInstall(context, descriptor, result),
+        renderJson: (result) => serializeAgentInstall(result),
+      },
+    );
+  });
+
+  return command;
+}
+
+function createAgentStatusCommand(runtime: CliRuntime): Command {
+  const command = attachCommandDescriptor(
+    configureRuntimeCommand(new Command("status"), runtime),
+    "agent.status",
+  );
+
+  addGlobalFlags(command);
+
+  command.action(async (options) => {
+    await runCommand<AgentStatusResult>(
+      runtime,
+      "agent.status",
+      options as Record<string, unknown>,
+      (context) => runAgentStatus(context),
+      {
+        renderHuman: (context, descriptor, result) =>
+          renderAgentStatus(context, descriptor, result),
+        renderJson: (result) => serializeAgentStatus(result),
+      },
+    );
+  });
+
+  return command;
+}
+
+function addAgentInstallOptions(command: Command): void {
+  command
+    .addOption(
+      new Option(
+        "--agent <agent>",
+        "Agent target for Prisma skills; repeat for multiple agents",
+      ).argParser(collectValues),
+    )
+    .addOption(
+      new Option(
+        "--all-agents",
+        "Install Prisma skills for every agent supported by the skills CLI",
+      ),
+    )
+    .addOption(
+      new Option(
+        "--skill <skill>",
+        "Prisma skill to install; repeat for multiple skills",
+      ).argParser(collectValues),
+    )
+    .addOption(
+      new Option(
+        "--global",
+        "Install skills into the user directory instead of the project",
+      ),
+    )
+    .addOption(
+      new Option(
+        "--copy",
+        "Ask the skills CLI to copy files instead of symlinking them",
+      ),
+    )
+    .addOption(new Option("--skip-skills", "Only write project agent files"))
+    .addOption(
+      new Option(
+        "--skip-project-files",
+        "Only install Prisma skills, without touching AGENTS.md or CLAUDE.md",
+      ),
+    )
+    .addOption(new Option("--dry-run", "Show changes without writing files"));
+}
+
+function collectValues(value: string, previous: string[] | undefined) {
+  return [...(previous ?? []), value];
+}