chore(cli): make skill discoverable from --help (#40274)

.claude/skills/playwright-dev/dashboard.md

@@ -32,6 +32,6 @@ npx playwright cli video-stop
 # afterwards, use ffmpeg to turn the video into mp4 for sharing.
 ```
 
-For using Playwright CLI, refer to the `packages/playwright-core/src/tools/cli-client/skill/SKILL.md` skill.
+For more about using Playwright CLI, look at `npx playwright cli --help` and the referenced Skill.
 While developing in in this repo, it's important to use `npx playwright cli` instead of `playwright-cli`.
 

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

@@ -239,6 +239,7 @@ export function decorateProgram(program: Command) {
       .command('cli', { hidden: true })
       .allowExcessArguments(true)
       .allowUnknownOption(true)
+      .helpOption(false)
       .action(async options => {
         process.argv.splice(process.argv.indexOf('cli'), 1);
         cliProgram().catch(logErrorAndExit);

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

@@ -7,6 +7,7 @@
 ./output.ts
 ./session.ts
 ./registry.ts
+./utils.ts
 
 [output.ts]
 "strict"
@@ -30,3 +31,6 @@
 
 [minimist.ts]
 "strict"
+
+[utils.ts]
+"strict"

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

@@ -20,11 +20,13 @@ import { execSync, spawn } from 'child_process';
 
 import crypto from 'crypto';
 import os from 'os';
+import path from 'path';
 
 import { listChannelSessions } from './channelSessions';
 import { JsonOutput, TextOutput } from './output';
 import { clientKey, createClientInfo, explicitSessionName, Registry, resolveSessionName } from './registry';
 import { Session } from './session';
+import { isCodingAgent } from './utils';
 import { libPath } from '../../package';
 import { serverRegistry } from '../../serverRegistry';
 import { minimist } from './minimist';
@@ -92,8 +94,16 @@ export async function program(options?: { embedderVersion?: string}) {
   }
 
   const command = commandName && help.commands[commandName];
-  if (args.help || args.h) {
-    output.help(command ? command.help : 'playwright-cli - run playwright mcp commands from terminal\n\n' + help.global);
+  if (args.help || args.h || !commandName) {
+    if (command) {
+      output.help(command.help);
+    } else {
+      const lines = ['playwright-cli - run playwright mcp commands from terminal'];
+      if (isCodingAgent())
+        lines.push(`Agent skill: ${path.relative(process.cwd(), libPath('tools', 'cli-client', 'skill', 'SKILL.md'))}`);
+      lines.push(help.global);
+      output.help(lines.join('\n\n'));
+    }
     process.exit(0);
   }
 

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

@@ -0,0 +1,27 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export function guessClientName(): string {
+  if (process.env.CLAUDECODE)
+    return 'Claude Code';
+  if (process.env.COPILOT_CLI)
+    return 'GitHub Copilot';
+  return 'playwright-cli';
+}
+
+export function isCodingAgent(): boolean {
+  return !!process.env.CLAUDECODE || !!process.env.COPILOT_CLI;
+}

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

@@ -2,6 +2,7 @@
 ../../package.ts
 ../utils/socketConnection.ts
 ../cli-client/registry.ts
+../cli-client/utils.ts
 ../backend/
 ../mcp/
 @utils/**

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

@@ -27,6 +27,7 @@ import { setupExitWatchdog } from '../mcp/watchdog';
 import { createBrowserWithInfo } from '../mcp/browserFactory';
 import * as configUtils from '../mcp/config';
 import { createClientInfo } from '../cli-client/registry';
+import { guessClientName } from '../cli-client/utils';
 import { registry as browserRegistry } from '../../server/registry/index';
 import type { Command } from 'commander';
 
@@ -80,14 +81,6 @@ export function decorateProgram(program: Command) {
       });
 }
 
-function guessClientName(): string {
-  if (process.env.CLAUDECODE)
-    return 'Claude Code';
-  if (process.env.COPILOT_CLI)
-    return 'GitHub Copilot';
-  return 'playwright-cli';
-}
-
 function defaultConfigFile(): string {
   return path.resolve('.playwright', 'cli.config.json');
 }

tests/mcp/cli-help.spec.ts

@@ -16,12 +16,22 @@
 
 import { test, expect } from './cli-fixtures';
 
-test('prints help by default', async ({ cli }) => {
+test('prints help', async ({ cli }) => {
   const { output } = await cli('--help');
   expect(output).toContain('Usage: playwright-cli <command>');
 });
 
+test('prints help by default', async ({ cli }) => {
+  const { output } = await cli();
+  expect(output).toContain('Usage: playwright-cli <command>');
+});
+
 test('prints command help', async ({ cli }) => {
   const { output } = await cli('click', '--help');
   expect(output).toContain('playwright-cli click <target> [button]');
 });
+
+test('prints agent skill path when running under a coding agent', async ({ cli }) => {
+  const { output } = await cli('--help', { env: { CLAUDECODE: '1' } });
+  expect(output).toContain('Agent skill:');
+});