This skill guides you through creating new AEM Edge Delivery blocks or modifying existing ones, following Content Driven Development (CDD) principles. Blocks are the reusable building blocks of AEM sites - each transforms authored content into rich, interactive experiences through JavaScript decoration and CSS styling. This skill covers the complete development process: understanding content models, implementing decoration logic, applying styles, and maintaining code quality standards.
Related Skills
content-driven-development : MUST be invoked before using this skill to ensure content and content models are ready
block-collection-and-party : Use to find similar blocks for patterns
testing-blocks : Automatically invoked after implementation for comprehensive testing
When to Use This Skill
This skill should ONLY be invoked from the content-driven-development skill during Phase 2 (Implementation).
If you are not already following the CDD process:
STOP - Do not proceed with this skill
Invoke the content-driven-development skill first
The CDD skill will ensure test content and content models are ready before implementation
If not, we need to use the content-driven-development skill first."
If prerequisites are not met, STOP and invoke the content-driven-development skill.
If prerequisites are met, get the test content URL from the user and proceed to step 2.
2. Find Similar Blocks
For new blocks or major modifications:
Search the codebase for similar blocks that might provide useful patterns or code we can re-use
Use the block-collection-and-party skill to find relevant reference blocks
Review the implementation patterns in similar blocks to inform your approach.
For minor modifications to existing blocks: Skip to step 3.
3. Create or Modify Block Structure
For new blocks:
Create directory: blocks/{block-name}/
Create files: {block-name}.js and {block-name}.css
Use the boilerplate structure (or reference templates in resources/ if helpful):
JS file exports a default decorate(block) function (can be async if needed)
CSS file targets the .{block-name} class
For existing blocks:
Locate the existing block directory in blocks/{block-name}/
Review the current implementation before making changes
Understand the existing decoration logic and styles
4. Implement JavaScript Decoration
Follow patterns and conventions in resources/js-guidelines.md:
Use DOM APIs to transform the initial block HTML structure
Keep decoration logic focused and single-purpose
Handle variants appropriately (check block.classList for variant classes)
Follow established patterns from similar blocks
Readresources/js-guidelines.md for detailed examples, code standards, and best practices.
5. Add CSS Styling
Follow patterns and conventions in resources/css-guidelines.md:
All CSS selectors must be scoped to the block (start with .{block-name})
Use BEM-like naming within the block scope
Leverage CSS custom properties for theming
Write mobile-first responsive styles
Keep specificity low
Follow established patterns from similar blocks
Readresources/css-guidelines.md for detailed examples, code standards, and best practices.
6. Test the Implementation
After implementation is complete, invoke the testing-blocks skill:
The testing-blocks skill will guide you through:
Writing unit tests for any logic-heavy utilities
Browser testing to validate block behavior
Taking screenshots for validation and PR documentation
Running linting and fixing issues
Verifying GitHub checks pass
Provide the testing-blocks skill with:
Block name being tested
Test content URL (from CDD process)
Any variants that need testing
Return to this skill after testing is complete to proceed to step 7.
7. Document Block
Blocks require two types of documentation:
Developer Documentation
Most blocks are simple and self-contained and only need code comments for documentation
If a block is especially complex (has many variants, or especially complex code) consider adding a brief README.md in the block folder
Keep any README documentation very brief so it can be consumed at a glance
Author-Facing Documentation
Author-facing documentation helps content authors understand how to use the block in the CMS. This documentation typically exists as draft/library content in the CMS itself, not in the codebase.
When author documentation is needed:
Almost all blocks should have author-facing documentation. The only exceptions are:
Deprecated blocks that should no longer be used but can't be removed yet
Special-purpose blocks used very infrequently on a need-to-know basis
Auto-blocked blocks that shouldn't be used directly by authors
Maintaining author documentation:
Author documentation must be kept in sync with the block implementation:
Update when variants are added, removed, or modified
Update when the content structure changes
Update when block behavior or functionality changes
Where author documentation lives:
Different projects use different approaches for author documentation:
