agentleFS
tyler-berggrentyler-berggren/tb-claude-kit/.claude/skills/web/SKILL.md

web

Skill2 starsChanged 5 days agoMITView on GitHub

Audit and repair a static site's SEO/AEO assets — metadata, structured data, sitemap, robots, llms.txt, markdown mirrors. Checks they are present, correct, and still current against the pages they describe.

12 other projects use a version of this.

Adopted by

Most recently taken up by

The file

Show its rules and text

We split this skill into the rules it gives an agent

15 rules. 0 are common, 8 are distinctive, and 7 are very specific to this project.

  • 0

    Common

    Most of the 11 edited versions we read keep these.

  • 8

    Distinctive

    This author's own choices. Worth a look.

  • 7

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Add --live when the argument asks for it.

    line 47
  2. Very specific:

    If the scanner reports it cannot find a site directory, ask which directory holds the built site and offer to record it in .claude/kit.json …

    line 54
  3. Distinctive:

    Read every finding before you fix any of them.

    line 60
  4. Very specific:

    Read both: a mirror that deliberately condenses a paragraph for machine readers is a decision to record as an ignore rule, while a mirror …

    line 69
  5. Distinctive:

    Never fix a finding you have not looked at in its source file.

    line 76
  6. Distinctive:

    Run the scanner again. Confirm the count dropped and that you introduced nothing new.

    line 136
  7. Very specific:

    When cowork/brain/BRAIN.db exists, log a milestone summarizing the run, and log any finding the user declined to fix now as a task so it is …

    line 142
  8. Very specific:

    Never silence a finding to make a run look clean.

    line 229
  9. Distinctive:

    Scan before speaking: Never characterize the site's SEO/AEO state from reading a file or two.

    line 234
  10. Distinctive:

    The scanner never writes: All repair goes through Claude's edits, so it is reviewable and matches each file's house style.

    line 236
  11. Very specific:

    Manual means ask: Never rewrite a meta description, FAQ answer, or llms.txt paragraph and mention it afterwards.

    line 240
  12. Distinctive:

    The page is the source of truth: When derived assets disagree with rendered copy, sync the asset to the page — unless the user says the …

    line 242
  13. Distinctive:

    Report failures plainly: If findings remain, say which and why.

    line 247
  14. Distinctive:

    Do not invent assets the project has not opted into: If a site has no markdown mirrors, their absence is not a finding — mirrors are only …

    line 249
  15. Very specific:

    If .claude/kit.json has a rules."web" entry, read it and apply it as an additional instruction for this skill.

    line 257

“Common” is measured: kept by at least 6 in 10 of the 11 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Site root

!ROOTS=$(jq -r '.web.roots[]?' .claude/kit.json 2>/dev/null); [ -z "$ROOTS" ] && ROOTS="web public dist site build _site out sitemd/site"; for r in $ROOTS; do [ -d "$r" ] && ls "$r"/*.html >/dev/null 2>&1 && echo "$r ($(find "$r" -name '*.html' -not -path '*/.*' | wc -l | tr -d ' ') html files)" && break; done || echo "No site directory found — set web.roots in .claude/kit.json"

Base URL

!jq -r '.web.baseUrl // "not set — set web.baseUrl in .claude/kit.json for canonical and sitemap checks"' .claude/kit.json 2>/dev/null || echo "no kit.json"

Asset inventory

!ROOT=$(jq -r '.web.roots[0]? // empty' .claude/kit.json 2>/dev/null); [ -z "$ROOT" ] && for r in web public dist site build _site out sitemd/site; do [ -d "$r" ] && ROOT="$r" && break; done; for a in robots.txt sitemap.xml llms.txt llms-full.txt _headers; do [ -f "$ROOT/$a" ] && echo " present $a" || echo " MISSING $a"; done 2>/dev/null


Web — SEO/AEO asset audit

Static sites accumulate two kinds of rot. Assets go missing (no llms.txt, no structured data, no snippet directives), and — more insidiously — assets go stale: the sitemap still claims a page was last touched in March, the markdown mirror describes a service you renamed, the FAQ schema answers a question the page no longer asks. The second kind is worse than having nothing, because it feeds confident wrong answers to the engines reading it.

This skill scans for both, fixes what has one right answer, and asks about anything that involves words a human would recognize as their own voice.

Dispatch

