feat: add a skill for detecting memory leaks using take_memory_snapshot tool (#1162)

This PR add a new skill for detecting and removing memory leaks using
take_memory_snapshot tool.

Skill was based on authoritative material from own sources:
* https://developer.chrome.com/docs/devtools/memory-problems
* https://web.dev/articles/effectivemanagement
as well as examples of memory leaks from public domain.

It can be tested with https://github.com/devnook/mem-leak-example.
Example prompt
* A page running at localhost:3000 has memory issues when you click from
home to contact tab and back. Can you fix it?

The skill prefers using comparison tools like memlab instead of custom
evaluate_script snippets to avoid directly reading of .heapsnpashot
files to save context space and tokens.

Fixes #1056

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: Yusheng <113574546+yshngg@users.noreply.github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Alex Rudenko <OrKoN@users.noreply.github.com>
Co-authored-by: Mathias Bynens <mathias@qiwi.be>

Author: 5 people

eslint.config.mjs

@@ -37,6 +37,7 @@ export default defineConfig([
             'puppeteer.config.cjs',
             'eslint.config.mjs',
             'rollup.config.mjs',
+            'skills/memory-leak-debugging/references/compare_snapshots.js',
           ],
         },
       },

skills/memory-leak-debugging/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: memory-leak-debugging
+description: Diagnoses and resolves memory leaks in JavaScript/Node.js applications. Use when a user reports high memory usage, OOM errors, or wants to analyze heapsnapshots or run memory leak detection tools like memlab.
+---
+
+# Memory Leak Debugging
+
+This skill provides expert guidance and workflows for finding, diagnosing, and fixing memory leaks in JavaScript and Node.js applications.
+
+## Core Principles
+
+- **Prefer `memlab`:** Do NOT attempt to read raw `.heapsnapshot` files directly, as they are extremely large and will consume too many tokens. Always recommend and use `memlab` to process snapshots and identify leak traces.
+- **Isolate the Leak:** Determine if the leak is in the browser (client-side) or Node.js (server-side).
+- **Common Culprits:** Look for detached DOM nodes, unhandled closures, global variables, event listeners not being removed, and caches growing unbounded. _Note: Detached DOM nodes are sometimes intentional caches; always ask the user before nulling them._
+
+## Workflows
+
+### 1. Capturing Snapshots
+
+When investigating a frontend web application memory leak, utilize the `chrome-devtools-mcp` tools to interact with the application and take snapshots.
+
+- Use tools like `click`, `navigate_page`, `fill`, etc., to manipulate the page into the desired state.
+- Revert the page back to the original state after interactions to see if memory is released.
+- Repeat the same user interactions 10 times to amplify the leak.
+- Use `take_memory_snapshot` to save `.heapsnapshot` files to disk at baseline, target (after actions), and final (after reverting actions) states.
+
+### 2. Using Memlab to Find Leaks (Recommended)
+
+Once you have generated `.heapsnapshot` files using `take_memory_snapshot`, use `memlab` to automatically find memory leaks.
+
+- Read [references/memlab.md](references/memlab.md) for how to use `memlab` to analyze the generated heapsnapshots.
+- Do **not** read raw `.heapsnapshot` files using `read_file` or `cat`.
+
+### 3. Identifying Common Leaks
+
+When you have found a leak trace (e.g., via `memlab` output), you must identify the root cause in the code.
+
+- Read [references/common-leaks.md](references/common-leaks.md) for examples of common memory leaks and how to fix them.
+
+### 4. Fallback: Comparing Snapshots Manually
+
+If `memlab` is not available, you MUST use the fallback script in the references directory to compare two `.heapsnapshot` files and identify the top growing objects and common leak types.
+
+Run the script using Node.js:
+
+```bash
+node compare_snapshots.js <baseline.heapsnapshot> <target.heapsnapshot>
+```
+
+The script will analyze and output the top growing objects by size and highlight the 3 most common types of memory leaks (e.g., Detached DOM nodes, closures, Contexts) if they are present.

skills/memory-leak-debugging/references/common-leaks.md

@@ -0,0 +1,33 @@
+# Common Memory Leaks
+
+When analyzing a retainer trace from `memlab`, look for these common patterns in the codebase:
+
+## 1. Uncleared Event Listeners
+
+Event listeners attached to global objects (like `window` or `document`) or long-living objects prevent garbage collection of the objects referenced in their callbacks.
+
+**Fix:** Always call `removeEventListener` when a component unmounts or the listener is no longer needed.
+
+## 2. Detached DOM Nodes
+
+A DOM node is removed from the document tree but is still referenced by a JavaScript variable. While detachedness is a good signal for a memory leak, it's not always a bug. For example, websites sometimes intentionally cache detached navigation trees.
+
+**Fix:** Signal the detached nodes to the user first. **Ask the user first** before nulling the references or changing the code, as the detached nodes might be part of an intentional cache. If confirmed as a leak, ensure variables holding DOM references are set to `null` when the node is removed, or limit their scope.
+
+## 3. Unintentional Global Variables
+
+Variables declared without `var`, `let`, or `const` (in non-strict mode) or explicitly attached to `window` remain in memory forever.
+
+**Fix:** Use strict mode, properly declare variables, and avoid global state.
+
+## 4. Closures
+
+Closures can unintentionally keep references to large objects in their outer scope.
+
+**Fix:** Nullify large objects when they are no longer needed, or refactor the closure to not capture unnecessary variables.
+
+## 5. Unbounded Caches or Arrays
+
+Data structures used for caching (like objects, Arrays, or Maps) that grow without limits.
+
+**Fix:** Implement caching limits, use LRU caches, or use `WeakMap`/`WeakSet` for data associated with object lifecycles.

