# On-Page Audit

Crawl a single page, extract its on-page SEO (search engine optimization) elements, and produce a written report of issues and fixes.

## When to use
- Before or after publishing a landing page, blog post, or pricing page to check SEO hygiene.
- When a stakeholder asks for an on-page SEO health check on a specific URL.
- When rankings drop or organic traffic dips and the page's fundamentals need review.
- As part of a periodic content-ops sweep across key pages.

## Tools
- `browser-navigate` — load the target page in a browser session so its rendered HTML is available for extraction.
- `browser-extract` — pull structured on-page elements from the loaded page: title tag, meta description, H1/H2 headings, image alt text, canonical tag, and internal/external link counts.
- `shell-execute` — run a small script to check element lengths (title, meta description), count missing alt attributes, and diff against SEO best-practice thresholds.
- `write-file` — save the finished audit report (issues found and recommended fixes) to a file.

## Playbook
1. Confirm the target URL and any known context (target keyword, page purpose) from the task or a human via `send-message` if unclear.
2. Load the page with `browser-navigate`.
3. Pull on-page elements with `browser-extract`: title tag, meta description, H1 and heading hierarchy, image alt attributes, canonical URL, and link structure.
4. Use `shell-execute` to run checks against the extracted data: title length (roughly 50-60 characters), meta description length (roughly 150-160 characters), presence of exactly one H1, missing alt text count, and canonical correctness.
5. Compile findings into an issues list, each with a concrete fix recommendation (e.g., "title is 82 characters, trim to under 60").
6. Note anything requiring a content or code change beyond this skill's scope — those are flagged, not applied.
7. Write the full report (elements extracted, issues, fixes, page URL, timestamp) to a file using `write-file`.
8. If any check cannot run because the page failed to load, retry once with `browser-navigate`, then fall back to `browser-search` to locate a working URL for the page.
9. Summarize the outcome and file location via `complete-task`.

## Failure modes
- 401/403 on any dependent SaaS lookup -> missing Integration; stop and ask a human via `send-message` to create it, naming the service and scopes.
- `browser-extract` returns empty or null elements -> verify the page fully loaded and the selectors match the current page structure before concluding data is missing.
- Rate limited by the browser tooling -> back off and retry with delay, and record the rate limit in memory via `update-memory` if it recurs.
- Page structure changed or URL redirects unexpectedly -> fall back to `browser-search` to relocate the correct page before extracting.

## Done when
- A report file exists (written via `write-file`) listing every on-page element extracted and every issue with its fix.
- Each flagged issue includes a specific, actionable recommendation rather than a vague note.
- Any change requiring PATCH/PUT/DELETE-level edits to the live page is explicitly called out as a human handoff, not applied.