ArgumentBehavior
(empty)Scan, auto-fix mechanical findings, propose the rest
reportScan and report only — write nothing
liveScan plus probe the deployed site, then fix as normal
live reportProbe and report, write nothing

Procedure

Step 1 — Scan

python3 .claude/skills/web/scan.py --json

Add --live when the argument asks for it. The scanner reads web.roots and web.baseUrl from .claude/kit.json; pass --root / --base-url to override.

It writes nothing, ever. Output is JSON: {root, baseUrl, pages, counts, findings}, each finding carrying severity, check, file, line, message, detail, and fix (auto or manual).

If the scanner reports it cannot find a site directory, ask which directory holds the built site and offer to record it in .claude/kit.json rather than passing --root every run.

Step 2 — Triage before touching anything

Read every finding before you fix any of them. The scanner is deliberate about severity but it cannot see intent:

  • A noindex page with no Open Graph tags is correct, not a gap. The scanner already suppresses this — if you see it flagged, the page's robots meta is not what you assumed.
  • mirror-missing-section on a heading the mirror deliberately rewords is a judgment call, not a defect.
  • mirror-text-drift reports the page's wording and the mirror's side by side. Read both: a mirror that deliberately condenses a paragraph for machine readers is a decision to record as an ignore rule, while a mirror still carrying copy the page has since rewritten is exactly the rot this check exists to find.
  • schema-price-mismatch may mean the page copy changed and the schema is now lying, or that the page says "starting at $5,000" while the schema correctly uses minPrice. Read both before deciding which one is wrong.

Never fix a finding you have not looked at in its source file.

Step 3 — Auto-fix the mechanical findings

Findings marked "fix": "auto" have exactly one correct answer. Apply them directly, no confirmation:

CheckFix
sitemap-stale-lastmodSet <lastmod> to the page's real last-modified date
sitemap-missing-pageAdd the <url> entry
sitemap-orphanRemove the entry, or note it if the page is deploy-generated
sitemap-no-lastmodAdd <lastmod>
open-graphAdd the missing tag, mirroring existing values on the page
og-image-relativeMake the URL absolute against baseUrl
twitter-cardAdd summary_large_image when an og:image exists, else summary
snippet-directivesAdd max-snippet:-1, max-image-preview:large, max-video-preview:-1
canonical, canonical-relative, canonical-mismatchPoint at the absolute page URL
headers-content-typeAdd a Content-Type rule for the asset
robots-no-sitemap, robots-no-llmsAdd the reference
favicon, apple-touch-icon, viewport, langAdd, reusing assets already in the project
llms-full-staleRegenerate from the current mirrors

Match the file's existing formatting — indentation, attribute order, quote style, whether tags are one-per-line or wrapped. A fix that reformats surrounding lines is a bad fix.

Step 4 — Propose everything else

Findings marked "fix": "manual" touch words, structure, or claims. Show the user what is wrong and what you would write, then wait.

This especially covers anything a human would recognize as their own voice — meta descriptions, llms.txt prose, FAQ answers, page copy. Many projects hold the rule that the human writes all customer-facing language; machine-facing text like llms.txt still counts, because it is the text an answer engine is most likely to paraphrase when describing them.

Present them grouped, with the actual before/after:

NEEDS YOUR CALL

  faq-answer-drift — web/index.html
    Page:   "Nope. For right now, it's just me."
    Schema: "Nope. For right now it's just me."
    → The schema is stale. Update it to match the page? [y/n]

  description-length — web/index.html (179 chars, aim ≤165)
    Current:  "I handle all of your tech so you can focus..."
    Proposed: "..."
    → Your copy. Rewrite, or leave it? [y/n/edit]

For content drift, the page is almost always the source of truth and the derived asset (schema, mirror, llms-full.txt) is what is stale. Say which direction you propose to sync and why, because occasionally it is the other way round.

Step 5 — Re-scan

Run the scanner again. Confirm the count dropped and that you introduced nothing new. Report the before/after counts honestly — if something is still failing, say so rather than describing the run as clean.

Step 6 — Record, if the project has a brain

When cowork/brain/BRAIN.db exists, log a milestone summarizing the run, and log any finding the user declined to fix now as a task so it is not silently dropped:

INSERT INTO logs (type, title, body, tags, importance)
VALUES ('milestone', 'Web audit: <n> fixed, <n> deferred', '<what changed>', 'aeo,seo,website', 5);

Normalize tags: split on comma, trim, lowercase, sort, dedupe, rejoin.