skills/memory-leak-debugging/references/compare_snapshots.js

@@ -0,0 +1,109 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as fs from 'node:fs';
+
+function parseSnapshot(filePath) {
+  console.log(`Loading ${filePath}...`);
+  const data = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  const strings = data.strings;
+  const nodes = data.nodes;
+  const nodeFields = data.snapshot.meta.node_fields;
+  const nodeFieldCount = nodeFields.length;
+
+  const typeOffset = nodeFields.indexOf('type');
+  const nameOffset = nodeFields.indexOf('name');
+  const sizeOffset = nodeFields.indexOf('self_size');
+
+  const nodeTypes = data.snapshot.meta.node_types[typeOffset];
+
+  const counts = {};
+  const sizes = {};
+
+  for (let i = 0; i < nodes.length; i += nodeFieldCount) {
+    const typeIdx = nodes[i + typeOffset];
+    const typeName = nodeTypes[typeIdx];
+    const nameIdx = nodes[i + nameOffset];
+    const name = typeof nameIdx === 'number' ? strings[nameIdx] : nameIdx;
+    const size = nodes[i + sizeOffset];
+
+    // Ignore native primitives/arrays that clutter the output unless specifically looking for them
+    if (
+      typeName === 'string' ||
+      typeName === 'number' ||
+      typeName === 'array'
+    ) {
+      continue;
+    }
+
+    const key = `${typeName}::${name}`;
+    counts[key] = (counts[key] || 0) + 1;
+    sizes[key] = (sizes[key] || 0) + size;
+  }
+  return {counts, sizes};
+}
+
+const [, , file1, file2] = process.argv;
+if (!file1 || !file2) {
+  console.error(
+    'Usage: node compare_snapshots.js <baseline.heapsnapshot> <target.heapsnapshot>',
+  );
+  process.exit(1);
+}
+
+try {
+  const snap1 = parseSnapshot(file1);
+  const snap2 = parseSnapshot(file2);
+
+  const diffs = [];
+  for (const key in snap2.counts) {
+    const count1 = snap1.counts[key] || 0;
+    const count2 = snap2.counts[key];
+    const size1 = snap1.sizes[key] || 0;
+    const size2 = snap2.sizes[key];
+
+    if (count2 > count1) {
+      diffs.push({
+        key,
+        countDiff: count2 - count1,
+        sizeDiff: size2 - size1,
+      });
+    }
+  }
+
+  diffs.sort((a, b) => b.sizeDiff - a.sizeDiff);
+
+  console.log('\n--- Top 10 growing objects by size ---');
+  diffs.slice(0, 10).forEach(d => {
+    console.log(`${d.key}: +${d.countDiff} objects, +${d.sizeDiff} bytes`);
+  });
+
+  // Look for common leak indicators
+  const commonLeaks = diffs.filter(
+    d =>
+      d.key.toLowerCase().includes('detached') ||
+      d.key.toLowerCase().includes('html') ||
+      d.key.toLowerCase().includes('eventlistener') ||
+      d.key.toLowerCase().includes('context') ||
+      d.key.toLowerCase().includes('closure'),
+  );
+
+  commonLeaks.sort((a, b) => b.countDiff - a.countDiff);
+
+  console.log('\n--- Top 3 most common types of memory leaks found ---');
+  if (commonLeaks.length === 0) {
+    console.log('No common DOM or Closure leaks detected.');
+  } else {
+    commonLeaks.slice(0, 3).forEach(d => {
+      console.log(`${d.key}: +${d.countDiff} objects, +${d.sizeDiff} bytes`);
+    });
+  }
+} catch (error) {
+  console.error(
+    'Error parsing snapshots. They might be too large for JSON.parse or invalid.',
+  );
+  console.error(error.message);
+}

skills/memory-leak-debugging/references/memlab.md

@@ -0,0 +1,29 @@
+# Using Memlab
+
+[Memlab](https://facebook.github.io/memlab/) is an E2E testing and analysis framework for finding JavaScript memory leaks.
+
+## Important Rule
+
+**NEVER read raw `.heapsnapshot` files directly.** They are too large and will exceed context limits. Always use `memlab` commands to analyze them.
+
+## Analyzing Snapshots
+
+You can use the `take_memory_snapshot` tool provided by the `chrome-devtools-mcp` extension to generate heap snapshots during an investigation. To find leaks, you generally need 3 snapshots:
+
+1.  **Baseline:** Before the suspect action.
+2.  **Target:** After the suspect action.
+3.  **Final:** After reverting the suspect action (e.g., closing a modal, navigating away).
+
+Once you have these 3 snapshots saved to disk, you can use `memlab` to find leaks:
+
+```bash
+npx memlab find-leaks --baseline <path-to-baseline> --target <path-to-target> --final <path-to-final>
+```
+
+You can also parse a single snapshot to find the largest objects or explore it individually:
+
+```bash
+npx memlab analyze snapshot --snapshot <path-to-snapshot>
+```
+
+Memlab will output the retainer traces for identified leaks. Use these traces to guide your search in the codebase.