Skip to content

Checks

Refresh audit

Audits one published page against today's search results and standards, and returns a ranked list of the edits that matter, with the parts that work protected.

Other tools

Add this skill to Claude

Claude takes skills as a ZIP file. Your download has started; if it didn't, use the button below.

  1. 1In Claude, open Customize, then Skills.
  2. 2Choose +, then Upload a skill, and pick refresh-audit.zip.
  3. 3Ask for it by name, or let Claude use it when a task matches.

Skills need code execution turned on in Claude's settings. On a Team or Enterprise plan, an admin can share it with everyone.

Download the folder

Try it now, without installing

See the skill work on a made-up input before you add it. Nothing is installed, and you can swap in your own input.

Open in the Claude app

Opens a new chat in the Claude desktop app with the prompt filled in. Nothing is sent until you press enter.

Includes the whole SKILL.md and the sample input. Paste it into Claude, ChatGPT or any chat.

Influenced by
Creating helpful, people-first content, Optimizing for generative AI features
Needs
The page, with its text, title, links and dates
Works with
Claude, ChatGPT, Codex, Cursor and any agent that reads SKILL.md
Version
1.0.0 · Last checked · License MIT
Maintained by
Sabih AhmedOrganic visibility
SkillSEO and AI search

Refresh audit

Example output

Audit one page
FindingTierEdit
Broken linkCriticalPoint to live page
No pricing sectionImportantAdd a section
Customer storyProtectedLeave it

Audits one published page against today's search results and standards, and returns a ranked list of the edits that matter, with the parts that work protected.

The skill

The whole skill, in plain text.

Nothing is hidden. Read it, change it to fit your team, or take the whole folder.

Scripts
Optional Python scripts for the counting. It works without them and says which way it ran.
Network
Opens web pages or your tools if your agent can. Works from pasted data if not.

3 test cases

refresh-audit/SKILL.md

In the folder

  • refresh-audit/SKILL.md
  • refresh-audit/references/checks.md
  • refresh-audit/scripts/refresh_math.py
