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
Goal: produce the deployable artifacts and the DA-source body
fragment, written to the project's output/ folder. The artifacts
differ by conversion level.
Read decisions.json.conversionLevel:
page-level → follow the page-level path below (overlay
template + slot markers). This is the original snowflake path.block-level → follow the block-level path below (per-section
EDS blocks). See
../knowledge/block-level-conversion.md
for the architecture and patterns.hybrid → block-level for passing sections, static fragments
for failing sections. Follow block-level path with fragment
fallbacks per decisions.json.feasibility.sections[].level.Before writing anything, load (using the override-then-bundled
resolution from SKILL.md):
Always:
methodology.md §3 (Generate) — the authoritative ruleslearnings.md — at minimum the entries for "container vs.
children", "Media Bus absolute URLs", "<br> stripping",
"non-<section> blocks must be rewritten", plus whatever else
applies to the patterns in decisions.jsonPage-level additionally:
architecture.md §"Slot semantics" — all five slot writer cases
the engine supportsBlock-level additionally:
block-level-conversion.md — output layout, decorator pattern,
CSS extraction, content model design, drafts test page format(On the milo flavor, the gated pointer below sends you to
assets/substrate-milo/FLAVOR.md, which carries the Milo block-level
deltas and the --pa-* animation vocabulary.)
Resolution at each lookup: check .snowflake/knowledge/<file>.md
first (project override), then <SKILL_DIR>/knowledge/<file>.md
(bundled). Project overrides win on conflict.
Follow this section when conversionLevel is page-level.
substrateFlavor is milo)If .snowflake/config.json substrateFlavor is milo, STOP and read
../assets/substrate-milo/FLAVOR.md#generate-page
FIRST, then apply its deltas to the page-level steps below (Milo owns the chrome;
the bespoke body is drawn by the blocks/snowflake overlay block). For the EDS
flavor, ignore this and follow the steps as written.
Under <projectsDir>/<NNN>-<slug>/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> (if any)
da/<page-slug>.html ← DA-source body fragmentPlus any vendored external libs (scripts/<template>-<libname>.js,
styles/<template>-<libname>.css) and any vendored static assets
(assets/...) per the asset strategy in decisions.json.
Work through the steps below in order. At each, check decisions.json for any project-specific overrides.
<link> resourcesFrom decisions.json["headLinks"], emit each as a top-level
<link> at the very top of the template HTML file, ABOVE the
synthesized <main>. The substrate engine lifts these into
document.head at runtime.
Do NOT include a <link> for /styles/<template>.css here — the
substrate loads that dynamically when the overlay applies.
<main>Walk the source body sections in document order. For each section
in decisions.json["sections"]:
originalTag !== "section" and rewriteToSection === true,
change the outermost element to <section> while preserving the
complete class list and all inner DOM.<main> wrapper (almost always
true for static AI-generated pages), synthesize one around the
collected sections.slots[i]:
selector inside the section.data-slot="<name>" to it. Keep the default content (acts
as fallback when DA cell is empty).<sup>,
<sub>, <strong>, <em>, <del>, <ins>, <mark>, <code>,
<kbd>, anchors, images) that sit BETWEEN text runs, leave them
inside the element and slot the WHOLE element. Do NOT wrap the
text in a sub-<span data-slot> that excludes the inline tags —
the DA cell would then be missing them and the .md
representation would be incomplete (authors can't see/edit the
marker). See <SKILL_DIR>/knowledge/learnings.md entry
"2026-05-20 — inline content elements belong INSIDE the slot".background-image slots, the element keeps its inline
style="background-image:url(...)" AS-IS. The substrate writer
replaces the URL at runtime.link slots, only apply if the <a> has NO nested
[data-slot] descendants. Container-vs-children rule.decisions.json marks a slot with
"mixedContent": true, do NOT place data-slot on the element
itself (its innerHTML replacement would destroy decorative
children like SVGs and icons). Instead, wrap only the authorable
text portion in <span data-slot="name">text</span>, leaving
decorative siblings (SVGs, icon images) outside the wrapper as
static template chrome. In the DA doc, emit the value as plain
text (not a link). See learnings entry "link slots with inline
decorative elements".decisions.json["strip"] — they don't
appear in the template.data-slot-skip="placeholder"
(never authorable; substrate ignores them).Extract everything from <body> start up to (but not including) the
first content section. Wrap as the body of fragments/<template>/header.html.
Apply asset path rewrites (3.7 below). Header has NO [data-slot]
markers — it's static repository content.
Extract everything from the last content section end to </body>,
MINUS <script> tags and any stripped dev-tool markup. Save as
fragments/<template>/footer.html. Apply asset path rewrites. No
[data-slot] markers.
Concatenate the source's inline <style> blocks (line ranges in
decisions.json["inlineStyleLines"]) into a single file at
styles/<template>.css. Strip the <style> and </style>
wrapper lines — emit only the inner content. Apply asset path
rewrites to any url(...) references inside.
If decisions.json["externalLibs"][i].strategy === "vendor" and the
lib includes a CSS file: copy it to
styles/<template>-<libname>.css verbatim.
Concatenate the source's inline <script> blocks (line ranges in
decisions.json["inlineScriptLines"]) into
scripts/<template>-animations.js. The substrate loads this via
HEAD probe; if it 404s the page still works.
For vendored external libs that need an initialization hook (e.g. Lenis), inject a small loader prelude that:
<script> element pointing at the vendored lib pathonload to a function that runs the rest of the script(function () {
const s = document.createElement('script');
s.src = `${window.hlx.codeBasePath}/scripts/<template>-<libname>.js`;
s.onload = main;
document.head.appendChild(s);
function main() {
// original inline script body goes here, including library init
}
})();For any inline onclick="someFunc()" references in the template,
expose someFunc on window from inside main().
Per decisions.json["assetStrategy"]:
"absolute" (public source host): rewrite every relative
assets/... reference to ${assetBase}assets/... (absolute URL
pointing at the source host).
"vendor" (local-only source host, or user-requested vendor):
assets/ directory (preserving subfolder structure).
Use curl if source is HTTP, cp -R if filesystem path is
available..DS_Stores and any unreferenced files in the copied
tree.%20)./assets/....https://<branch>--<repo>--<owner>.aem.page/assets/...). Media
Bus only resolves absolute URLs. The branch name comes from
decisions.json or is asked of the user.The asymmetry is critical and worth a sanity check: search the
output for any src="assets/" (missing leading slash, non-absolute,
not vendored-absolute) — should find none.
Write output/da/<page-slug>.html in the canonical <div class="…">
block form (see da-content). Read da-content (Blocks, Inline tags,
Page metadata, Images and links) before writing this file — block format, cell content
normalization, page metadata, and image URL rules all live there.
Structure:
<body>
<header></header>
<main>
<div>
<div class="<first-class-of-section-1>">
<div><div><slot-name></div><div><slot-value></div></div>
... one row per slot, paired divs ...
</div>
</div>
... one outer-div per section ...
<div>
<div class="metadata">
<div><div>template</div><div><templateName></div></div>
<div><div>title</div><div><pageTitle></div></div>
</div>
</div>
</main>
<footer></footer>
</body>Snowflake-specific reminders (universal rules are in da-content):
<main> — placement in <footer>
breaks the overlay engine (no <meta name="template"> → engine
bails → standard EDS decoration 404s on every block).<span class="…"> into cells — class is lost on
normalization, breaking any CSS hook the source page relied on.https://<branch>--<repo>--<owner>.aem.page/assets/... (DA cells
don't accept root-relative paths even though template/fragment
HTML does).Run these checks. If any fail, fix the affected artifact and re-run the check.
PROJ="${PROJECTS_DIR}/${NNN}-${SLUG}"
# 1) Template has <main> and all sections have unique first-classes
node -e '
const fs = require("fs");
const { JSDOM } = require("jsdom");
// ... or use regex-based check if jsdom not available
'
# 2) No relative "assets/" refs in template/fragments/CSS
grep -REn "=\"assets/" "$PROJ/output/templates" "$PROJ/output/fragments" "$PROJ/output/styles" && echo "FAIL: relative assets/" || echo "OK"
# 3) No nested [data-slot] inside another [data-slot]
# (would need a DOM parse — skip for now if jsdom not available;
# document this gap in the future-validator roadmap)
# 4) DA doc has no <span class> (stripped) and no <table> (Snowflake
# uses div form). See da-content (Inline tags) for full normalization.
grep -cE "<table|<span class" "$PROJ/output/da/"*.html
# expected: 0 (per file)
# 4a) WARN: <br> is position-dependent (da-content, Inline tags).
grep -nE "<br>" "$PROJ/output/da/"*.html && echo "WARN: <br> found — verify position" || echo "OK"
# 5) DA cell <img> URLs are absolute
grep -oE "<img[^>]*src=\"[^\"]+\"" "$PROJ/output/da/"*.html \
| grep -vE "src=\"https?://" && echo "FAIL: non-absolute DA img" || echo "OK"
# 6) No section first-class collides with a CSS layout rule
# This is the most common post-conversion layout bug — inner CSS class
# used as section first-class picks up grid/flex rules meant for inner div.
grep -oE 'class="[^"]*"' "$PROJ/output/templates/"*.html \
| grep -oE '^[a-z][a-z0-9-]+' \
| sort -u \
| while IFS= read -r cls; do
if grep -qE "\.${cls}[[:space:]]*\{" "$PROJ/output/styles/"*.css 2>/dev/null; then
echo "WARN: section first-class '$cls' appears as CSS selector — verify no layout collision"
fi
done || echo "OK: no first-class CSS collisions detected"
# 7) No slot whose element contains non-authorable children
# (SVGs, decorative images that writeSlot innerHTML would destroy).
# DOM-based check — more reliable than regex for nested structures.
node -e '
const fs = require("fs");
const html = fs.readFileSync(process.argv[1], "utf8");
const { JSDOM } = require("jsdom");
const dom = new JSDOM(html);
const doc = dom.window.document;
const bad = [];
doc.querySelectorAll("[data-slot]").forEach((el) => {
const deco = el.querySelectorAll("svg, img[aria-hidden], img[role=presentation]");
if (deco.length) bad.push(el.getAttribute("data-slot") + " contains <" + deco[0].tagName.toLowerCase() + ">");
});
if (bad.length) { bad.forEach((b) => console.error("WARN: " + b + " — use span-wrapper")); process.exit(1); }
' "$PROJ/output/templates/${TEMPLATE_NAME}.html" \
&& echo "OK: no mixed-content slots" \
|| echo "FAIL: slots with decorative children found — see learnings: span-wrapper pattern"Set state.phase = "generate", state.phaseStatus = "complete",
state.generateCompletedAt = "<timestamp>". Record:
state.conversionLevel = "page-level"state.slotCount — total number of [data-slot] markers across
the templatestate.sectionCount — number of sections in <main>Continue to Phase 4 (Wire).
Follow this section when conversionLevel is block-level or
hybrid. The full architecture is in
../knowledge/block-level-conversion.md;
this section is the step-by-step execution.
substrateFlavor is milo)If .snowflake/config.json substrateFlavor is milo, STOP and read
../assets/substrate-milo/FLAVOR.md#generate-block
FIRST, then apply its deltas to the B.* steps below — including B.5b animation
sidecars (--pa-* animation blocks consumed by the vendored runtime). Milo owns
the runtime and auto-loads forge-* blocks; the decorator pattern and DA block-table
format below are unchanged. For the EDS flavor, ignore this.
Artifacts are written directly to the EDS repo (not to a project
output/ subfolder) because block-level produces standard EDS files
at standard paths:
styles/styles.css ← global tokens + shared components
styles/fonts.css ← empty (fonts via head.html)
head.html ← font preconnects (appended)
fragments/<brand>/header.html ← static header fragment
fragments/<brand>/footer.html ← static footer fragment
blocks/header/header.{js,css} ← fragment loader + header styles
blocks/footer/footer.{js,css} ← fragment loader + footer styles
blocks/<name>/<name>.{js,css} ← one pair per content section
assets/ ← vendored images/logo
drafts/<page-slug>.html ← local test page
output/da/<page-slug>.html ← DA body fragment (for upload)Split the source's inline <style> block. See
block-level-conversion.md §"Global styles extraction" for the
two-bucket split (global vs per-section).
Write styles/styles.css with:
body { display: none }, header/footer
visibility, .appear):root design tokens.eyebrow, .btn variants, .editorial, etc.):root token changesWrite styles/fonts.css as empty (fonts loaded via CDN).
Append font preconnects and the CDN stylesheet link to head.html,
placed after the viewport meta but before the aem.js script tag.
Per decisions.json["assetStrategy"] (usually vendor for
local-only sources):
assets/.DS_Stores, rename dirs with spaces/assets/...Extract header and footer markup from the source. Write to
fragments/<brand>/header.html and footer.html. Rewrite asset
paths to root-relative.
Write blocks/header/header.js and blocks/footer/footer.js as
simple fragment loaders (see block-level-conversion.md
§"Header/footer fragment pattern").
Write blocks/header/header.css and blocks/footer/footer.css
with the header/footer CSS rules extracted from the source.
Each block is fully independent — its own JS, CSS, and content model with no shared state or cross-block dependencies. Blocks can be generated in parallel. If the host environment supports dispatching independent work units concurrently (subagents, worker threads, scoops, etc.), use that capability here — it is safe and significantly faster for pages with many sections. Sequential generation is equally correct if parallelism is not available.
For each content section in decisions.json.feasibility.sections[]
where level === "block":
Design the content model — map the section's authorable
content to DA block table rows. See
block-level-conversion.md §"Content model design". Generator
placeholder UIs (data-placeholder="true" / visible "PLACEHOLDER · …"
text) are static source content — carry them into the content model
verbatim; never drop them or reinterpret them as dynamic/commerce
slots (see that section's "Generator placeholder UIs" rule).
Write the block JS — blocks/<name>/<name>.js with a
decorate(block) function that reads authored rows and builds
the source DOM structure. Follow the decorator pattern in
block-level-conversion.md.
Write the block CSS — blocks/<name>/<name>.css with the
section-scoped CSS rules from the source. Include the
<name>-container / <name>-wrapper override for full-bleed.
For hybrid conversions, sections where level === "fragment" get
a static fragment + minimal loader instead (see
block-level-conversion.md §"Hybrid conversion").
Add the early return to buildHeroBlock if .hero exists as an
authored block. See block-level-conversion.md §"scripts.js
modifications".
Write drafts/<page-slug>.html as a full HTML document with all
blocks in DA canonical div-class format. See
block-level-conversion.md §"Drafts test page".
Write output/da/<page-slug>.html in the canonical DA body
fragment format (da-content, Page structure and Blocks). Structure:
<body>
<header></header>
<main>
<div>
<div class="hero">
<div><div><picture>...</picture></div></div>
<div><div>Eyebrow text</div></div>
<div><div><h1>Heading</h1></div></div>
<div><div>Description text</div></div>
<div><div>
<p><strong><a href="/cta">CTA Label</a></strong></p>
</div></div>
</div>
</div>
<!-- ... one section div per block ... -->
<div>
<div class="metadata">
<div><div>title</div><div>Page Title</div></div>
</div>
</div>
</main>
<footer></footer>
</body>No template metadata key — block-level pages don't use the
overlay engine. No slot-keyed rows — standard EDS positional
block tables.
DA cell image URLs must be absolute (same rule as page-level).
# 1) Each block has both .js and .css
for dir in blocks/*/; do
name=$(basename "$dir")
[ -f "$dir/$name.js" ] && [ -f "$dir/$name.css" ] \
|| echo "MISSING: $dir"
done
# 2) No relative "assets/" in block CSS or fragments
grep -rn '"assets/' blocks/ fragments/ && echo "FAIL" || echo "OK"
# 3) Lint passes
npm run lint
# 4) DA cell <img> URLs are absolute
grep -oE '<img[^>]*src="[^"]+"' output/da/*.html \
| grep -vE 'src="https?://' \
&& echo "FAIL: non-absolute DA img" || echo "OK"Then start the dev server and verify:
npx -y @adobe/aem-cli up --html-folder drafts --no-open
# Open http://localhost:3000/drafts/<page-slug> in a browser
# Check: zero console errors, all blocks render, visual matchSet state.phase = "generate", state.phaseStatus = "complete",
state.generateCompletedAt = "<timestamp>". Record:
state.conversionLevel = "block-level" (or "hybrid")state.blockCount — number of content blocks createdstate.fragmentCount — number of static fragments (header +
footer + any hybrid fallbacks)Continue to Phase 4 (Wire).
.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