updates and refinements to agents and claude context files

[shsteimer]

Description

Related Issue

Motivation and Context

How Has This Been Tested?

Screenshots (if appropriate):

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

• I have signed the Adobe Open Source CLA.
• My code follows the code style of this project.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have read the CONTRIBUTING document.
• I have added tests to cover my changes.
• All new and existing tests passed.

[aem-code-sync]

Hello, I'm the AEM Code Sync Bot and I will run some actions to deploy your branch and validate page speed.
In case there are problems, just click a checkbox below to rerun the respective action.

• Re-run PSI checks
• Re-sync branch

Commits

• cd3c150 ✅ (latest)
• ab0fb48 ✅
• 1e0fc3a ✅
• e30d838 ✅
• f79856e ✅
• 3623728 ✅
• 34f2067 ✅
• 0e91450 ✅
• 21288a1 ✅
• b43ac5b ✅
• 9b28e5b ✅
• 22da6e6 ✅
• c2a8543 ✅
• ac8badc ✅
• 905a882 ✅
• 7149776 ✅
• e14b9da ✅

[catalan-adobe]

@shsteimer, overall looks good to me. Two questions:

• first time I see addition of package-lock.json in skills scripts, is it to better control the versions? Make the install faster?
• I see you reduced SKILL files and moved content to resources files which look like a best practice, reducing the main file as much as possible. Could you check that the SKILLs are performing as good as before? Do the skills read the resource files whenever needed?

[shsteimer]

@shsteimer, overall looks good to me. Two questions:

• first time I see addition of package-lock.json in skills scripts, is it to better control the versions? Make the install faster?

Honestly, I debated on adding to .clade/skills/**/package-lock.json to .gitingnore or not. Ultimately, I just decided to let them be committed, following the practice for what we do with project level package/package-lock.json. I don't think it makes anything faster, all it does is pin the versions. But I don't have a strong opinion on if this is the right decision or not. maybe it's easier/better to not commit these?

• I see you reduced SKILL files and moved content to resources files which look like a best practice, reducing the main file as much as possible. Could you check that the SKILLs are performing as good as before? Do the skills read the resource files whenever needed?

So as I was testing I started to notice that agents would:

• very consistently follow the import-page workflow
• much less consistently follow the content-driven-development flow

this led me to additional refactoring I just comitted/pushed that takes inspiration from how the page-import flow works. it adds 2 new sub-skills, removes some redundant/unneccessary/extra info and resource files to try to keep things lighter. With this new flow in place I'm definitely seeing much better adherance to the CDD process across cursor, claude, and codex (honestly, if anything, I think codex and cursor with latest codex/sonnet/opus thinking models follow the workflow better than claude code, which is a first).

Will grab some conversation extracts and add them here soon to demonstrate.

[shsteimer]

@catalan-adobe you may notice I made an adjustment to the preview-import skill here. I noticed it pretty consistently struggled get deduce the write way to start aem up with --html-folder param. this change helps it do that much more often in my testing, but your thoughts/inputs/feedback there is more than welcome.

Here are 2 recent transcripts of me using these skills:

page import in cursor, full transcript:

cursor_import_webpage_to_our_site.md

building a block with Claude after the import (as summarized by claude)

