From 49a66c8ae38db26d884bb406a4c311bb88f22959 Mon Sep 17 00:00:00 2001
From: mukunda katta <mukunda.vjcs6@gmail.com>
Date: Sat, 18 Apr 2026 01:06:17 -0700
Subject: [PATCH] docs: clarify CLI evaluate_script usage

---
 docs/cli.md                         | 18 ++++++++++++++++++
 skills/chrome-devtools-cli/SKILL.md | 19 +++++++++++++++++++
 2 files changed, 37 insertions(+)

diff --git a/docs/cli.md b/docs/cli.md
index c3025b3c0..ecfe380cb 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -70,6 +70,24 @@ chrome-devtools fill "input-uid-456" "search query"
 chrome-devtools lighthouse_audit --mode snapshot
 ```
 
+**Script evaluation:**
+
+```sh
+# The JavaScript function is the first positional argument.
+chrome-devtools evaluate_script '() => document.title'
+
+# Pass snapshot UIDs through --args instead of putting them in selectors.
+chrome-devtools evaluate_script '(el) => el.innerText' --args 1_4
+
+# For longer scripts, assign the function to a shell variable first.
+script='() => {
+  return [...document.querySelectorAll("time")].map(el => el.textContent?.trim()).filter(Boolean);
+}'
+chrome-devtools evaluate_script "$script"
+```
+
+Do not invent flags like `--expression` for `evaluate_script`. The CLI expects the function as a positional argument, and single quotes are usually the safest way to preserve JavaScript syntax in the shell.
+
 ## Output format
 
 By default, the CLI outputs a human-readable summary of the tool's result. For programmatic use, you can request raw JSON:
diff --git a/skills/chrome-devtools-cli/SKILL.md b/skills/chrome-devtools-cli/SKILL.md
index 2b251c69b..7215d5425 100644
--- a/skills/chrome-devtools-cli/SKILL.md
+++ b/skills/chrome-devtools-cli/SKILL.md
@@ -123,6 +123,25 @@ chrome-devtools take_snapshot # Take a text snapshot of the page from the a11y t
 chrome-devtools take_snapshot --verbose true --filePath "s.txt" # Take a verbose snapshot and save to file
 ```
 
+### `evaluate_script` quoting rules
+
+- Pass the JavaScript function as the first positional argument. Do not invent flags like `--expression`.
+- Prefer wrapping the whole function in single quotes in the shell so JavaScript parentheses and double quotes are preserved.
+- Keep the argument as a function expression such as `'() => document.title'` or `'(el) => el.innerText'`.
+- For complex scripts, write the function to a shell variable first and then pass the variable to `chrome-devtools evaluate_script`.
+
+Examples:
+
+```bash
+chrome-devtools evaluate_script '() => document.title'
+chrome-devtools evaluate_script '(el) => el.innerText' --args 1_4
+script='() => {
+  const dates = [...document.querySelectorAll("time")].map(el => el.textContent?.trim()).filter(Boolean);
+  return dates;
+}'
+chrome-devtools evaluate_script "$script"
+```
+
 ## Service Management
 
 ```bash