Redesign an existing website to make it better. Built on top of impeccable.
88%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Low
Low-risk findings worth noting
Blocks that LIST other pages (directories, news/event feeds, "related" rails) read an EDS query-index (a published JSON of pages with per-page properties) instead of frozen cards — when the source is not editorially curated; that decision stays human and is recorded in the inventory.
What a dynamic block can show is bounded by what each page emits, and an index row carries only
page-intrinsic DOM or authored metadata. The metadata a block needs must be decided before
the batch import — emitting it per page at write time is one extra row; retrofitting it across
thousands of published pages is a second migration. stardust/dynamic-features.md § Listings contract records it; helix-query.yaml at the EDS project root is authored from the same contract.
h1, og:image, authored links) via CSS selectors in
helix-query.yaml. Zero content change. Meaningful internal links become free facets.<meta name="…"> through
each page's metadata block at author time. A metadata row KEY | VALUE renders to
<meta name="<key lowercased>">: single-token capitalised keys (PublishDate →
publishdate), selectors meta[name="publishdate"], dates as ISO YYYY-MM-DD.static-snapshot — record it, do not fake it.helix-query.yaml first/query-index.json answering 404 means the project ships no helix-query.yaml (the demo
boilerplate does not) — a code-branch authoring gap, never a configuration-service problem. The
first remedy, in this order:
helix-query.yaml at the code-branch root: the delivered content roots into
target: /query-index.json, chrome and search documents excluded.
version: 1
indices:
default:
include:
- '/**'
exclude:
- '/nav'
- '/footer'
- '/**/nav*'
- '/**/footer*'
- '/fragments/**'
- '/drafts/**'
- '/search'
target: /query-index.json
properties:
title:
select: head > meta[property="og:title"]
value: attribute(el, 'content')
description:
select: head > meta[name="description"]
value: attribute(el, 'content')
image:
select: head > meta[property="og:image"]
value: match(attribute(el, 'content'), 'https:\/\/[^/]+(\/.*)')
lastModified:
select: none
value: parseTimestamp(headers['last-modified'], 'ddd, DD MMM YYYY hh:mm:ss GMT')
robots:
select: head > meta[name="robots"]
value: attribute(el, 'content')publishdate, category, …) from § Listings
contract; a text property (select: main, value: textContent(el)) when search excerpts
are wanted; a lang property per locale tree (a scoped index per tree, locale-trees.md).GET <origin>/query-index.json no more often than every 5 s, for at most 10 minutes,
until it answers 200 with total at the expected page count (re-publish one page to nudge an
index that stays at building). The total goes into the ledger detail.No admin configuration-service write is part of this — a 403 from admin.hlx.page/config/…
with the migration token is expected and is not a blocker. A recorded hands-off run probed that
service, concluded "no index can be configured" and built a sheet-backed interim index while
the fix was one committed yaml file. The sheet-backed index (rows synced with
scripts/sync-sheets.mjs, the block reading the sheet's JSON) is the fallback ONLY when the
code branch is not writable, recorded interim with the owner decision named.
target per index; exclude chrome and search documents; a
lang property per locale tree; a text property when search excerpts are wanted.POST /index/… answering "requested path returned a 301 or 404" means "not published", not
"bad selector". Publish per page as a delivery-loop step, then poll total until it settles.Document-first. The generator writes the listing INTO the document: for a flat listing one row
per item carrying exactly the text the card shows (title link, date, category, address, excerpt);
for a grouped listing a heading row per group, then its item rows; last, one label-list row (a
<ul> of the block's UI strings — filter labels, "View details", empty-state copy). The block
renders from rows and reads the index only for what is not text (images, coordinates) and to top
up items published after the last write, newest first, client-paged. Re-runs of the generator
recognise their own rows (a link into the listed template set, or the label list) and replace them,
so an index change is a re-run, never a merge. Curated authored rows are preserved verbatim.
Why: served words ÷ rendered words is what Adobe's readability checker scores and what non-rendering
crawlers read — a block that builds 65 cards from the index leaves ~850 words out of the document and
halves the page's score (deploy/reference/ai-readability.md). Index-only rendering is right for
thousands of items or per-user results; such a page needs an authored summary in the document.
Verify. Authored rows equal the index on the listing pages; a newly published page appears after publish (top-up); the AI-readability gate reads ≥ 98 on every listing page.
.tessl-plugin
skills
audit
reference
deploy
reference
scripts
test
diff
direct
dynamics
extract
migrate
prepare-migration
prototype
assets
motion
fixtures
reference
qa
replica
reference
scripts
test
reskin
rollout
spec
stardust
uplift
reference