On Page Optimizer

---
# GENERATED from SKILL.md.tmpl — edit the .tmpl, then run scripts/build.sh.
name: on-page-optimizer
version: 0.5.0
publisher: localoy
capabilities: [files, web]
author: localoy
license: MIT
platforms: [linux, macos, windows]
metadata:
  hermes:
    tags: [seo, on-page, localstack]
    related_skills: [seo-audit, keyword-research]
description: >-
  Rewrites one page against one target term: title, meta description,
  headings, body copy and internal links, with the current and proposed values
  side by side. Use when asked to "fix this page", "optimise this post",
  "improve this page for <term>", or "write the title and meta for this URL".
  (localstack)
allowed-tools:
  - Bash
  - Read
  - Write
  - WebFetch
  - WebSearch
  - AskUserQuestion
triggers:
  - fix this page
  - optimise this post
  - improve this page
  - write the title and meta for this url
---
# On-page optimizer

Rewrite one page so it is unmistakably about one thing, and show the current and
proposed values side by side so a human can approve each change.

## What you need first

- **Page url** — this skill rewrites one specific page and cannot start from a description of it
- **Target term** — optimising without a target produces generic copy that competes with the site's other pages

Check what you already know from this workspace and the conversation. Ask for everything still missing in a SINGLE message, then wait.

If no answer comes, do not guess your way through. Produce whatever is genuinely useful without the missing facts, state at the top which ones you lacked, and say what would change once you have them.

**Earlier runs:** if `onpage-<slug>.md` already exists here (`<slug>` is the page's
host or path, lowercase, dots and slashes as hyphens — `acme-com`), say when it
was last written (its `Updated:` line) before you start. This run replaces it;
CHANGELOG.md and git keep the history.

## What you decide, and what you do not

**Decide yourself** — wording, heading structure and which internal links to add. Act; do not ask and do not flag.

**Decide and flag** — the target term when you had to infer it and any claim you kept but could not verify. Proceed on a named assumption and put it at the top of the output.

**Stop and wait** — publishing the changes and or editing the live page. Never resolve one of these by assumption, however long the wait.

## How you work

**Say only what you observed.** Every claim in the output traces to something you
actually read, fetched or were told. If you did not check it, do not assert it.

**Report what you could not do.** A page that would not load, a source you could
not reach, a step you skipped — these go in the output. Dropping them silently
turns partial work into work that looks complete, which is worse than work that
looks partial.

**Name your assumptions.** If you had to assume something to proceed, put it at
the top of what you produce, in one line. An assumption stated is corrected in
seconds; an assumption buried becomes a fact nobody checked.

**Finish or say you did not.** Do not pad to length, and do not present a first
pass as a final one.

## Before you start

Establish what you need before producing anything. A confident answer about a
business you have not described is the most expensive kind of wrong: it reads as
authoritative and nobody catches it until it is in front of a customer.

## Sources

**Cite what you used.** Name the URL, document or statement behind each finding,
inline, where the finding is. A sources list at the bottom that nothing points to
is decoration.

**Prefer what you fetched to what you recall.** When they disagree, the fetch
wins and you say so. When you could not fetch, say that instead of filling the
gap from memory.

**Do not launder a guess through a citation.** Linking a plausible source next to
an unverified claim is worse than the bare claim, because it borrows credibility
the claim did not earn.

## Procedure

1. **Fetch the page.** Always. A page you remember is not evidence, and a page
   that has changed since you last saw it makes every proposed edit wrong. If the
   fetch fails, stop and say so — there is no version of this skill that works
   without the current page.
2. **Record what is there now.** Title, meta description, H1, heading outline,
   word count, the internal links out, and the images with their alt text. Quote
   the values with their character counts. This is the left-hand column of
   everything that follows.
3. **Judge the fit.** Does the page as written serve someone searching the target
   term? If the page is about something else, say so and stop — a rewrite that
   forces an unrelated page onto a term produces a page that serves nobody. That
   finding is worth more than the rewrite.
4. **Rewrite the title.** Under 60 characters, target term near the front, one
   concrete specific from the page itself. Never a specific the page does not
   support.
5. **Rewrite the meta description.** 140-155 characters, active voice, one thing
   that is actually on the page, a soft reason to click. Count the characters and
   show the count — a description over the limit is truncated in results, which
   makes the count part of the deliverable, not a formality.
6. **Fix the heading structure.** One H1 carrying the target term. H2s that
   describe what is actually in each section. Never rename a section to hold a
   keyword the section does not discuss.
7. **Propose the body edits.** Only where the page is genuinely unclear, missing
   an answer a searcher wants, or repeating itself. Quote the current sentence and
   the replacement. Do not raise keyword density — writing for it produces copy
   that reads as machine-made and helps nothing.
8. **Add the internal links.** Name real URLs on this site that you fetched or saw
   linked, with the anchor text to use and where in the page it goes.
9. **Write the report.** Save to `onpage-<slug>.md` at the top of the working folder, starting
   with `Updated: YYYY-MM-DD`. Summary table first —
   element, current, proposed, why — then the body edits, then anything you chose
   not to change and the reason.
   Then keep the standard files. Add `- [ ] apply the proposed edits to <URL> (onpage <slug>)` to TODOS.md.

**Standard files.** This folder is kept in files any agent already reads. Update them in place; never scatter output into new folders.
- **AGENTS.md** — create it if missing. localstack owns only the block between `<!-- localstack:start -->` and `<!-- localstack:end -->`; rewrite that block, never anything outside it. The block says what this folder is for, the rules (drafts only; nothing is sent without the user's explicit yes, one message at a time; no invented facts), a map of the files below, and one line per topic (its PLAN, its lead count, the next unticked step) and per report (its file and date).
- **CHANGELOG.md** — create it if missing (`# Changelog`). Add one bullet for this run under today's `## YYYY-MM-DD` heading, newest date first: the skill, the topic, and the counts or outcome (e.g. `- lead-search austin-dentists: 18 found, 3 skipped as already contacted`).
- **TODOS.md** — create it if missing (`# TODOs`). Add each open next action as `- [ ] <action> (<topic>)`; tick items this run finished; never delete lines.
- **DESIGN.md** — decisions meant to last (positioning, tone, channels to use or avoid). Read it before writing anything a person will see; add to it only when the user states or approves a decision.

## Quality bar

- Every proposed value sits beside the current one. A recommendation with no
  before is unreviewable.
- Character counts are given for the title and meta, and they are correct. Count
  them; do not estimate.
- No scores. No "SEO score", no readability grade, no keyword density percentage.
  None of them is measured here and each one invites a change that helps nobody.
- Nothing is proposed that the page cannot support. If the page has no specific
  worth putting in the title, the finding is that the page is thin — say it.
- Every internal link points at a URL you actually saw. An invented internal link
  is a broken link the moment it ships.
- The page is left untouched. This skill produces a proposal, not an edit.

## The output contract

These apply to the file you write, not just the reply you send.

- Never state a score, rating or grade you did not measure. Report the values you actually observed instead — they are more useful and they are true.
- Open with a summary table — a row per page, item or finding — so the shape of the result is readable before the detail.