CtrlK
BlogDocsLog inGet started
Tessl Logo
PluginPublic

adobe/aem-edge-delivery-services

Skills for building AEM Edge Delivery Services sites — site creation, block development, content modeling, code review, testing, and page import.

Quality

91%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

Overview
Quality
Evals
Security
Files

SKILL.mdskills/authoring-analysis/

name:
authoring-analysis
description:
Use this when the page-import pipeline needs to determine the authoring approach (default content vs blocks) for scraped content before generating import HTML for AEM Edge Delivery Services. Covers validating block selection and section styling for import/migration. Do not invoke directly — called by page-import as a pipeline step.
license:
Apache-2.0
metadata:
{"version":"1.0.3"}

Authoring Analysis

Determine authoring approach for EACH content sequence: default content or specific block.

When to Use This Skill

Use this skill when:

  • You have page structure with content sequences (from identify-page-structure)
  • You have block inventory (local + Block Collection)
  • Ready to make authoring decisions following David's Model

Invoked by: page-import skill (Step 3)

Prerequisites

From identify-page-structure skill, you need:

  • ✅ Section boundaries with styling notes
  • ✅ Content sequences per section (neutral descriptions)
  • ✅ Block inventory (local + Block Collection with purposes)
  • ✅ screenshot.png for visual reference

Related Skills

  • page-import - Orchestrator that invokes this skill
  • identify-page-structure - Provides section structure and block inventory
  • content-modeling - Owns the rules for default content vs block (Step 3a). Not invoked here; a block that does not exist yet is recorded as "new block needed" (Step 3b)
  • block-collection-and-party - This skill invokes it to validate blocks
  • generate-import-html - Uses this skill's output to create HTML

IMPORTANT: Step 3e Execution Trigger

After completing Step 3 (analyzing all sequences), you MUST execute Step 3e if:

  • ✅ At least one section contains exactly ONE sequence that became a block
  • ✅ That section has distinct background styling from identify-page-structure

If NO sections meet these criteria → Skip Step 3e If ANY sections meet these criteria → Execute Step 3e for EACH qualifying section

Authoring Analysis Workflow

Context: You now have:

  • Section boundaries with styles
  • Content sequences per section
  • Available block palette

FOR EACH content sequence, follow this mandatory process:


Step 3a: MANDATORY - Default Content Check (FIRST!)

Question: "Can an author create this with normal typing in Word/Google Docs?"

Default content means:

  • ✅ Headings, paragraphs, lists
  • ✅ Inline images within text
  • ✅ Simple quotes
  • ✅ Just... typing content

NOT default content means:

  • ❌ Repeating structured patterns (card grids, feature lists)
  • ❌ Interactive components (accordions, tabs, carousels)
  • ❌ Complex layouts (side-by-side columns, split content)
  • ❌ Requires specific structure for decoration

Rules and reasons: see content-modeling (never a text, heading or image block).

Decision:

  • If YES (can type normally) → Mark as DEFAULT CONTENT, DONE ✅
  • If NO (needs structure) → Proceed to Step 3b

Examples:

"Large centered heading, paragraph, two buttons"
→ Can author just type heading, paragraph, links? YES
→ Decision: DEFAULT CONTENT ✅

"Two centered buttons"
→ Can author just type two links? YES
→ Decision: DEFAULT CONTENT ✅

"Four items in grid, each with image, heading, description"
→ Can author just type this? NO - requires grid structure
→ Decision: Proceed to Step 3b ➡️

"Expandable questions and answers"
→ Can author just type this? NO - requires interaction/decoration
→ Decision: Proceed to Step 3b ➡️

Step 3b: Block Selection (ONLY IF NOT DEFAULT)

With block inventory context, ask: "Which available block would an author choose for this?"