---name: refresh-auditdescription: >-  Audits one published B2B SaaS page against today's search results and today's standards (claims and sources,  coverage, format, answers near the top, voice, title and description, links, dates) and returns a ranked edit  list in 3 tiers with NO CHANGE, STANDARD REFRESH, SIGNIFICANT REFRESH, FULL REWRITE, CONSOLIDATE or BLOCKED. Use it  on a page content-triage marked for refresh, or any page someone wants to update. Not for choosing which pages to  refresh (use content-triage) or for rewriting the page (the edit list goes to the writer).license: MITcompatibility: >-  Works in Claude, ChatGPT, Codex, Cursor and any agent that reads SKILL.md. Reads the page and the live results if  the agent can browse, otherwise pasted text and outlines. Python 3 is optional, for the gap count and the date rule.metadata:  author: SHAKEUP  version: "1.0.0"  stage: check  plugin: seo-ai-search  homepage: https://www.shakeuphq.com/skills/refresh-audit--- # Refresh audit Turns "this page needs updating" into a short, ranked list of the edits that matter, and protects the parts of the page that already work. ## Purpose - One job: audit one published page and return a tiered edit list with a refresh verdict.- Stage: check. It ends in a verdict with severities on every finding.- A refresh is not a rewrite. Most pages need targeted edits; the audit calls for a rewrite only when the page serves the wrong intent.- It never edits the page, and never moves a page's "updated" date without a substantial change. ## Use when / not | Situation | Use || --- | --- || A page is in `content-triage`'s refresh bucket | this skill, on the priority refreshes first || A page's facts, tools or results have moved since it was written | this skill || Choosing which pages need work | `content-triage` || The page competes with another page on the site | `cannibalization-audit` first; consolidate before refreshing || Only the title and description lose clicks | `meta-serp-copy` alone is enough | ## Inputs | Input | Required | Ways to provide, in order | If missing || --- | --- | --- | --- || The page: full text, title, description, headings, links, dates, author | yes | fetch the URL if the agent can browse; the page source or text the reader pastes | `BLOCKED`, ask for the text || Performance: position, clicks, impressions, CTR, trend, the queries it ranks for | no | the `content-triage` handoff; a connected Search Console; a Pages and Queries export | intent mismatch can't be checked from data; coverage `partial` || The live results for its main keyword: top 5 titles, URLs and outlines | no | browse the results; titles, URLs and H2s the reader pastes | coverage, depth and format gaps not checked; coverage `partial`; ask for them || The site's page list | no | a crawl or sitemap; a pasted list | link checks limited to the page's own links || Clash result | no | the `cannibalization-audit` handoff | say "clashes not checked" | ## Profile read From `company-profile.md`: `## Company`, `## Buyers` and `## Buying moments` (whose questions the page should answer), `## Voice` (for the voice pass), `## Claims and proof` and `### Never say` (for the claim pass), `## Content` (authors, clusters, pillars), and every `## Learnings` entry for `refresh-audit` with status `noted`, `fact` or `accepted`. No profile: ask for the buyer the page is for and the company's approved claims, in one message; continue without voice rules (coverage `partial`). Say that `company-profile` saves this next time. ## Steps 1. **Apply learnings.** Read them first. Sections the reader marked as protected stay protected. 2. **Read the baseline.** Read the whole page, not a skim. Record: title and character count, description and character count, H1, every H2 and H3, word count, every claim with its source, every internal and external link, published and updated dates, author. Take performance from the `content-triage` handoff when it exists instead of pulling it again. 3. **Confirm the keyword and the intent.** The target keyword is in the title, H1 and first H2. The ranking keyword is the non-branded query with the most impressions. If they differ, compare intent: same need is fine (retarget the title), a different need is an intent mismatch (a critical finding). 4. **Read the live results** for the target keyword: the top 5 organic pages. For each: format, its H2s as short subtopics, its date, and the result features shown (featured snippet, "People also ask", an AI Overview and the pages it cites). Without the results, skip to step 6 and mark coverage `partial`. 5. **Count the gaps.** With Python, write the page's subtopics and each result's subtopics to JSON and run:    ```   python3 scripts/refresh_math.py gaps --json gaps.json   ```    Without Python: for each subtopic in the top 5, count how many cover it (2 subtopics match when they share half their words). Covered by 3 or more and missing from the page is a coverage gap. Subtopics only the page covers are its edge: protect them. Say which way you ran it. 6. **Run the checks** in `references/checks.md`: claims and sources (run `claim-check` on every claim, or apply its rules inline), coverage and format, answers near the top, voice (run `voice-check` on sections that will stay), title and description, links, dates. Each finding gets the severity the file gives it. 7. **Build the edit list.** One row per finding: tier, the problem, the exact edit, the section, why it matters. Order within each tier by impact: intent and accuracy first, then gaps on subtopics that carry the most impressions, then everything else. 8. **Mark the protected passages.** Every section with no finding is protected. Sections that carry the page's top queries, or its edge, are protected even when a finding touches them: the edit is surgical, not a rewrite of the section. 9. **Set the date rule for the writer.** After the edit, run:    ```   python3 scripts/refresh_math.py date --old old.md --new new.md   ```    The visible "updated" date may change only when 30% or more of the words changed or 2 or more sections were added. Without Python, count new H2 and H3 headings, and estimate the share of changed paragraphs; if unsure, leave the date. Google's own guidance asks whether a site changes dates to seem fresh when the content hasn't substantially changed. ## Check and verdict | Verdict | Condition (first match wins) || --- | --- || `BLOCKED` | No page text after asking || `CONSOLIDATE` | Another page on the site serves the same intent: merge first, then audit the keeper || `FULL REWRITE` | An intent mismatch (the results serve a different job than the page); or more than half the H2 sections carry a critical or important finding || `SIGNIFICANT REFRESH` | 2 or more coverage gaps that need new sections; or a format change (a table, steps, a comparison); or critical claim findings in 3 or more places || `STANDARD REFRESH` | Any critical or important finding otherwise (depth, freshness, title, links, a claim or 2) || `NO CHANGE` | Optional findings only, or none: leave the page, and don't touch its date | Named stops: `FULL REWRITE` and `CONSOLIDATE` wait for the reader before anyone starts, because both change the page's URL or most of its text. No other stops. ## Learn Append a learning to the profile when: - the reader rejects an edit as wrong for the page (a `proposal` with their reason);- the reader reports the result of a refresh, such as position or clicks 30, 60 or 90 days later (a `fact` with its source and window);- a source the audit relied on turns out dead or wrong (a `fact`, so later runs don't trust it). Example: `- 2026-10-24 | refresh-audit | fact | Adding a pricing models section moved /blog/attribution-software-guide from position 9.4 to 4.8 in 60 days | Why: Search Console, Aug to Oct 2026 | Status: noted` ## Output ```Verdict: <NO CHANGE | STANDARD REFRESH | SIGNIFICANT REFRESH | FULL REWRITE | CONSOLIDATE | BLOCKED> · Coverage: <complete | partial (what's missing) | blocked> · Gaps: <script | by hand>Rule fired: <the condition, in words>Page: <URL> · Target keyword: <keyword> · Ranking keyword: <query> · Position: <n> · Clicks: <n> · Impressions: <n>  (each "not available" when missing) Critical (fix before it ships):| # | Problem | Edit | Section | Why | Important (the refresh):| # | Problem | Edit | Section | Why | Optional:| # | Problem | Edit | Section | Protected passages: <sections, and why>Edge (only this page covers): <subtopics>Title: <current, n characters> → <hand to meta-serp-copy, or fine>Date rule: change the updated date only if 30% or more of the words change or 2 or more sections are addedLearnings applied: <list, or none>``` Then the handoff block. ## Hand off ```handoffskill: refresh-auditversion: 1.0.0verdict: SIGNIFICANT REFRESHcoverage: completefor: https://example.com/blog/attribution-software-guideoutputs:  critical: 2  important: 5  new_sections: [pricing models, CRM integration]  protected: [the customer story section]  meta_rewrite: truenext: [meta-serp-copy, internal-linking]open: [replace the 2021 benchmark with a current source]``` `next` adds `[cannibalization-audit]` for `CONSOLIDATE`, and `[keyword-selection]` for `FULL REWRITE` (the page needs a new target). ## Failure modes | Problem | Do this || --- | --- || The reader asks only to bump the updated date | Refuse the date change without an edit; run the audit or return `NO CHANGE` || The top 5 includes the reader's own page | Read the next result instead, and say so || The results are all one brand's pages or directories | Format and coverage comparisons are weak; say so and lean on buyer questions from the profile || The page is a top performer marked PROTECT by `content-triage` | Audit only for critical findings; anything else waits || A competitor's page outranks on a claim the reader can't make | Don't add the claim; note the gap and route it to `company-profile` as a claim to confirm || No position data and no results | Run claims, links, voice, title and date checks only; coverage `partial` | ## Influenced by - SHAKEUP's content engine: a tiered edit list instead of a rewrite brief, protected passages by default, every claim checked again on refresh, and a date that moves only on a substantial change.- Google's guidance on helpful, people-first content, including its question on changing dates to seem fresh: https://developers.google.com/search/docs/fundamentals/creating-helpful-content- Google's guide to its generative AI features, which says no special chunking, markup or AI files are needed: https://developers.google.com/search/docs/fundamentals/ai-optimization-guide

