How to Build a Scheduled PageSpeed SEO Audit Skill With Hermes Agent

Read [THIS ARTICLE URL] and install the Hermes skill described there.

First inspect my local Hermes configuration and any project guidance. Tell me
the destination you will use. Create only:
~/.hermes/skills/pagespeed-seo-baseline/SKILL.md
~/.hermes/skills/pagespeed-seo-baseline/scripts/pagespeed_baseline.py

Copy the complete code blocks from the article. Do not invent a different
workflow. Verify the Python file with a syntax check and report the two paths.
Tell me how to configure PAGESPEED_API_KEY locally, but never ask me to paste
the value into this chat and never display it.

Do not run PageSpeed, schedule a task, write to my site repository, use CMS or
hosting credentials, edit a skill other than this one, or change a live site.
Stop after installation and verification.

export PAGESPEED_API_KEY="replace-with-your-key"

~/.hermes/skills/pagespeed-seo-baseline/
  SKILL.md
  scripts/
    pagespeed_baseline.py

---
name: pagespeed-seo-baseline
description: Create a read-only PageSpeed Insights baseline for one public URL, a supplied URL list, or a controlled XML sitemap sample. Save raw JSON and a dated report that distinguishes Lighthouse lab data from CrUX field data. Use for website speed, Core Web Vitals, Lighthouse, and recurring performance-baseline requests. Never edit a site, repository, CMS, hosting configuration, or deployment.
required_environment_variables:
  - PAGESPEED_API_KEY
---

# PageSpeed SEO Baseline

This is an evidence-collection skill. It may call the public PageSpeed Insights API and public sitemap URLs, then write only inside the report directory chosen by the operator.

## Boundaries

- Read `PAGESPEED_API_KEY` from the runtime environment only. Never print, message, save, or commit it.
- Do not use browser logins, SSH, CMS, hosting, Git write, deployment, or website-editing tools. A performance report is not approval to repair a site.
- Run both `mobile` and `desktop`. Preserve each successful response under `raw/` before summarizing it.
- Describe Lighthouse as a point-in-time lab measurement. Treat `loadingExperience` as page-level CrUX only when returned, and `originLoadingExperience` as origin-level CrUX only when returned. Do not substitute one for the other.
- For `--sitemap`, say how URLs were sampled and how many were excluded. For important templates, prefer `--urls-file`.
- Never create or change a schedule until a human has reviewed one successful manual report and named the recurring scope, cadence, report path, and delivery destination.

## Commands

Run from this skill directory. The output path must be outside a repository unless the operator explicitly chooses an ignored evidence directory.

    python3 scripts/pagespeed_baseline.py \
      --url "https://www.example.com/pricing/" \
      --out "$HOME/hermes-pagespeed-reports/pricing-baseline"

    python3 scripts/pagespeed_baseline.py \
      --sitemap "https://www.example.com/sitemap.xml" \
      --max-urls 12 \
      --out "$HOME/hermes-pagespeed-reports/site-sample"

## Required report handoff

Return the report path and a compact table: requested URL, final URL, device strategy, performance score, LCP, INP, CLS, TBT, and field-data scope. Name failed requests and skipped URLs. Group repeated opportunities by likely mechanism, but label every repair as a hypothesis until a developer verifies it.

When the operator asks for a schedule, show the proposed command, cadence, report retention rule, and delivery target. Wait for explicit confirmation before creating it. If running on a messaging surface, send the report path or attachment; never send the API key or raw command environment.

#!/usr/bin/env python3
"""Collect bounded PageSpeed Insights evidence without third-party packages."""
from __future__ import annotations

import argparse
import json
import os
import sys
import time
import urllib.error
import urllib.parse
import urllib.request
import xml.etree.ElementTree as ET
from collections import OrderedDict
from datetime import datetime, timezone
from pathlib import Path

API = "https://www.googleapis.com/pagespeedonline/v5/runPagespeed"
CATEGORIES = ("performance", "accessibility", "best-practices", "seo")
STRATEGIES = ("mobile", "desktop")
AUDITS = ("largest-contentful-paint", "interaction-to-next-paint", "cumulative-layout-shift", "total-blocking-time")


def get_bytes(url: str) -> bytes:
    request = urllib.request.Request(url, headers={"User-Agent": "Hermes-PageSpeed-Baseline/1.0"})
    with urllib.request.urlopen(request, timeout=45) as response:
        return response.read()


def sitemap_urls(url: str) -> list[str]:
    try:
        root = ET.fromstring(get_bytes(url))
    except (urllib.error.URLError, ET.ParseError) as error:
        raise RuntimeError(f"Could not read sitemap {url}: {error}") from error
    locs = [n.text.strip() for n in root.findall(".//{*}loc") if n.text and n.text.strip()]
    if root.tag.lower().endswith("sitemapindex"):
        locs = [item for child in locs for item in sitemap_urls(child)]
    return list(OrderedDict((u, None) for u in locs if urllib.parse.urlparse(u).scheme in {"http", "https"}))


