From 58dc932990228c8445b73c41ec15652dca82535c Mon Sep 17 00:00:00 2001
From: "Tommy D. Rossi" <beats.by.morse@gmail.com>
Date: Thu, 22 Jan 2026 19:31:15 +0100
Subject: [PATCH] Add CLI usage instructions to playwriter skill

---
 playwriter/scripts/build-resources.ts | 51 ++++++++++++++++++++++++++-
 skills/playwriter/SKILL.md            | 46 ++++++++++++++++++++++++
 2 files changed, 96 insertions(+), 1 deletion(-)

diff --git a/playwriter/scripts/build-resources.ts b/playwriter/scripts/build-resources.ts
index b13b443..16d3ab1 100644
--- a/playwriter/scripts/build-resources.ts
+++ b/playwriter/scripts/build-resources.ts
@@ -128,7 +128,56 @@ function buildSkill() {
     ---
   `
   
-  const content = frontmatter + '\n\n' + promptContent
+  const cliUsage = dedent`
+    ## CLI Usage
+
+    If \`playwriter\` command is not found, install globally or use npx/bunx:
+
+    \`\`\`bash
+    npm install -g playwriter
+    # or use without installing:
+    npx playwriter -e "..." -s 1
+    bunx playwriter -e "..." -s 1
+    \`\`\`
+
+    ### Execute code
+
+    \`\`\`bash
+    playwriter -e "<code>" -s <session>
+    \`\`\`
+
+    The \`-s\` flag specifies a session name (required). Use the same session to persist state across commands.
+
+    **Examples:**
+
+    \`\`\`bash
+    # Navigate to a page
+    playwriter -e "await page.goto('https://example.com')" -s 1
+
+    # Click a button
+    playwriter -e "await page.click('button')" -s 1
+
+    # Get page title
+    playwriter -e "console.log(await page.title())" -s 1
+
+    # Take a screenshot
+    playwriter -e "await page.screenshot({ path: 'screenshot.png', scale: 'css' })" -s 1
+
+    # Get accessibility snapshot
+    playwriter -e "console.log(await accessibilitySnapshot({ page }))" -s 1
+    \`\`\`
+
+    ### Reset connection
+
+    If the browser connection is stale or broken:
+
+    \`\`\`bash
+    playwriter reset -s <session>
+    \`\`\`
+
+  `
+  
+  const content = frontmatter + '\n\n' + cliUsage + '\n' + promptContent
   
   // Write to repo root skills/ folder for add-skill discovery
   const skillsDir = path.join(playwriterDir, '..', 'skills', 'playwriter')
diff --git a/skills/playwriter/SKILL.md b/skills/playwriter/SKILL.md
index 994b02d..346db81 100644
--- a/skills/playwriter/SKILL.md
+++ b/skills/playwriter/SKILL.md
@@ -3,6 +3,52 @@ name: playwriter
 description: Control Chrome browser via Playwright code snippets. Automate web interactions, take screenshots, inspect accessibility trees, and debug web applications.
 ---
 
+## CLI Usage
+
+If `playwriter` command is not found, install globally or use npx/bunx:
+
+```bash
+npm install -g playwriter
+# or use without installing:
+npx playwriter -e "..." -s 1
+bunx playwriter -e "..." -s 1
+```
+
+### Execute code
+
+```bash
+playwriter -e "<code>" -s <session>
+```
+
+The `-s` flag specifies a session name (required). Use the same session to persist state across commands.
+
+**Examples:**
+
+```bash
+# Navigate to a page
+playwriter -e "await page.goto('https://example.com')" -s 1
+
+# Click a button
+playwriter -e "await page.click('button')" -s 1
+
+# Get page title
+playwriter -e "console.log(await page.title())" -s 1
+
+# Take a screenshot
+playwriter -e "await page.screenshot({ path: 'screenshot.png', scale: 'css' })" -s 1
+
+# Get accessibility snapshot
+playwriter -e "console.log(await accessibilitySnapshot({ page }))" -s 1
+```
+
+### Reset connection
+
+If the browser connection is stale or broken:
+
+```bash
+playwriter reset -s <session>
+```
+
 # playwriter execute
 
 Control user's Chrome browser via playwright code snippets. Prefer single-line code with semicolons between statements. If you get "Extension not running" error, tell user to click the playwriter extension icon on the tab they want to control.