What gets checked

Per page — lang, title presence and length, meta description presence and length, viewport, canonical (present, absolute, matches the page URL), robots snippet directives, the Open Graph set, Twitter card, favicon and apple-touch-icon, exactly one h1, heading-level skips, img alt text, JSON-LD parses, and JSON-LD @id references resolving to a node that exists.

Site-wide — robots.txt exists and does not block the site, points at a sitemap, mentions llms.txt when one exists; sitemap.xml is valid XML, lists every indexable page, lists no page that does not exist, lists no noindex page, and carries lastmod on each entry; llms.txt follows the llmstxt.org shape and every link in it resolves on disk; _headers declares a Content-Type for .md assets when nosniff is set.

Currency — this is the part that catches rot rather than absence:

  • sitemap-stale-lastmod — <lastmod> older than the page's real last change, taken from git when the file is committed and clean, filesystem mtime otherwise
  • mirror-missing-text / mirror-text-drift — a paragraph of page copy with no counterpart in the markdown mirror, or one the mirror words differently. This is the check that catches an edited sentence: mirrors are compared block by block, because a whole-document similarity score cannot see one rewritten line in a thousand-word page and reports clean while the mirror still tells engines the old story
  • mirror-drift / mirror-missing-section — whole-document and heading-level backstops for the same mirrors, catching wholesale rot and dropped sections
  • llms-full-stale — the concatenated corpus missing any substantive paragraph of a current mirror
  • faq-count-mismatch / faq-question-mismatch / faq-answer-drift — FAQPage structured data disagreeing with the <details> blocks actually rendered
  • schema-price-mismatch — a price asserted in structured data that appears nowhere in the visible copy
  • llms-txt-dead-link — llms.txt pointing at a file that does not exist

Live (--live only) — served Content-Type for .md and .txt assets, canonical Link headers on markdown mirrors, HTTP status for every page and asset, and redirect chains. This is the only way to catch deploy-config drift, where the local _headers looks right and production ignores it.

Configuration

{
  "web": {
    "roots": ["web"],
    "baseUrl": "https://example.com",
    "ignore": [
      {
        "check": "mirror-missing-section",
        "file": "web/index.md",
        "match": "Hi, I’m Tyler",
        "note": "the mirror deliberately uses a descriptive heading for machine readers"
      }
    ]
  }
}

roots is a list of candidate directories; the first that exists and contains HTML wins. Absent, the scanner tries web, public, dist, site, build, _site, out, sitemd/site, then the project root.

baseUrl is the canonical origin. Without it, canonical-URL and sitemap-URL checks are skipped and --live cannot run — everything else still works.

ignore records divergences the project has decided are correct, so a re-run does not re-litigate them. Each rule needs check; file and match (a substring of the finding's message) narrow it; note explains the decision and is printed back whenever the rule fires.

Suppressed findings are counted in every run's header and listed under --show-suppressed, and they stay in the JSON under suppressed. They are never silently dropped — a suppression you cannot see is indistinguishable from a check that stopped working.

Only add an ignore rule when the user has decided the current state is right. Never silence a finding to make a run look clean. A rule with no note is a rule nobody will be able to evaluate in six months.

Rules

  • Scan before speaking. Never characterize the site's SEO/AEO state from reading a file or two. Run the scanner.
  • The scanner never writes. All repair goes through Claude's edits, so it is reviewable and matches each file's house style.
  • Auto means auto. Findings marked auto are applied without asking. Do not pad the conversation by confirming a missing og:site_name.
  • Manual means ask. Never rewrite a meta description, FAQ answer, or llms.txt paragraph and mention it afterwards. Propose, then wait.
  • The page is the source of truth. When derived assets disagree with rendered copy, sync the asset to the page — unless the user says the page is the thing that is wrong.
  • Verify by re-scanning. A fix is not done because the edit applied. Re-run and confirm the finding is gone.
  • Report failures plainly. If findings remain, say which and why. Never describe a run as clean when it is not.
  • Do not invent assets the project has not opted into. If a site has no markdown mirrors, their absence is not a finding — mirrors are only checked when a page declares one.

Project overrides

If .claude/kit.json has a rules."web" entry, read it and apply it as an additional instruction for this skill. Absent file or key means no overrides — that is the normal case.

jq -r '.rules."web" // empty' .claude/kit.json 2>/dev/null

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.