fix(cli): rewrite CLI command in installed skills

Skills still document `playwright-cli`, which is fine for GitHub
search, but when installed via `npx/yarn/pnpm playwright cli` the
examples need the package-manager form. Rewrite at install time and
leave skill name / allowed-tools / `.playwright-cli/` alone.

Fixes: #42135

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: f3c49995-a324-4711-b5b6-d4fe2f766e2d

Author: Skn0tt

packages/playwright-core/src/cli/program.ts

@@ -242,9 +242,9 @@ export function decorateProgram(program: Command) {
       .allowExcessArguments(true)
       .allowUnknownOption(true)
       .helpOption(false)
-      .action(async options => {
+      .action(async () => {
         process.argv.splice(process.argv.indexOf('cli'), 1);
-        cliProgram().catch(logErrorAndExit);
+        cliProgram({ cliCommand: `${getPackageManagerExecCommand()} playwright cli` }).catch(logErrorAndExit);
       });
 
   decorateMCPCommand(program

packages/playwright-core/src/tools/cli-client/program.ts

@@ -74,9 +74,10 @@ const booleanOptions: (keyof (GlobalOptions & OpenOptions & AttachOptions & { al
   'version',
 ];
 
-export async function program(options?: { embedderVersion?: string}) {
+export async function program(options?: { embedderVersion?: string, cliCommand?: string }) {
   const clientInfo = createClientInfo();
   const help = require(libPath('tools', 'cli-client', 'help.json'));
+  const cliCommand = options?.cliCommand || 'playwright-cli';
 
   const argv = process.argv.slice(2);
   const boolean = [...help.booleanOptions, ...booleanOptions];
@@ -204,7 +205,7 @@ export async function program(options?: { embedderVersion?: string}) {
     case 'install':
       if (args.global && !args.skills)
         output.errorInstallGlobalRequiresSkills();
-      await runInitWorkspace(args, output);
+      await runInitWorkspace(args, output, cliCommand);
       output.installed();
       return;
     case 'install-browser':
@@ -321,12 +322,13 @@ async function runInSessionOrStop(entry: SessionFile, clientInfo: ClientInfo, ar
   }
 }
 
-async function runInitWorkspace(args: MinimistArgs, output: Output) {
+async function runInitWorkspace(args: MinimistArgs, output: Output, cliCommand: string) {
   const cliPath = libPath('entry', 'cliDaemon.js');
   const daemonArgs: string[] = [
     cliPath,
     '--init-workspace',
     ...(args.skills ? [args.global ? '--init-skills-global' : '--init-skills', String(args.skills)] : []),
+    ...(args.skills ? ['--cli-command', cliCommand] : []),
   ];
   await new Promise<void>((resolve, reject) => {
     const child = spawn(process.execPath, daemonArgs, {

packages/playwright-core/src/tools/cli-daemon/DEPS.list

@@ -8,4 +8,5 @@
 @utils/**
 ../../server/registry/index.ts
 @utils/**
+node_modules/commander
 node_modules/zod

packages/playwright-core/src/tools/cli-daemon/program.ts

@@ -20,6 +20,7 @@ import fs from 'fs';
 import os from 'os';
 import path from 'path';
 
+import { Option } from 'commander';
 import { getAsBooleanFromENV, guessClientName } from '@utils/env';
 import { gracefullyProcessExitDoNotHang } from '@utils/processLauncher';
 import { startCliDaemonServer } from './daemon';
@@ -29,6 +30,7 @@ import * as configUtils from '../mcp/config';
 import { createClientInfo } from '../cli-client/registry';
 import { installSkills } from '../utils/installSkills';
 import { registry as browserRegistry } from '../../server/registry/index';
+
 import type { Command } from 'commander';
 
 export function decorateProgram(program: Command) {
@@ -46,10 +48,11 @@ export function decorateProgram(program: Command) {
       .option('--init-workspace', 'initialize workspace')
       .option('--init-skills <value>', 'install skills for the given agent type ("claude" or "agents")')
       .option('--init-skills-global <value>', 'install skills for the given agent type ("claude" or "agents") into the home directory')
+      .addOption(new Option('--cli-command <command>', 'command prefix to embed into installed skills').hideHelp())
 
       .action(async (sessionName: string, options: any) => {
         if (options.initWorkspace) {
-          await initWorkspace(options.initSkills, options.initSkillsGlobal);
+          await initWorkspace(options.initSkills, options.initSkillsGlobal, options.cliCommand);
           return;
         }
 
@@ -86,7 +89,7 @@ function globalConfigFile(): string {
   return path.join(process.env['PWTEST_CLI_GLOBAL_CONFIG'] ?? os.homedir(), '.playwright', 'cli.config.json');
 }
 
-export async function initWorkspace(initSkills: string | undefined, initSkillsGlobal?: string) {
+export async function initWorkspace(initSkills: string | undefined, initSkillsGlobal?: string, cliCommand?: string) {
   const globalSkills = !!initSkillsGlobal;
   if (!globalSkills) {
     const cwd = process.cwd();
@@ -99,7 +102,7 @@ export async function initWorkspace(initSkills: string | undefined, initSkillsGl
   if (skills) {
     const target = skills === 'agents' ? 'agents' : 'claude';
     try {
-      await installSkills(['playwright-cli'], target, { global: globalSkills });
+      await installSkills(['playwright-cli'], target, { global: globalSkills, cliCommand });
     } catch (error) {
       console.error('❌', error instanceof Error ? error.message : error);
       // eslint-disable-next-line no-restricted-properties

packages/playwright-core/src/tools/skills/playwright-cli/SKILL.md

@@ -340,20 +340,6 @@ playwright-cli close-all
 playwright-cli kill-all
 ```
 
-## Installation
-
-If global `playwright-cli` command is not available, try a local version via `npx playwright cli`:
-
-```bash
-npx --no-install playwright --version
-```
-
-When local version is available, use `npx playwright cli` in all commands. Otherwise, install `playwright-cli` as a global command:
-
-```bash
-npm install -g @playwright/cli@latest
-```
-
 ## Example: Form submission
 
 ```bash

packages/playwright-core/src/tools/utils/installSkills.ts

@@ -27,15 +27,49 @@ export const allSkills = ['playwright-cli', 'playwright-component-testing', 'pla
 export type SkillName = typeof allSkills[number];
 export type SkillTarget = 'claude' | 'agents';
 
-export async function installSkills(skills: readonly SkillName[], target: SkillTarget = 'claude', options?: { global?: boolean }) {
+// Source skill docs use this as the command. Kept literal so GitHub/search still
+// reads as a real CLI. At install time it is rewritten when the invoker differs
+// (e.g. `npx`/`yarn`/`pnpm exec` playwright cli), while skill identity and
+// artifact paths stay put.
+const sourceCliCommand = 'playwright-cli';
+
+export async function installSkills(skills: readonly SkillName[], target: SkillTarget = 'claude', options?: { global?: boolean, cliCommand?: string }) {
   const cwd = process.cwd();
   const baseDir = options?.global ? os.homedir() : cwd;
   for (const skill of skills) {
     const sourceDir = libPath('tools', 'skills', skill);
     if (!fs.existsSync(sourceDir))
       throw new Error(`Skill source directory not found: ${sourceDir}`);
     const destDir = path.join(baseDir, `.${target}`, 'skills', skill);
-    await fs.promises.cp(sourceDir, destDir, { recursive: true });
+    await copySkillDir(sourceDir, destDir, options?.cliCommand || sourceCliCommand);
     console.log(`✅ Skill installed to \`${options?.global ? destDir : path.relative(cwd, destDir)}\`.`);
   }
 }
+
+async function copySkillDir(sourceDir: string, destDir: string, cliCommand: string) {
+  await fs.promises.mkdir(destDir, { recursive: true });
+  const entries = await fs.promises.readdir(sourceDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const from = path.join(sourceDir, entry.name);
+    const to = path.join(destDir, entry.name);
+    if (entry.isDirectory()) {
+      await copySkillDir(from, to, cliCommand);
+      continue;
+    }
+    if (!entry.isFile())
+      continue;
+    const content = await fs.promises.readFile(from, 'utf8');
+    await fs.promises.writeFile(to, rewriteCliCommand(content, cliCommand));
+  }
+}
+
+function rewriteCliCommand(content: string, cliCommand: string): string {
+  // Must not contain `playwright-cli`, or the bulk replace below would rewrite it.
+  const protectedToken = '\0PWCLI\0';
+  return content
+      .replaceAll(`name: ${sourceCliCommand}`, `name: ${protectedToken}`)
+      .replaceAll(`Bash(${sourceCliCommand}:*)`, `Bash(${protectedToken}:*)`)
+      .replaceAll(`.${sourceCliCommand}/`, `.${protectedToken}/`)
+      .replaceAll(sourceCliCommand, cliCommand)
+      .replaceAll(protectedToken, sourceCliCommand);
+}

packages/playwright/src/program.ts

@@ -20,6 +20,7 @@ import 'playwright-core/lib/bootstrap';
 
 import { libCli, tools } from 'playwright-core/lib/coreBundle';
 import { program } from 'commander';
+import { getPackageManagerExecCommand } from '@utils/env';
 import { setBoxedStackPrefixes } from '@utils/stackTrace';
 import { gracefullyProcessExitDoNotHang } from '@utils/processLauncher';
 import { builtInReporters, config, configLoader } from './common';
@@ -193,7 +194,7 @@ function addInitSkillsCommand(program: Command) {
   command.addOption(option);
   command.action(async opts => {
     try {
-      await tools.installSkills(tools.allSkills, opts.loop);
+      await tools.installSkills(tools.allSkills, opts.loop, { cliCommand: `${getPackageManagerExecCommand()} playwright cli` });
     } catch (e) {
       console.error(e);
       gracefullyProcessExitDoNotHang(1);

tests/mcp/cli-misc.spec.ts

@@ -50,6 +50,16 @@ test('install workspace w/skills', async ({ cli }, testInfo) => {
   const referencesDir = testInfo.outputPath('.claude', 'skills', 'playwright-cli', 'references');
   const references = await fs.promises.readdir(referencesDir);
   expect(references.length).toBeGreaterThan(0);
+
+  const skill = await fs.promises.readFile(skillFile, 'utf8');
+  expect(skill).toContain('playwright-cli open');
+  expect(skill).not.toContain('npx playwright cli open');
+  expect(skill).toContain('name: playwright-cli');
+  expect(skill).toContain('.playwright-cli/');
+  expect(skill).toContain('Bash(playwright-cli:*)');
+
+  const sessionRef = await fs.promises.readFile(path.join(referencesDir, 'session-management.md'), 'utf8');
+  expect(sessionRef).toContain('playwright-cli list');
 });
 
 test('install workspace w/--skills=agents', async ({ cli }, testInfo) => {

tests/mcp/init-agents.spec.ts

@@ -130,6 +130,25 @@ test('init-skills installs all skills', async ({  }) => {
   for (const skill of ['playwright-cli', 'playwright-component-testing', 'playwright-trace'])
     expect(fs.existsSync(path.join(baseDir, '.claude', 'skills', skill, 'SKILL.md'))).toBe(true);
   expect(fs.existsSync(path.join(baseDir, '.claude', 'skills', 'playwright-cli', 'references', 'tracing.md'))).toBe(true);
+
+  const skill = fs.readFileSync(path.join(baseDir, '.claude', 'skills', 'playwright-cli', 'SKILL.md'), 'utf-8');
+  expect(skill).toContain('npx playwright cli open');
+  expect(skill).toContain('name: playwright-cli');
+  expect(skill).toContain('.playwright-cli/');
+  expect(skill).not.toMatch(/(^|\n)playwright-cli open\b/);
+});
+
+test('playwright cli install --skills templates npx playwright cli command', async ({  }) => {
+  const baseDir = await writeFiles({});
+
+  await spawnAsync('npx', ['playwright', 'cli', 'install', '--skills'], { cwd: baseDir, shell: true });
+
+  const skill = fs.readFileSync(path.join(baseDir, '.claude', 'skills', 'playwright-cli', 'SKILL.md'), 'utf-8');
+  expect(skill).toContain('npx playwright cli open');
+  expect(skill).toContain('name: playwright-cli');
+  expect(skill).toContain('.playwright-cli/');
+  expect(skill).toContain('Bash(playwright-cli:*)');
+  expect(skill).not.toMatch(/(^|\n)playwright-cli open\b/);
 });
 
 test('init-skills installs into .agents with --loop agents', async ({  }) => {