Skip to content

Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.

feat(cli): add -g flag to install skills globally (#42099)

Pavel Feldman19630696cbe0
diff --git a/docs/src/getting-started-cli.md b/docs/src/getting-started-cli.md
index e577933724..6c99fccbe5 100644
--- a/docs/src/getting-started-cli.md
+++ b/docs/src/getting-started-cli.md
@@ -42,6 +42,12 @@ Coding agents like Claude Code and GitHub Copilot can use locally installed skil
playwright-cli install --skills
```
+To share the skills across all your projects, add the `-g` flag to install them into your home directory (`~/.claude/skills` or, with `--skills=agents`, `~/.agents/skills`):
+
+```bash
+playwright-cli install --skills -g
+```
+
### Skills-less operation
You can also point your agent at the CLI directly and let it discover commands on its own:
diff --git a/packages/playwright-core/src/tools/cli-client/output.ts b/packages/playwright-core/src/tools/cli-client/output.ts
index 1972f1862a..7dc38f04b5 100644
--- a/packages/playwright-core/src/tools/cli-client/output.ts
+++ b/packages/playwright-core/src/tools/cli-client/output.ts
@@ -57,6 +57,7 @@ export interface Output {
errorDetachNotAttached(session: string): never;
errorBrowserNotOpenForTool(session: string): never;
errorAttachNoTarget(): never;
+ errorInstallGlobalRequiresSkills(): never;
list(data: ListData): void;
closeAll(sessions: string[]): void;
@@ -126,6 +127,11 @@ export class TextOutput implements Output {
return process.exit(1);
}
+ errorInstallGlobalRequiresSkills(): never {
+ console.error(`Error: --global requires --skills`);
+ return process.exit(1);
+ }
+
list({ all, browsers, servers, channelSessions }: ListData): void {
const byWorkspace = new Map<string, ListedBrowser[]>();
for (const browser of browsers) {
@@ -307,6 +313,11 @@ export class JsonOutput implements Output {
return process.exit(1);
}
+ errorInstallGlobalRequiresSkills(): never {
+ this._emit({ isError: true, error: `--global requires --skills` });
+ return process.exit(1);
+ }
+
list({ all, browsers, servers, channelSessions }: ListData): void {
const payload: Record<string, unknown> = { browsers };
if (all) {
diff --git a/packages/playwright-core/src/tools/cli-client/program.ts b/packages/playwright-core/src/tools/cli-client/program.ts
index 6a087c48c1..ef0e82a34f 100644
--- a/packages/playwright-core/src/tools/cli-client/program.ts
+++ b/packages/playwright-core/src/tools/cli-client/program.ts
@@ -65,8 +65,9 @@ const globalOptions: (keyof (GlobalOptions & OpenOptions & AttachOptions))[] = [
'session',
];
-const booleanOptions: (keyof (GlobalOptions & OpenOptions & AttachOptions & { all?: boolean }))[] = [
+const booleanOptions: (keyof (GlobalOptions & OpenOptions & AttachOptions & { all?: boolean, g?: boolean }))[] = [
'all',
+ 'g',
'help',
'json',
'raw',
@@ -85,6 +86,11 @@ export async function program(options?: { embedderVersion?: string}) {
args.session = args.s;
delete args.s;
}
+ // Normalize -g alias to --global
+ if (args.g) {
+ args.global = true;
+ delete args.g;
+ }
const output: Output = args.json ? new JsonOutput() : new TextOutput();
const commandName = args._?.[0];
@@ -196,6 +202,8 @@ export async function program(options?: { embedderVersion?: string}) {
return;
}
case 'install':
+ if (args.global && !args.skills)
+ output.errorInstallGlobalRequiresSkills();
await runInitWorkspace(args, output);
output.installed();
return;
@@ -315,7 +323,11 @@ async function runInSessionOrStop(entry: SessionFile, clientInfo: ClientInfo, ar
async function runInitWorkspace(args: MinimistArgs, output: Output) {
const cliPath = libPath('entry', 'cliDaemon.js');
- const daemonArgs: string[] = [cliPath, '--init-workspace', ...(args.skills ? ['--init-skills', String(args.skills)] : [])];
+ const daemonArgs: string[] = [
+ cliPath,
+ '--init-workspace',
+ ...(args.skills ? [args.global ? '--init-skills-global' : '--init-skills', String(args.skills)] : []),
+ ];
await new Promise<void>((resolve, reject) => {
const child = spawn(process.execPath, daemonArgs, {
stdio: output.installStdio(),
diff --git a/packages/playwright-core/src/tools/cli-daemon/commands.ts b/packages/playwright-core/src/tools/cli-daemon/commands.ts
index 53cd564285..f1312ee5f9 100644
--- a/packages/playwright-core/src/tools/cli-daemon/commands.ts
+++ b/packages/playwright-core/src/tools/cli-daemon/commands.ts
@@ -1114,6 +1114,7 @@ const install = declareCommand({
args: z.object({}),
options: z.object({
skills: z.string().optional().describe('Install skills, possible values: claude (default), agents.'),
+ global: z.boolean().optional().describe('Install skills into the home directory instead of the workspace (alias: -g). Requires --skills.'),
}),
toolName: '',
toolParams: () => ({}),
diff --git a/packages/playwright-core/src/tools/cli-daemon/program.ts b/packages/playwright-core/src/tools/cli-daemon/program.ts
index b57ce32118..07c216829a 100644
--- a/packages/playwright-core/src/tools/cli-daemon/program.ts
+++ b/packages/playwright-core/src/tools/cli-daemon/program.ts
@@ -45,10 +45,11 @@ export function decorateProgram(program: Command) {
.option('--endpoint <endpoint>', 'attach to a running Playwright browser endpoint')
.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')
.action(async (sessionName: string, options: any) => {
if (options.initWorkspace) {
- await initWorkspace(options.initSkills);
+ await initWorkspace(options.initSkills, options.initSkillsGlobal);
return;
}
@@ -85,16 +86,20 @@ 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) {
- const cwd = process.cwd();
- const playwrightDir = path.join(cwd, '.playwright');
- await fs.promises.mkdir(playwrightDir, { recursive: true });
- console.log(`✅ Workspace initialized at \`${cwd}\`.`);
+export async function initWorkspace(initSkills: string | undefined, initSkillsGlobal?: string) {
+ const globalSkills = !!initSkillsGlobal;
+ if (!globalSkills) {
+ const cwd = process.cwd();
+ const playwrightDir = path.join(cwd, '.playwright');
+ await fs.promises.mkdir(playwrightDir, { recursive: true });
+ console.log(`✅ Workspace initialized at \`${cwd}\`.`);
+ }
- if (initSkills) {
- const target = initSkills === 'agents' ? 'agents' : 'claude';
+ const skills = initSkillsGlobal ?? initSkills;
+ if (skills) {
+ const target = skills === 'agents' ? 'agents' : 'claude';
try {
- await installSkills(['playwright-cli'], target);
+ await installSkills(['playwright-cli'], target, { global: globalSkills });
} catch (error) {
console.error('❌', error instanceof Error ? error.message : error);
// eslint-disable-next-line no-restricted-properties
@@ -102,7 +107,8 @@ export async function initWorkspace(initSkills: string | undefined) {
}
}
- await ensureConfiguredBrowserInstalled();
+ if (!globalSkills)
+ await ensureConfiguredBrowserInstalled();
}
async function ensureConfiguredBrowserInstalled() {
diff --git a/packages/playwright-core/src/tools/utils/installSkills.ts b/packages/playwright-core/src/tools/utils/installSkills.ts
index 43d4978a69..4bcea607c2 100644
--- a/packages/playwright-core/src/tools/utils/installSkills.ts
+++ b/packages/playwright-core/src/tools/utils/installSkills.ts
@@ -17,6 +17,7 @@
/* eslint-disable no-console */
import fs from 'fs';
+import os from 'os';
import path from 'path';
import { libPath } from '../../package';
@@ -26,14 +27,15 @@ 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') {
+export async function installSkills(skills: readonly SkillName[], target: SkillTarget = 'claude', options?: { global?: boolean }) {
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(cwd, `.${target}`, 'skills', skill);
+ const destDir = path.join(baseDir, `.${target}`, 'skills', skill);
await fs.promises.cp(sourceDir, destDir, { recursive: true });
- console.log(`✅ Skill installed to \`${path.relative(cwd, destDir)}\`.`);
+ console.log(`✅ Skill installed to \`${options?.global ? destDir : path.relative(cwd, destDir)}\`.`);
}
}
diff --git a/tests/mcp/cli-misc.spec.ts b/tests/mcp/cli-misc.spec.ts
index 67ba1e0040..750f34c1a5 100644
--- a/tests/mcp/cli-misc.spec.ts
+++ b/tests/mcp/cli-misc.spec.ts
@@ -60,6 +60,32 @@ test('install workspace w/--skills=agents', async ({ cli }, testInfo) => {
expect(fs.existsSync(skillFile)).toBe(true);
});
+test('install w/--skills -g installs into the home directory', async ({ cli }, testInfo) => {
+ const fakeHome = testInfo.outputPath('fake-home');
+ await fs.promises.mkdir(fakeHome, { recursive: true });
+ const { output } = await cli('install', '--skills', '-g', { env: { HOME: fakeHome, USERPROFILE: fakeHome } });
+ expect(output).toContain('Skill installed to');
+ expect(output).not.toContain('Workspace initialized');
+
+ const skillFile = path.join(fakeHome, '.claude', 'skills', 'playwright-cli', 'SKILL.md');
+ expect(fs.existsSync(skillFile)).toBe(true);
+});
+
+test('install w/--skills=agents --global installs into the home directory', async ({ cli }, testInfo) => {
+ const fakeHome = testInfo.outputPath('fake-home');
+ await fs.promises.mkdir(fakeHome, { recursive: true });
+ await cli('install', '--skills=agents', '--global', { env: { HOME: fakeHome, USERPROFILE: fakeHome } });
+
+ const skillFile = path.join(fakeHome, '.agents', 'skills', 'playwright-cli', 'SKILL.md');
+ expect(fs.existsSync(skillFile)).toBe(true);
+});
+
+test('install -g without --skills errors', async ({ cli }) => {
+ const result = await cli('install', '-g');
+ expect(result.exitCode).toBe(1);
+ expect(result.error).toContain('--global requires --skills');
+});
+
test('install handles browser detection', async ({ cli }) => {
const { output } = await cli('install');
// Verify that one of the browser detection outcomes occurred