How it thinks

Inputs in, a verdict out, and a stop only where you decide.

What we built

A refresh is a short list of surgical edits, not a rewrite brief, and any section that works is protected by default. Every claim is checked again on refresh, because a figure that shipped 2 years ago gets no exemption.

It reads your company profile if you have one, or asks for only what it needs. Then it works through its steps, checks its own work and ends in a verdict.

The steps

  1. 01

    Read the whole page

    Title, description, headings, every claim with its source, every link, the dates and the author, recorded before any call is made.

  2. 02

    Confirm the keyword and the need

    If the page ranks for a different need than its title targets, that is a rewrite, not a refresh.

  3. 03

    Count the gaps against the top 5

    Its script flags any subtopic 3 or more of the top results cover that the page lacks, and the subtopics only your page covers.

  4. 04

    Check claims, answers, voice, title and links

    Every claim is checked again, however old. Broken links and unsourced figures are fixed before anything else ships.

  5. 05

    Rank the edits in 3 tiers

    Critical fixes ship first, then the work the refresh exists for, then optional extras. Every section without a finding is protected.

  6. 06

    Set the date rule

    The updated date moves only when 30% or more of the words change or 2 sections are added. A date bump with no edit is refused.

What you need

  • Required

    The page, with its text, title, links and dates

    It reads the URL if your agent can browse → The page text you paste

  • Optional

    The page's search data

    The handoff from content triage → A connected Search Console → A page and query export

  • Optional

    The top 5 results for its main keyword

    It reads the results if your agent can browse → Titles, URLs and headings you paste

  • Optional

    Your site's page list

    Your sitemap or crawl → A list you paste