def select_urls(urls: list[str], maximum: int) -> list[str]:
    groups: OrderedDict[str, list[str]] = OrderedDict()
    for url in urls:
        parts = [part for part in urllib.parse.urlparse(url).path.split("/") if part]
        groups.setdefault(parts[0] if parts else "root", []).append(url)
    chosen = [values[0] for values in groups.values()]
    chosen.extend(url for url in urls if url not in chosen)
    return chosen[:maximum]


def run_api(url: str, strategy: str, key: str) -> dict:
    params = [("url", url), ("strategy", strategy), ("key", key)]
    params.extend(("category", category) for category in CATEGORIES)
    endpoint = API + "?" + urllib.parse.urlencode(params)
    last_error = "unknown error"
    for attempt in range(3):
        try:
            request = urllib.request.Request(endpoint, headers={"User-Agent": "Hermes-PageSpeed-Baseline/1.0"})
            with urllib.request.urlopen(request, timeout=150) as response:
                return json.load(response)
        except urllib.error.HTTPError as error:
            last_error = f"HTTP {error.code}: {error.read().decode('utf-8', 'replace')[:240]}"
            if error.code not in {429, 500, 502, 503, 504}:
                break
        except (urllib.error.URLError, TimeoutError, json.JSONDecodeError) as error:
            last_error = str(error)
        time.sleep(2 ** attempt)
    raise RuntimeError(last_error)


def value(result: dict, audit_id: str) -> str:
    return result.get("lighthouseResult", {}).get("audits", {}).get(audit_id, {}).get("displayValue", "n/a")


def score(result: dict) -> str:
    raw = result.get("lighthouseResult", {}).get("categories", {}).get("performance", {}).get("score")
    return "n/a" if raw is None else str(round(raw * 100))


def field(result: dict, scope: str) -> str:
    metrics = result.get(scope, {}).get("metrics", {})
    names = ("LARGEST_CONTENTFUL_PAINT_MS", "INTERACTION_TO_NEXT_PAINT", "CUMULATIVE_LAYOUT_SHIFT_SCORE")
    return " / ".join(str(metrics.get(name, {}).get("percentile", "n/a")) for name in names) if metrics else "not returned"


def report(records: list[dict], scope: str, selected: int, total: int) -> str:
    lines = ["# Hermes PageSpeed baseline", "", f"- Generated (UTC): {datetime.now(timezone.utc).isoformat(timespec='seconds')}", f"- Scope: {scope}", f"- URLs selected: {selected} of {total}", "- Lighthouse is lab data. CrUX appears only when Google returned it.", "", "| URL | Final URL | Device | Perf | LCP | INP | CLS | TBT | Page CrUX (LCP / INP / CLS) | Origin CrUX (LCP / INP / CLS) | Status |", "| --- | --- | --- | ---: | --- | --- | --- | --- | --- | --- | --- |"]
    for item in records:
        if item["error"]:
            row = [item["url"], "n/a", item["strategy"], "n/a", "n/a", "n/a", "n/a", "n/a", "n/a", "n/a", item["error"]]
        else:
            data = item["result"]
            final_url = data.get("lighthouseResult", {}).get("finalUrl", item["url"])
            row = [item["url"], final_url, item["strategy"], score(data), *(value(data, name) for name in AUDITS), field(data, "loadingExperience"), field(data, "originLoadingExperience"), "ok"]
        lines.append("| " + " | ".join(str(cell).replace("|", "/") for cell in row) + " |")
    return "
".join(lines) + "
"


def main() -> int:
    parser = argparse.ArgumentParser()
    scope = parser.add_mutually_exclusive_group(required=True)
    scope.add_argument("--url")
    scope.add_argument("--urls-file")
    scope.add_argument("--sitemap")
    parser.add_argument("--max-urls", type=int, default=10)
    parser.add_argument("--out", required=True)
    args = parser.parse_args()
    key = os.environ.get("PAGESPEED_API_KEY")
    if not key:
        parser.error("PAGESPEED_API_KEY is not set in the environment")
    if args.url:
        urls, label = [args.url], "single URL"
        total = len(urls)
    elif args.urls_file:
        urls = [line.strip() for line in Path(args.urls_file).read_text(encoding="utf-8").splitlines() if line.strip() and not line.startswith("#")]
        label = "supplied URL list"
        total = len(urls)
    else:
        all_urls = sitemap_urls(args.sitemap)
        urls, label = select_urls(all_urls, args.max_urls), f"sitemap sample from {args.sitemap}"
        total = len(all_urls)
    out = Path(args.out)
    raw = out / "raw"
    raw.mkdir(parents=True, exist_ok=True)
    records = []
    for number, url in enumerate(urls, start=1):
        for strategy in STRATEGIES:
            try:
                result = run_api(url, strategy, key)
                (raw / f"{number:03d}-{strategy}.json").write_text(json.dumps(result, indent=2), encoding="utf-8")
                records.append({"url": url, "strategy": strategy, "result": result, "error": ""})
            except RuntimeError as error:
                records.append({"url": url, "strategy": strategy, "result": {}, "error": str(error)})
    (out / "report.md").write_text(report(records, label, len(urls), total), encoding="utf-8")
    (out / "summary.json").write_text(json.dumps({"scope": label, "urls": urls, "records": [{k: v for k, v in item.items() if k != "result"} for item in records]}, indent=2), encoding="utf-8")
    print(out / "report.md")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