Conversation Summary: Building a Featured-Article Block with Content Driven Development

  Initial Request

  Build a new featured-article block for an AEM Edge Delivery Services site, matching specific mobile and desktop designs provided via screenshots. Test content available at /us/en page.

  Skills Used (Orchestrated Workflow)

  The conversation demonstrated a complete Content Driven Development (CDD) workflow orchestrating multiple specialized skills:

  1. content-driven-development (Primary orchestrator)
    - Guided the entire 8-step workflow
    - Ensured content-first approach
    - Maintained progress tracking via TodoWrite tool
  2. analyze-and-plan (Step 2)
    - Performed systematic visual analysis of mobile/desktop screenshots
    - Identified all design requirements (layout, colors, typography, spacing)
    - Defined comprehensive acceptance criteria
    - Created analysis document for reference
  3. content-modeling (Step 3)
    - Designed author-friendly content model following AEM best practices
    - Used standalone block pattern (2 rows: image, content)
    - Validated against best practices (<4 cells/row, semantic formatting)
    - Documented content model with examples
  4. building-blocks (Step 5)
    - Created block directory structure
    - Implemented JavaScript decoration (flexible to handle 2 content structures)
    - Implemented mobile-first responsive CSS
    - Referenced existing blocks (hero, columns) for patterns
  5. testing-blocks (Step 5, invoked by building-blocks)
    - Ran linting (passed)
    - Browser validation via MCP Playwright tools
    - Captured screenshots at mobile (375px) and desktop (1200px)
    - Validated all acceptance criteria

  Workflow Executed

  Complete 8-step CDD process:
  1. ✅ Start dev server
  2. ✅ Analyze & plan (visual analysis, requirements, acceptance criteria)
  3. ✅ Design content model (standalone block, semantic formatting)
  4. ✅ Identify/create test content (local HTML test file)
  5. ✅ Implement (JavaScript + CSS)
  6. ✅ Lint & test (all checks passed)
  7. ✅ Final validation (all acceptance criteria met)
  8. ✅ Ship it (PR created with attribution)

  Key Capabilities Demonstrated

  1. Multi-skill orchestration:
  - CDD skill successfully coordinated 4 other skills
  - Each skill returned control to CDD at appropriate points
  - Clear handoffs with required context

  2. Visual analysis:
  - Systematic analysis of design screenshots
  - Extracted detailed requirements (layout, colors, typography, spacing)
  - Mapped to AEM implementation patterns

  3. Content modeling:
  - Applied canonical block model patterns (standalone)
  - Designed flexible structure supporting multiple authoring approaches
  - Validated against best practices

  4. Adaptive implementation:
  - JavaScript flexible enough to handle both 2-row and 1-row-2-col structures
  - Mobile-first responsive CSS
  - Reused existing DOM elements (pictures, headings)

  5. Comprehensive testing:
  - Linting via npm scripts
  - Browser validation via MCP Playwright
  - Screenshot capture for proof
  - Acceptance criteria validation

  6. Proper git workflow:
  - Feature branch creation
  - Conventional commit format with attribution
  - PR with descriptive body and validation checklist

  Success Metrics

  ✅ Complete success:
  - All 8 CDD steps completed
  - All acceptance criteria met
  - Block renders correctly on mobile and desktop
  - No console errors
  - Linting passed
  - PR created: https://github.com/shsteimer/aem-skills-demo/pull/2

  Deliverables:
  - blocks/featured-article/featured-article.js (92 lines)
  - blocks/featured-article/featured-article.css (177 lines)
  - Test content: drafts/tmp/featured-article-test.plain.html
  - Analysis: drafts/tmp/featured-article-analysis.md
  - Content model: drafts/tmp/featured-article-content-model.md
  - Screenshots: mobile and desktop validation

  Interesting Observations

  1. Mid-implementation correction:
  - User corrected content box positioning (bottom-left → bottom-center)
  - Skills adapted immediately, updating analysis and implementation

  2. Flexibility request:
  - User requested support for both content structures (2-row and 1-row-2-col)
  - JavaScript updated to detect and handle both patterns gracefully

  3. Documentation artifacts:
  - Skills created reusable reference documents (analysis, content model)
  - These serve as documentation for future development

  4. Content-first philosophy:
  - Created local test content BEFORE writing any code
  - Ensured implementation matched real content structure

  Challenges (Minor)

  1. Dev server restart required for local HTML testing
  2. Preview link requires CMS content (local HTML not available on preview environment)
  3. Minor permission issue with pkill command (easily resolved)

  Overall Assessment

  Highly successful demonstration of:
  - ✅ Multi-skill orchestration working seamlessly
  - ✅ Content Driven Development methodology
  - ✅ Systematic approach from analysis → design → implementation → testing → shipping
  - ✅ Proper AEM Edge Delivery patterns and best practices
  - ✅ Complete deliverable with validation and documentation
  - ✅ Professional git workflow with attribution

  Time efficiency:
  - Single conversation from requirements to PR
  - No backtracking or major rework needed
  - Skills provided appropriate guidance at each step

  Quality indicators:
  - All acceptance criteria validated
  - No console errors
  - Linting passed
  - Responsive across viewports
  - Follows AEM coding standards

  The skills demonstrated a mature, production-ready workflow suitable for real-world AEM development.

[trieloff]

looks good, I guess. I think we need to start thinking about more structured benchmarks.