agents: add distill-page skill with tests

Author: paulirish

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "agents/skills/distill-page/turndown_tmp"]
+	path = agents/skills/distill-page/turndown_tmp
+	url = https://github.com/mixmark-io/turndown.git

agents/README.md

@@ -1,10 +1,10 @@
 # @paulirish/agents
 
-A collection of expert agent skills and command-line tools for Gemini and Claude.
+A collection of expert agent skills and CLIs.
 
 ## Installing Skills
 
-Skills can be installed directly into your agent environment (e.g., Gemini CLI, Claude) using the `skills` CLI:
+Skills can be installed directly into your coding agent using the vercel `skills` CLI:
 
 ```bash
 npx skills add paulirish/dotfiles/agents --skill <skill-name>

agents/package.json

@@ -18,7 +18,8 @@
   "dependencies": {
     "heap-snapshot-toolkit": "^1.1.3",
     "playwright": "^1.61.1",
-    "markpaste": "^0.0.6"
+    "markpaste": "^0.0.6",
+    "protobufjs": "^8.7.1"
   },
   "devDependencies": {
     "typescript": "^5.0.0"

agents/pnpm-lock.yaml

@@ -0,0 +1,36 @@
+---
+name: distill-page
+description: Extract distilled page content as Markdown using Chromium's on-device ML page content annotation.
+---
+
+# Page Distiller Skill
+
+This skill extracts high-quality, noise-free Markdown content from a webpage using Chromium's experimental, on-device Machine Learning model annotations (`Page.getAnnotatedPageContent`).
+
+Unlike generic HTML-to-Markdown parsers (e.g. Turndown) which rely on markup syntax heuristics, this approach uses Chromium's visual ML layout analysis. It automatically identifies semantic roles (such as `ARTICLE` and `MAIN`) and excludes sidebars, navigation elements, footers, and popups.
+
+## Usage
+
+```bash
+node agents/skills/distill-page/scripts/distill-page.ts [--markdown] <URL>
+```
+
+### Options:
+* `--markdown`: Output as distilled Markdown (recommended). Without this, it outputs the raw decoded protobuf JSON.
+* `--base64-stdin`: Instead of fetching via Playwright, decode a base64-encoded protobuf payload passed via stdin.
+
+### Examples:
+```bash
+# Get markdown representation of page
+node agents/skills/distill-page/scripts/distill-page.ts --markdown https://example.com
+
+# Get raw JSON structure of annotated layout tree
+node agents/skills/distill-page/scripts/distill-page.ts https://example.com
+```
+
+## Requirements
+* Launches a headful browser (`headless: false`) and requires Chromium feature flags:
+  * `--enable-dom-distiller`
+  * `--enable-features=OptimizationHints,PageContentAnnotation,OptimizationGuideModelDownloading`
+* Playwright must be installed.
+* ProtobufJS must be installed.

agents/skills/distill-page/SKILL.md

@@ -0,0 +1,237 @@
+import * as pb from './proto/common_quality_data_pbjs.js';
+
+function normalizeWhitespace(text: string): string {
+  return text.replace(/\s+/g, ' ').trim();
+}
+
+const {ContentAttributeType, TextSize, TableRowType, AnnotatedRole} = pb.optimization_guide.proto;
+const {
+  CONTENT_ATTRIBUTE_TEXT,
+  CONTENT_ATTRIBUTE_IMAGE,
+  CONTENT_ATTRIBUTE_ANCHOR,
+  CONTENT_ATTRIBUTE_ORDERED_LIST,
+  CONTENT_ATTRIBUTE_UNORDERED_LIST,
+  CONTENT_ATTRIBUTE_TABLE,
+  CONTENT_ATTRIBUTE_TABLE_ROW,
+  CONTENT_ATTRIBUTE_HEADING,
+  CONTENT_ATTRIBUTE_CONTAINER
+} = ContentAttributeType;
+type AnyNode = pb.optimization_guide.proto.IContentNode;
+type IAnnotatedPageContent = pb.optimization_guide.proto.IAnnotatedPageContent;
+
+export function decodeAnnotatedPageContent(base64String: string): IAnnotatedPageContent {
+  const buffer = Buffer.from(base64String, 'base64');
+  const message = pb.optimization_guide.proto.AnnotatedPageContent.decode(buffer);
+  return pb.optimization_guide.proto.AnnotatedPageContent.toObject(message, {
+    longs: String,
+
+    arrays: true,
+    objects: true,
+  });
+}
+
+function findNodeByRoles(node: AnyNode, roles: string[]): AnyNode | null {
+  const attrs = node.contentAttributes || {};
+  if (attrs.annotatedRoles) {
+    for (const r of roles) {
+      if (attrs.annotatedRoles.includes(r as any)) {
+        return node;
+      }
+    }
+  }
+
+  if (node.childrenNodes) {
+    for (const child of node.childrenNodes) {
+      const found = findNodeByRoles(child, roles);
+      if (found) return found;
+    }
+  }
+  return null;
+}
+
+function recursiveToMarkdown(node: AnyNode, state: {imageIndex: number, insideHeading?: boolean, currentUrl?: string | null}): string {
+  let md = '';
+  const attrs = node.contentAttributes || {};
+
+  if (attrs.attributeType === CONTENT_ATTRIBUTE_TEXT && attrs.textData) {
+    let text = attrs.textData.textContent || '';
+    text = text.trim();
+    if (text) {
+      if (attrs.textData.textStyle?.hasEmphasis && text !== '`') {
+        text = `**${text}**`;
+      }
+      if (attrs.textData.textStyle?.textSize) {
+        const size = attrs.textData.textStyle.textSize;
+        if (size === TextSize.TEXT_SIZE_XL || size === TextSize.TEXT_SIZE_L) {
+          if (!state.insideHeading) {
+            const prefix = size === TextSize.TEXT_SIZE_XL ? '##' : '###';
+            text = `\n\n${prefix} ${text}\n\n`;
+          }
+        }
+      }
+      md += text;
+      if (!text.endsWith('\n')) {
+        md += ' ';
+      }
+    }
+  } else if (attrs.attributeType === CONTENT_ATTRIBUTE_IMAGE && attrs.imageData) {
+    const caption = attrs.imageData.imageCaption || 'image';
+    if (attrs.imageData.url) {
+      md += `\n![${caption}](${attrs.imageData.url})\n`;
+    } else {
+      const ref = `image${String(state.imageIndex++).padStart(2, '0')}`;
+      md += `\n![${caption}][${ref}]\n`;
+    }
+  } else if (attrs.attributeType === CONTENT_ATTRIBUTE_ANCHOR && attrs.anchorData) {
+    const url = attrs.anchorData.url || '';
+    let resolvedUrl = url;
+    if (state.currentUrl && url.startsWith(state.currentUrl + '#')) {
+      resolvedUrl = url.substring(state.currentUrl.length);
+    }
+    let childText = '';
+    if (node.childrenNodes) {
+      for (const child of node.childrenNodes) {
+        childText += recursiveToMarkdown(child, state);
+      }
+    }
+    childText = childText.trim();
+    if (childText && resolvedUrl) {
+      md += `[${childText}](${resolvedUrl}) `; // we've processed children manually
+    }
+    return md;
+  } else if (
+    attrs.attributeType === CONTENT_ATTRIBUTE_ORDERED_LIST ||
+    attrs.attributeType === CONTENT_ATTRIBUTE_UNORDERED_LIST
+  ) {
+    let listMd = '\n\n';
+    const isOrdered = attrs.attributeType === CONTENT_ATTRIBUTE_ORDERED_LIST;
+    let index = 1;
+
+    if (node.childrenNodes) {
+      for (const item of node.childrenNodes) {
+        // Even if it isn't strictly CONTENT_ATTRIBUTE_LIST_ITEM, process it as a list child
+        let itemText = '';
+        if (item.childrenNodes) {
+          for (const content of item.childrenNodes) {
+            itemText += recursiveToMarkdown(content, state);
+          }
+        }
+        itemText = normalizeWhitespace(itemText);
+        if (itemText) {
+          const prefix = isOrdered ? `${index}. ` : '* ';
+          listMd += `${prefix}${itemText}\n`;
+          index++;
+        }
+      }
+    }
+    return listMd + '\n';
+  } else if (attrs.attributeType === CONTENT_ATTRIBUTE_TABLE) {
+    let tableMd = '\n\n';
+    let isFirstRow = true;
+    if (node.childrenNodes) {
+      for (const row of node.childrenNodes) {
+        const rowAttrs = row.contentAttributes || {};
+        if (rowAttrs.attributeType !== CONTENT_ATTRIBUTE_TABLE_ROW) continue;
+
+        let rowText = '|';
+        let sepText = '|';
+        if (row.childrenNodes) {
+          for (const cell of row.childrenNodes) {
+            let cellText = '';
+            if (cell.childrenNodes) {
+              for (const content of cell.childrenNodes) {
+                cellText += recursiveToMarkdown(content, state);
+              }
+            }
+            cellText = normalizeWhitespace(cellText);
+            rowText += ` ${cellText} |`;
+            sepText += `---|`;
+          }
+        }
+        tableMd += rowText + '\n';
+        if (isFirstRow || (rowAttrs.tableRowData && rowAttrs.tableRowData.type === TableRowType.TABLE_ROW_TYPE_HEADER)) {
+          if (isFirstRow) {
+            tableMd += sepText + '\n';
+          }
+        }
+        isFirstRow = false;
+      }
+    }
+    return tableMd + '\n';
+  } else if (attrs.attributeType === CONTENT_ATTRIBUTE_HEADING) {
+    let maxTextSize = TextSize.TEXT_SIZE_M_DEFAULT;
+    if (node.childrenNodes) {
+      for (const child of node.childrenNodes) {
+        if (child.contentAttributes?.textData?.textStyle?.textSize) {
+          const size = child.contentAttributes.textData.textStyle.textSize;
+          if (size > maxTextSize) {
+            maxTextSize = size;
+          }
+        }
+      }
+    }
+
+    let headingText = '';
+    if (node.childrenNodes) {
+      const oldInsideHeading = state.insideHeading;
+      state.insideHeading = true;
+      for (const child of node.childrenNodes) {
+        headingText += recursiveToMarkdown(child, state);
+      }
+      state.insideHeading = oldInsideHeading;
+    }
+    headingText = normalizeWhitespace(headingText);
+    if (headingText) {
+      let prefix = '## ';
+      if (maxTextSize === TextSize.TEXT_SIZE_L) {
+        prefix = '### ';
+      } else if (maxTextSize === TextSize.TEXT_SIZE_XL) {
+        prefix = '## ';
+      }
+      return `\n\n${prefix}${headingText}\n\n`;
+    }
+    return '';
+
+  }
+
+  if (
+    attrs.annotatedRoles &&
+    ((attrs.annotatedRoles || []).includes(AnnotatedRole.ANNOTATED_ROLE_NAV) || (attrs.annotatedRoles || []).includes(AnnotatedRole.ANNOTATED_ROLE_FOOTER))
+  ) {
+    return ''; // Skip rendering kids of nav/footer
+  }
+
+  if (node.childrenNodes) {
+    for (const child of node.childrenNodes) {
+      md += recursiveToMarkdown(child, state);
+    }
+  }
+
+  if (attrs.attributeType === CONTENT_ATTRIBUTE_CONTAINER) {
+    md += '\n\n';
+  }
+
+  return md;
+}
+
+export function convertToMarkdown(decodedProto: IAnnotatedPageContent): string {
+  const root = decodedProto.rootNode;
+  if (!root) return '';
+
+  // Try to find the narrowest main content area to avoid outer shells
+  const contentRoot =
+    findNodeByRoles(root, [AnnotatedRole.ANNOTATED_ROLE_ARTICLE as unknown as string, AnnotatedRole.ANNOTATED_ROLE_MAIN as unknown as string]) || root;
+
+  let rawMd = recursiveToMarkdown(contentRoot, {imageIndex: 1, currentUrl: decodedProto.mainFrameData?.url});
+
+  // Clean up formatting
+  rawMd = rawMd
+    .replace(/\n{3,}/g, '\n\n')
+    .replace(/ \n/g, '\n')
+    .replace(/ +([.,!?;:)])/g, '$1')
+    .replace(/`\s+/g, '`')
+    .replace(/\s+`/g, '`')
+    .replace(/^\s+|\s+$/g, '');
+
+  return rawMd;
+}