Obvious match (pattern matches a block's purpose 1:1): use it.

  • "Grid of items with images/text" + "cards" block → USE IT ✅
  • "Expandable questions" + "accordion" block → USE IT ✅
  • "Tabbed content panels" + "tabs" block → USE IT ✅
  • "Side-by-side content" + "columns" block → USE IT ✅
  • "Rotating images" + "carousel" block → USE IT ✅

Several blocks could fit ("three items with images": cards or columns?; "customer quotes with photos": quote or cards?): compare the content with each candidate's authored structure (Step 3d) and pick the block whose structure fits the content without bending it. Note the runner-up and why in the output.

Content between two blocks ("hero-like content in the middle of the page", "card-like items but only two"): use the closest existing block and its variants. Note the mismatch in the output.

No block fits (content needs structure and nothing in the inventory has that shape): record NEW BLOCK NEEDED with the content description and why existing blocks do not fit. Do not design the block here: new blocks are built through content-driven-development, which uses content-modeling. Use the closest existing block in the import in the meantime, or default content if nothing is close.


Step 3c: Validate Block Exists (IF NEEDED)

Only if block not in Block Collection common set:

Invoke block-collection-and-party skill to:

  • Confirm block exists
  • Get live example URL
  • Review content model

Step 3d: Get Block HTML Structure (BEFORE generating HTML)

CRITICAL: Before generating any HTML in the next skill, read the authored (pre-decoration) structure of ALL blocks you will use. Append .plain.html to a page that shows the block:

# Block Collection example page
curl -s https://main--aem-block-collection--adobe.aem.live/block-collection/cards.plain.html

For a block in the project, use its page in the block library or a local test page (http://localhost:3000/<path>.plain.html).

Why this prevents mistakes:

  • Shows exact row/column structure (e.g., cards: each card = 1 row with 2 columns)
  • Reveals all variants (e.g., "Cards" vs "Cards (no images)")
  • Displays the markup without decoration
  • Prevents the #1 HTML generation error: wrong structure

Use the output to:

  1. Understand how many columns each row should have
  2. See where images vs content go
  3. Match your content to the correct variant
  4. Generate HTML that matches the expected structure exactly

Step 3 Output Format

Complete analysis for all sequences:

Section 1 (light):
  - Sequence 1: "Large centered heading, paragraph, two call-to-action buttons"
    → Decision: DEFAULT CONTENT
    → Reason: Author can type heading, paragraph, links normally
    → Note: Prominent styling is a CSS concern

  - Sequence 2: "Two images side-by-side"
    → Decision: Columns block (2 columns)
    → Reason: Side-by-side layout requires structure
    → Obvious match with "columns" block in inventory

Section 2 (light):
  - Sequence 1: "Centered heading"
    → Decision: DEFAULT CONTENT
    → Reason: Just a heading - author types it

  - Sequence 2: "Grid of 8 items, each with icon and short text"
    → Decision: Cards block
    → Reason: Repeating structured pattern, needs block
    → Obvious match with "cards" block in inventory

  - Sequence 3: "Two centered buttons"
    → Decision: DEFAULT CONTENT
    → Reason: Just two links - author types them

Section 3 (grey):
  - Sequence 1: "Eyebrow text, heading, paragraph, button stacked vertically"
    → Decision: DEFAULT CONTENT
    → Reason: Author types text and link normally

  - Sequence 2: "Four items in grid, each with image, category tag, heading, description"
    → Decision: Cards block
    → Reason: Repeating structured pattern
    → Obvious match with "cards" block in inventory

Section 4 (dark):
  - Sequence 1: "Tab navigation with three switchable content panels"
    → Decision: Tabs block
    → Reason: Interactive component, needs decoration
    → Obvious match with "tabs" block in inventory

Step 3e: Validate Section Styling (Single-Block Sections Only)

⚠️ EXECUTION TRIGGER: This step is executed AFTER Step 3 is complete. Execute this step if and only if:

  • ✅ You have completed Step 3 (identified which sequences become blocks)
  • ✅ At least one section contains exactly ONE sequence that became a block
  • ✅ That section has distinct background styling from identify-page-structure

If NO sections meet these criteria → Skip Step 3e entirely and proceed to next skill

If ANY sections meet these criteria → You MUST execute all sub-steps below for EACH qualifying section


Why this validation matters:

When a section contains a single block, the background styling might be:

  • Block-specific design (e.g., hero with dark background image) → Don't add section-metadata
  • Section container styling (e.g., dark section with tabs block) → Add section-metadata

Without validation, we risk adding unnecessary section-metadata that conflicts with block styling or makes authoring more complex.

Sections with multiple sequences: Always keep section-metadata (styling applies to all content, not validated in Step 3e)


For EACH section with exactly one block, execute ALL these sub-steps:

Sub-step 1: Identify the candidate sections

Review your Step 3 output. Find sections where:

  • Section contains exactly 1 content sequence
  • That sequence became a block (not default content)
  • Section has distinct background styling from identify-page-structure

Example:

Section 1 (dark blue):
  - Sequence 1: Large centered heading, paragraph, two buttons
    → Decision: Hero block

Section 3 (grey):
  - Sequence 1: Tab navigation with three switchable panels
    → Decision: Tabs block

Sub-step 2: For each candidate section, examine the screenshot

Open screenshot.png and examine the section visually.

Ask these questions:

Q1: Is the background an image (photo, gradient, illustration)?

  • If YES → Likely block-specific design
  • If NO (solid color) → Continue to Q2

Q2: Does the content fill the colored area edge-to-edge, or is there visible section padding?

  • Edge-to-edge (full-bleed) → Likely block-specific design
  • Visible padding around content → Likely section container styling

Q3: Does the block type typically have its own background styling?

  • Hero, banner, full-width CTAs → Often have own backgrounds
  • Tabs, accordion, cards, columns → Often use section backgrounds

Sub-step 3: Make the decision

Based on your analysis, decide for each single-block section:

SKIP section-metadata if:

  • Background is an image/gradient (block-specific)
  • Content is full-bleed/edge-to-edge (no section padding visible)
  • Block type typically has intrinsic background (hero, banner)

KEEP section-metadata if:

  • Background is solid color with visible section padding
  • Block type typically inherits section styling (tabs, cards, accordion)
  • Styling clearly provides container context (not block design)

Sub-step 4: Document your decisions

For each validated section, note:

  • Section number
  • Block type
  • Background analysis (image vs solid, full-bleed vs padded)
  • Decision (keep or skip section-metadata)
  • Reason

Example output:

VALIDATED SECTIONS:

Section 1 (dark blue):
  - Block: Hero
  - Background: Full-width dark blue gradient image
  - Layout: Edge-to-edge, no visible section padding
  - Decision: SKIP section-metadata
  - Reason: Background is hero's design, not section styling

Section 3 (grey):
  - Block: Tabs
  - Background: Solid grey (#f5f5f5)
  - Layout: Content centered with visible padding (~80px on sides)
  - Decision: KEEP section-metadata style="grey"
  - Reason: Section provides container styling for tabs block

When in doubt:

If you're uncertain whether background is block-specific or section-wide:

  • Default to KEEPING section-metadata (safer, easier for authors to remove than add)
  • Add a note in your documentation explaining the ambiguity
  • Consider asking the user for guidance

Step 3e Completion Checklist:

Before proceeding to next skill, verify you have completed:

  • ✅ Identified all single-block sections with background styling
  • ✅ Examined original screenshot for EACH candidate section
  • ✅ Answered Q1, Q2, Q3 for EACH candidate section
  • ✅ Made skip/keep decision for EACH candidate section
  • ✅ Documented reasoning for EACH decision
  • ✅ Updated section styling notes with validated decisions

Final Output

This skill provides complete authoring analysis:

1. Authoring decisions for all sequences:

  • Each sequence marked as DEFAULT CONTENT, a specific block name, or NEW BLOCK NEEDED
  • Reasoning documented

2. Block structures fetched:

  • HTML structure examples for all blocks to be used

3. Section styling validation (if applicable):

  • Updated section list with validated styling decisions
  • Some sections may be marked "no section-metadata"

Next step: Pass these outputs to generate-import-html skill

skills

authoring-analysis

README.md

tile.json