Skills for building AEM Edge Delivery Services sites — site creation, block development, content modeling, code review, testing, and page import.
91%
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
Operational guide for the 6-step loop. Each project executes this loop once per input page.
Before you start: read architecture.md for the overlay design and
learnings.md for accumulated gotchas. Don't re-discover what's been
documented.
1. Capture → /input/ holds the source page + assets
2. Analyze → identify header/footer, segment blocks, find slots
3. Generate → produce template, fragments, CSS, JS, DA doc
4. Wire → deploy artifacts to template-keyed paths, scripts
5. Round-trip → local diff + production preview
6. Reflect → write notes, promote learningsGoal: project is self-contained — the input can be re-analyzed without network access.
relume-pricing.input/<page-slug>.html. If the source references
external CSS/JS files, save those alongside. Inline CSS/JS stays in
the file.README.md describing: source URL, generator (if known),
capture date, page intent, anything notable about the structure
(e.g., "uses Stardust provenance metadata", "tailwind-style utility
classes throughout").Goal: structural map of what becomes header, what becomes footer, what becomes template, what becomes slots.
<body> start until <main>
start is the header fragment. Often broader than just <header> —
announcement banners, mega-nav panels, sticky breadcrumbs all live
here. Group them all into one fragment.</main> end to </body>
(minus scripts) is the footer fragment. Often includes sticky CTAs,
modal markup, etc.<main> (or each <section>
inside it) is a candidate block. Use LLM segmentation if the
source doesn't already mark sections; use semantic tags as ground
truth if it does.<img> / <picture> → image slot.<a> with text and href → link slot (carries both).aria-hidden icons, hard-coded glyphs → NOT slots,
stay in template.data-slot-skip="placeholder". Detect the convention per-input
during this phase and document it in notes.md so the Generate
subagent knows what to skip. Examples observed:
<element data-placeholder="true"> attribute.<span class="placeholder-tag"> inline marker.Write notes.md with the structural map (line numbers, section list,
header/footer boundary). The map anchors the rest of the run.
Goal: produce the five artifacts that the overlay engine consumes.
Output layout (all under output/):
output/
├── templates/<template>.html ← <main> with [data-slot] markers
├── fragments/<template>/header.html ← full header DOM
├── fragments/<template>/footer.html ← full footer DOM
├── styles/<template>.css ← extracted inline <style>
├── scripts/<template>-animations.js ← extracted inline <script> (optional)
└── da/<page-slug>.html ← DA-source body fragmentRewrite relative asset paths. When a source uses relative paths
like assets/photos/foo.jpg, url(./images/bar.png),
<link href="assets/css/site.css">, they resolve against our serving
host (localhost:3000/drafts/... or
<branch>--<repo>--<owner>.aem.page/<da-root>/...) — where they 404.
They need rewriting to one of three target forms, depending on
asset strategy (recorded in decisions.json["assetStrategy"]):
absolute (default for publicly hosted sources):
https://<source-host>/path/to/assets/.... Source host serves the
binaries directly; EDS preview sideloads any <img src> URL into
Media Bus on first preview (see da-content media.md).vendor (local-only source, accepted repo size impact):
Copy the asset tree into ./assets/ in the repo. Template /
fragment / page-CSS refs become root-relative /assets/.... DA
cell refs use absolute branch URLs
(https://<branch>--<repo>--<owner>.aem.page/assets/...).da-media (cleanest long-term):
Upload binaries to DA /media/<scope>/<file> via the bundled
<SKILL_DIR>/scripts/da-media-upload.mjs script. Template /
fragment / page-CSS / DA cell refs all use
https://content.da.live/<org>/<repo>/media/<scope>/<file>. The
uploader emits a media-mapping.json of local-path →
content.da.live URL that Generate consumes for the rewrites.| Aspect | absolute | vendor | da-media |
|---|---|---|---|
| Repo size | unchanged | +N MB | unchanged |
| Branch-independent assets | N/A | No | Yes |
| Local-only source | No | Yes | Yes |
| Initial-run effort | none | curl+sed | uploader |
| Tooling required | none | none | bundled .mjs |
| Reusable across runs | N/A | per-run | Yes |
| DA-cell image URL form | source host | branch URL | content.da.live |
| Delivered image URL | ./media_<hash> (sideload) | ./media_<hash> | ./media_<hash> |
For fonts specifically, even under da-media, place font files in Code
Bus /fonts/<file>.woff2 (or .otf) per da-content media.md
§13.2 decision tree. Fonts upload would be a DA media-bus mismatch
(SVG/PNG/JPG/MP4 are Media Bus; fonts are Content Bus).
This applies to template HTML, fragment HTML, DA cell values
referencing images, and any CSS url() references.
Don't forget head-level <link> resources. The source page's
<head> often has more than just inline <style> — font preconnects,
Google Fonts stylesheet links, etc. Extract those too and include them
at the top of the template file, above <main>:
<!-- /templates/<template>.html -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=…">
<main>
…slot-marked sections…
</main>The overlay engine lifts any top-level <link> it finds in the
template into document.head at runtime. Without these, font stacks
that name third-party fonts (Mona Sans, Inter, etc.) silently
fall back to system-ui — visually subtle, semantically wrong.
Two transformations the template needs that aren't slot-related:
Synthesize <main> if the source doesn't have one. The
overlay engine querySelector('main')s the parsed template.
When the source's body-level sections aren't already wrapped
in <main>, wrap them in one when writing the template file.
Ensure each <section>'s first class is unique within
the template. The overlay engine matches DA blocks to template
sections by section.className.split(' ')[0]. If the source
has multiple sections sharing a first class (common when
utility classes like section, card, tile are used),
rewrite so a stable discriminator becomes the first class.
Keep the original classes in the list afterward — CSS rules
depending on them still match.
Discriminator priority (use the first one that works):
data-section attribute (Stardust convention).id attribute on the section element.<p class="label">, <span class="eyebrow">, etc).section-N.Example:
- <section class="section" data-section="activity-tile-grid">
+ <section class="activity-tile-grid section" data-section="activity-tile-grid">DA HTML format, cell content normalization, page metadata, and image
URL rules live in the da-content skill (SKILL.md and
references/). Load it before writing the DA doc.
The points below are Snowflake-specific — overlay-pattern decisions
or consequences that aren't in da-content:
Metadata block lives inside <main>, not <footer>. If the
block is misplaced or misnamed, the pipeline emits no
<meta name="template">, the overlay engine bails, standard EDS
decoration falls through, and the renderer logs one 404 per block
trying to load /blocks/<name>/<name>.js.
Never write <span class="…"> into DA cells. Per
da-content the span is stripped and the class is lost —
any page CSS targeting that class stops matching. Rewrite source-
page styling hooks to CSS-on-structure (:has(), sibling
selectors) or swap to a preserved semantic element before emitting.
<img> URLs in DA cells are stricter than template/fragment
HTML. DA cells require absolute URLs (da-content).
Template and fragment HTML can use root-relative /assets/...
because the browser resolves those against the rendered page host
(= code-bus host). The DA pipeline is what's stricter, not the
browser. Acceptable absolute forms in Snowflake DA cells:
https://<source-host>/<path>/image.pnghttps://<branch>--<repo>--<owner>.aem.page/assets/...https://content.da.live/<org>/<repo>/media_<sha>...<el data-slot="name">default value</el>. Default is
overwritten by DA content at runtime, but having it makes the
template self-renderable for testing.<img data-slot="name" src="..." alt="">. Runtime
copies src and alt from the DA cell.<picture data-slot="name">…</picture>. Runtime
replaces the picture with the DA cell's <picture>.<a data-slot="name" href="…">label</a>. Runtime copies
href and innerHTML from the DA cell's <a>.style="background-image:url(…)" plus a data-slot attribute.
DA cell carries an <img>; runtime extracts its src and writes
it as the element's background-image URL, preserving other
inline styles. Use this for CSS-driven photos (hero backdrops,
card tiles where the image is the container's background, etc.)
without restructuring the source's markup. The pipeline's Media
Bus also picks up the <img> in the DA cell and serves an
optimised version via ./media_<sha>.jpg?width=…&format=…&optimize=….<el data-slot-skip="placeholder">…</el>.
Never a slot; rendered as-is.Slot names are kebab-case. Repeating items get indexed names:
card-1.title, card-2.title. Names are scoped to their block —
the same name can repeat across blocks.
Never put [data-slot] on an element that has nested [data-slot]
children. The slot writer for every element type overwrites the
target's innerHTML (or replaces it entirely), which destroys
nested slot markers before they can be processed.
Concretely:
<a class="card-link">. Either
slot the inner three children, OR slot the <a> itself — never both.<img> plus <source> siblings. Slot the
<picture>, not the inner <img>.Edge case: an <a data-slot="cta">Learn more <img></a> (text + a
decorative icon, NO nested [data-slot]) is fine. The icon is lost
when DA cell value is applied, but that's acceptable for button-style
CTAs. The trigger is nested [data-slot], not "any inner content".
<section> blocks to <section> in the templateIf a logical section in the source uses any tag OTHER than <section>
(common for <div class="hero-…">, scroll wrappers, etc.), rewrite the
outermost element to <section class="originalClassListHere"> in the
generated template. The CSS continues to work; the engine can now
match the block by its first class. Keep the inner DOM intact.
This complements the existing rule about synthesizing <main>.
Goal: deploy artifacts to the template-keyed paths and verify prior runs' work is untouched.
Copy from output/ to the EDS-served paths:
output/templates/<template>.html → templates/<template>.html
output/fragments/<template>/header.html → fragments/<template>/header.html
output/fragments/<template>/footer.html → fragments/<template>/footer.html
output/styles/<template>.css → styles/<template>.css
output/scripts/<template>-animations.js → scripts/<template>-animations.jsRun the transformer to produce the local-test file:
node tools/transform-da-to-eds.mjs \
<project>/output/da/<page>.html \
drafts/<page>.htmlhead.html does NOT change. styles/styles.css does NOT change.
scripts/scripts.js (carries the overlay hook — the engine itself is in
scripts/overlay-engine.js) and scripts/delayed.js and the
blocks/{header,footer}/* decorators are already template-keyed —
no edits needed.
Run npm run lint — must be clean. The boilerplate ignore patterns
already exclude styles/*.css (except styles.css/fonts.css/
lazy-styles.css) and scripts/*-animations.js, so vendor CSS/JS
from the source page are auto-excluded.
Goal: validate that the rendered DOM matches the original input byte-for-byte (or at least: same element count, same tag+class sequence, same visible text).
Local first:
aem up --html-folder drafts --no-open --forward-browser-logsLoad http://localhost:3000/drafts/<page>.html in Playwright.
Capture document.querySelector('main').outerHTML. Compare to
input/<page>.html lines for <main>. Save both to diff/ and
write a per-tag count table + a tag+class sequence diff in
diff/README.md. Take a viewport screenshot.
Screenshot strategy. For pages with position: sticky,
scroll-driven JS, or IntersectionObserver .anim-enter-style
animations, fullPage: true screenshots are misleading — the snapshot
is taken in initial-scroll state where sticky elements leave empty
space and .anim-enter siblings are opacity: 0. Default to
per-section viewport screenshots: call
section.scrollIntoView({ block: 'start' }), wait 400-800ms for
animations to settle, then capture. Save each as
diff/local-<sectionName>.jpg.
Local-only source caveat. If the source URL is on a private host
(localhost, 127.0.0.1, intranet IP), the production preview host
cannot reach the source's assets. Three options, in order of
preference:
/assets/ in the repo.
Same paths work locally and on production via code-bus. Same-origin
so no CORS issues for fonts. Trade-off is repo size. Mechanical
steps:
cp -R <source-assets-dir> ./assets/.DS_Stores and unreferenced files%20)/assets/...https://<branch>--<repo>--<owner>.aem.page/assets/...) — Media
Bus requires absolute (see Generate phase rule #4)./media/. Cleaner long-term; requires
tooling not yet in scope.Production round-trip:
TOKEN="${DA_TOKEN:-$(jq -r .access_token ~/.aem/da-token.json)}"
curl -X PUT -H "Authorization: Bearer $TOKEN" \
-F "data=@<project>/output/da/<page>.html;type=text/html" \
https://admin.da.live/source/<org>/<repo>/<da-root>/<page>.htmlcurl -X POST -H "Authorization: Bearer $TOKEN" \
https://admin.hlx.page/preview/<org>/<repo>/<branch>/<da-root>/<page>https://<branch>--<repo>--<org>.aem.page/<da-root>/<page> in
Playwright. Verify main.dataset.overlay === '<template>', section
count matches, no console errors.aem.live (= the main branch's live URL) is generally NOT in
scope for experimental branches — only aem.page against the feature
branch is.
Goal: feed the next run.
notes.md for everything that happened.learnings.md for findings tied to this
source.learnings.md.
Test for promotion: "would the next project, from a different
generator and different page, benefit from knowing this?" If yes,
it goes in the cross-project learnings.architecture.md or
eds-da-mechanics.md, update those docs in the same commit. If the
finding is about DA HTML rules (not the overlay engine), it belongs
in the da-content skill — file a separate PR against that
skill rather than duplicating into Snowflake.tools/ directory with a README.Once a run is closed and published, you may want to re-render it under a newer skill substrate (to demonstrate skill improvements, fix bugs found later, etc.). The skill supports this but doesn't prescribe a single strategy — pick the one that fits the repo's intent:
Rename the existing close tag with a date suffix (e.g.
sd-foo-a-close → sd-foo-a-close-2026-05-19), reset the branch tip to
trunk, run phases 0–6 fresh, re-tag sd-foo-a-close at the new commit.
DA's PUT auto-versions the doc; the 5.2.2a labeled snapshot adds an
explicit "Before refresh" entry. Only the latest version stays reachable
at the active branch URL. Old states are archived in git and DA versions.
Before refreshing, clone the branch to a dated branch
(sd-foo-a → sd-foo-a-2026-05-19) AND copy the DA path to a dated DA
path (/foo/a → /foo/a-2026-05-19). Both versions stay live at
separate URLs. The active branch resets and refreshes; the snapshot
branch is immutable. Good for demo collections where you want to show
"how this evolved." Branch count grows with each refresh — manageable
if refreshes are quarterly, less so if daily.
Each refresh adds versioned template / CSS / DA paths to the same branch
(e.g. templates/foo-2026-05-19.html, /foo/a-2026-05-19). One branch
per demo, but file count accumulates over time. Useful when branch
proliferation is undesirable but A/B-ability is required.
For all three modes, use ISO date as the version suffix:
<base>-YYYY-MM-DD for branches, DA paths, and (mode A only) close tags.
Same-day collisions get a -N counter starting at 2:
<base>-2026-05-19-2, <base>-2026-05-19-3.
Repos with strong opinions on naming (version numbers, semantic-version
of substrate, etc.) document the override in
.snowflake/knowledge/methodology.md.
git tag NEW OLD # create new tag at same commit
git tag -d OLD # delete old tag locally
git push origin NEW :OLD # push new, delete old on remoteNot atomic on remote but reliable. Verify with
git ls-remote origin 'refs/tags/<branch>-*' after.
.tessl-plugin
skills
aem-block-library
aem-cli
aem-layout-view
block-collection-and-party
brand-setup
references
building-blocks
code-review
content-driven-development
references
content-modeling
create-site
da-auth
figma-to-content
find-test-content
generate-import-html
identify-page-structure
migrate-header
page-decomposition
page-import
preview-import
scrape-webpage
slicc-handoff
snowflake
assets
substrate
substrate-milo
examples
knowledge
scripts
testing-blocks
ue-component-model