What it can return

  • NO CHANGE

    Nothing critical or important was found. Leave the page and its date alone.

  • STANDARD REFRESH

    Targeted fixes only, such as a claim, the title, links or a thin section.

  • SIGNIFICANT REFRESH

    2 or more new sections are needed, or the format has to change.

  • FULL REWRITE

    The page serves a different need than the results reward.

  • CONSOLIDATE

    Another page on your site serves the same need. Merge first.

  • BLOCKED

    There's no page text to audit.

Where it stops for you

  • Before a full rewrite starts
  • Before a merge starts

Example output

What you get back.

A run for a made-up company. Your output depends on your inputs.

Here's a run for a made-up B2B SaaS company that sells attribution software. The page is its guide to attribution software, at position 9.4 with 14,800 impressions a year.

Verdict

SIGNIFICANT REFRESH

Coverage: complete

Gaps: script

TierProblemEditSection
CriticalA link to a deleted post returns 404Point it at the live page on the same topicHow to choose
Critical"Cut reporting time by 40%" has no sourceRemove it, or add it to the approved claims with a sourceWhat it does
Important4 of the top 5 cover pricing models, the page doesn'tAdd a section on pricing modelsNew
Important3 of the top 5 cover CRM integrationAdd a section on CRM integrationNew
Important4 of the top 5 compare tools in a tableAdd a comparison tableHow to choose
ImportantThe title runs to 72 characters and gets cutRewrite it with the title skillTitle
Protected

the customer story section. None of the top 5 has anything like it.

Date rule

change the updated date only if 30% or more of the words change or 2 sections are added. Here, 2 new sections means it can move.

The handoff block the next skill reads
skill: refresh-audit
version: 1.0.0
verdict: SIGNIFICANT REFRESH
coverage: complete
for: /blog/attribution-software-guide
outputs:
  critical: 2
  important: 6
  new_sections: [pricing models, CRM integration]
  protected: [customer story]
next: [meta-serp-copy, internal-linking]
open: [replace the 2021 benchmark with a current source]

What good looks like

  • Every edit names its section and why it matters
  • Broken links and unsourced figures sit in the critical tier
  • The sections that work, and your page's own edge, are listed as protected
  • A rewrite called only when the page serves the wrong need
  • No date change without a substantial edit

Install

Use it in the tool you already have.

Pick your tool. Each tab has the shortest path we know of.

  1. 01
  2. 02
    In Claude, open Customize, then Skills.
  3. 03
    Choose +, then Upload a skill, and pick the ZIP. Code execution must be on in your settings.
  4. 04
    Ask for it by name, or let Claude use it when a task matches.

Questions

Before you add it.

Does it rewrite the page?

No. It returns the edits, ranked, with the section each one touches. The writer makes them, and every section without a finding stays as it is.

Can it run without the search results?

Yes, with less. It checks claims, links, voice, the title and dates, marks the result partial and asks for the top 5 titles and URLs.

Why won't it just change the date?

Changing the updated date without a real edit tells readers and search engines something that isn't true. Google's guidance names it as a sign of content made for rankings.

What does the script do?

It counts the subtopics the top 5 results cover that your page lacks, and checks after the edit whether enough changed for the date to move. Without Python, the skill makes the same count itself and says so.