mkdir -p "$HOME/hermes-pagespeed-reports"
cd ~/.hermes/skills/pagespeed-seo-baseline
python3 scripts/pagespeed_baseline.py \
  --url "https://www.example.com/" \
  --out "$HOME/hermes-pagespeed-reports/homepage-2026-07-24"

Create a proposed weekly PageSpeed baseline schedule, but do not activate it yet.

Use the exact manual scope and command from my approved report. Run in the same
isolated environment. Store each run beneath
$HOME/hermes-pagespeed-reports/weekly/YYYY-MM-DD/ and retain reports for 90
days. Deliver only report.md and summary.json to the approved owner channel.

Show the schedule, command, environment assumptions, report path, and failure
notification behavior. Do not include PAGESPEED_API_KEY in any output. Wait for
my explicit approval before writing or enabling the schedule.

Read this PageSpeed evidence folder: [REPORT PATH]. Create a repair brief only.
For each repeated or high-impact opportunity, state the affected URLs, the lab
or field evidence, a likely mechanism, the developer owner, expected benefit,
risk, test method, and rollback signal. Flag assumptions. Do not edit code,
content, configuration, or a deployment.

---
name: hermes-pagespeed-audit
description: Run a read-only PageSpeed Insights audit for one public URL, a supplied URL list, or a controlled sitemap sample, save raw JSON and a dated Markdown report that separates Lighthouse lab data from CrUX field data, and cover website speed, Core Web Vitals, Lighthouse, and recurring performance-baseline requests without ever editing a site, repository, CMS, hosting configuration, or deployment.
required_environment_variables:
  - PAGESPEED_API_KEY
---

# Hermes PageSpeed Audit

Audit public pages with the Google PageSpeed Insights API and return an evidence packet: one raw JSON file per run plus a dated Markdown report. The skill is read-only. It never edits a website, repository, CMS, or deployment, and it never creates a schedule without human approval.

## Step 1: Confirm the scope

Ask the operator for one of:

1. A single public URL.
2. A URL list, one URL per line in a text file.
3. A sitemap URL with a maximum sample (default 10 URLs).

Confirm the report directory. Default: `$HOME/hermes-pagespeed-reports/<page-or-site>-<YYYY-MM-DD>`.

## Step 2: Read the API key from the environment

The PageSpeed Insights API requires an API key. Read `PAGESPEED_API_KEY` from the runtime environment; the operator creates a restricted key in Google Cloud Console and sets this variable locally, and no real key value appears in this file or in chat. Never print, message, save, or commit the key.

## Step 3: Call the API for every URL and strategy

Run both `mobile` and `desktop` for each URL, requesting the performance, accessibility, best-practices, and seo categories. Example:

    curl -sS -G "https://www.googleapis.com/pagespeedonline/v5/runPagespeed" \
      --data-urlencode "url=<URL>" \
      --data-urlencode "strategy=mobile" \
      --data-urlencode "category=performance" \
      --data-urlencode "category=accessibility" \
      --data-urlencode "category=best-practices" \
      --data-urlencode "category=seo" \
      --data-urlencode "key=$PAGESPEED_API_KEY" \
      -o "<report-dir>/raw/<number>-<strategy>.json"

Save every successful response under `raw/` before summarizing it. Retry up to three times on HTTP 429 and 5xx with a short backoff. If a request still fails, record the error in the report and continue with the remaining URLs.

## Step 4: Write the dated report

Create `report.md` in the report directory with:

- Run timestamp in UTC and the scope description (single URL, supplied list, or sitemap sample with the number sampled and excluded).
- One table row per URL and strategy: requested URL, final URL, performance score, LCP, INP, CLS, TBT, page-level CrUX (LCP / INP / CLS), origin-level CrUX (LCP / INP / CLS), and status.
- Failed requests listed with their error.
- A scope note: Lighthouse is a point-in-time lab measurement; CrUX appears only when Google returned it.

Verify that every `raw/` file is non-empty JSON before writing the report. Also write `summary.json` with the scope, the tested URLs, and the per-record status, without embedding full API responses.

## Step 5: Report back

Return the report path and the compact table from Step 4. Label every repair suggestion as a hypothesis until a developer verifies it. If the operator asks for a schedule, show the proposed command, cadence, retention rule, and delivery target, and wait for explicit confirmation before creating the task.

## Boundaries

- Read the API key from the environment only. Never print, message, save, or commit it.
- Do not use browser logins, SSH, CMS, hosting, Git write, deployment, or website-editing tools. A performance report is not approval to repair a site.
- Do not create or change a schedule until a human has reviewed one successful manual report and named the recurring scope, cadence, report path, and delivery destination.

mkdir -p ~/.hermes/skills/seo/hermes-pagespeed-audit
hermes skills list

Run the PageSpeed audit skill on https://www.example.com/ and save the report under $HOME/hermes-pagespeed-reports/.

Follow this article and build the PageSpeed audit skill for me.