adobe avatar

app-builder

Development, customization, testing, and deployment skills for Adobe App Builder projects, including the Workfront UI-extension suite (appbuilder-workfront)

version
1.0.0
GitHub stars
332

Install

/plugin install app-builder@adobe-skills

Run it inside Claude Code after adding the marketplace with /plugin marketplace add adobe/skills.

Contents

Discovered from source

Skills 10

App Builder Action Scaffolder

Full lifecycle skill for Adobe Runtime actions — scaffold, implement, deploy, and debug. Place action code at src/<extension-dir>/actions/<action-name>/index.js and register in src/<extension-dir>/ext.config.yaml.

Building a Workfront extension? The Workfront-specific action layer — the { data, error } response contract, IMS-token passthrough from the SPA, and Workfront's own Public API v21 — is in workfront-actions. Use this skill for generic action patterns, templates, and the App Builder SDKs.

Pattern Quick-Reference

Pick the template that matches the user's intent. Default to assets/action-boilerplate.js for generic actions.

User wantsTemplate
Simple action / generic starting pointassets/action-boilerplate.js
Minimal prototype (bare-bones)assets/action-scaffold-template.js
Database CRUD (durable records, indexes)assets/database-action-template.js
Webhook receiver (I/O Events)assets/event-webhook-template.js
Custom event providerassets/event-provider-template.js
Journaling consumer (replayable events)assets/journaling-consumer-template.js
Large payload response (>1 MB)assets/large-payload-template.js
Action sequence pipelineassets/action-sequence-template.js
Asset Compute worker (AEM renditions)assets/asset-compute-worker-template.js
Debug Runtime action issuesreferences/debugging.md

Fast Path (for clear requests)

When the user's request maps unambiguously to a single pattern above — they name a specific pattern, reference a template, or describe a use case that clearly matches one entry — skip straight to scaffolding. Use the matched template and proceed directly.

Examples of fast-path triggers:

  • "Add a webhook receiver action" → assets/event-webhook-template.js, scaffold directly
  • "Create an Asset Compute worker" → assets/asset-compute-worker-template.js, scaffold directly
  • "Add a database CRUD action" → assets/database-action-template.js, scaffold directly
  • "Add an action called process-order" (simple, no ambiguity) → assets/action-boilerplate.js, scaffold directly

If there is any ambiguity — multiple patterns could fit, constraints are unclear, or the user hasn't specified enough to pick a single approach — fall through to the full workflow below.

Quick Reference

  • Action entry point: Place action code at src/<extension-dir>/actions/<action-name>/index.js. This keeps paths aligned with the generated extension layout.
  • Manifest location: Register actions in src/<extension-dir>/ext.config.yaml. Do not put a root-level runtimeManifest in app.config.yaml; the CLI silently ignores it.
  • Extension directory name: The extension directory name varies by project template:
    • src/dx-excshell-1/ — Experience Cloud Shell SPA (default)
    • src/aem-cf-console-admin-1/ — AEM Content Fragment Console extension
    • src/dx-asset-compute-worker-1/ — Asset Compute worker Use the actual directory name from your project's app.config.yaml $include entries.
  • Web action response shape: Return { statusCode, body } for standard web actions; add headers only when needed.
  • Key CLI loop: aio app dev for local iteration (use aio app run if actions use State SDK, Files SDK, or sequences), aio rt action invoke for direct testing, aio app deploy for publishing.
  • State vs database: State for ephemeral job tracking; database for durable records, indexed queries, or document-style CRUD.
  • Events delivery choice: Webhook for push delivery, custom event provider to publish domain events, journaling consumer for replayability or back-pressure.
  • Large payload and sequence patterns: Large payload redirect when >1 MB response limit; action sequence for linear multi-action flows.
  • Asset Compute worker fit: Use for AEM rendition processing; different SDK and extension layout than standard Runtime actions.

Full Workflow (for ambiguous or complex requests)

  1. Confirm target outcome, constraints, and acceptance criteria.
  2. Collect current implementation context from code, environment, and Adobe configuration.
  3. Apply the detailed procedure in references/playbook.md for this capability.
  4. Produce implementation artifacts and validation evidence.
  5. Run through references/checklist.md before final handoff.
  6. Summarize decisions, risks, and immediate next actions.

Example User Prompts

  • "Add a new action to my App Builder project that calls the AEM Assets API."
  • "My runtime action is timing out after 60 seconds. How do I increase the limit without breaking the app?"
  • "Set up a cron action that runs every 5 minutes to sync data from an external API."
  • "Create a web action that accepts file uploads and stores them using the Files SDK."
  • "Store customer preferences in the App Builder Database."
  • "Set up a webhook to receive I/O Events for asset changes."
  • "My action response is too large — how do I handle payloads over 1MB?"

Inputs To Request

  • Current repository path and module boundaries
  • Target Adobe organization, project, and workspace
  • Non-functional constraints: latency, cost, compliance, and support model
  • Definition of done with measurable acceptance criteria

Deliverables

  • Implementation updates for the requested capability
  • Validation evidence: tests, checks, or reproducible verification steps
  • Handoff summary with explicit tradeoffs and follow-up actions

Quality Bar

  • Keep decisions explicit and traceable to project constraints
  • Prefer deterministic automation for repeatable steps
  • Fail safely with actionable diagnostics
  • Document tradeoffs and next-step risks in handoff notes

References

  • Use references/playbook.md for detailed execution guidance.
  • Use references/checklist.md for pre-handoff validation.
  • Use references/prompt-pack.md for ready-to-use execution prompts.
  • Use references/runtime-reference.md for action structure, params, response formats, SDK usage, and CLI operations.
  • Use references/aem-apis.md for AEM Content Fragment API surfaces — decision table, Delivery OpenAPI, Management OpenAPI, GraphQL persisted queries, and the deprecated Assets HTTP API — with auth patterns and action code for each.
  • Use references/action-patterns.md for common action patterns, including CRUD API, cron, multi-step processing, database CRUD, webhook intake, custom event providers, journaling consumers, large payload redirects, action sequence composition, and Asset Compute workers.
  • Use assets/database-action-template.js, assets/event-webhook-template.js, assets/event-provider-template.js, assets/journaling-consumer-template.js, assets/large-payload-template.js, assets/action-sequence-template.js, and assets/asset-compute-worker-template.js when the user request maps directly to one of the newer boilerplate patterns.
  • Use ../_shared/categories/architecture-runtime.md for Adobe service-specific guidance.

Common Manifest Guardrail

  • Keep App Builder action definitions under application.runtimeManifest in app.config.yaml.
  • Do not use root-level runtimeManifest; App Builder CLI ignores it for action configuration.
  • Validate manifest structure before deploy: python3 ../_shared/scripts/validate_manifest_structure.py <path-to-app.config.yaml>.
  • Use ../_shared/references/appbuilder-manifest-guardrail.md for valid and invalid examples.

Common Issues

  • Action deployment fails: Most deploy failures come from invalid manifest structure or missing dependencies. Check that actions are nested under application.runtimeManifest (or the extension ext.config.yaml pattern), run the manifest validator, run npm install, then retry aio app deploy.
  • Action timeout: Runtime execution defaults to 60 seconds and can be extended to 300 seconds for non-web actions. Reduce work per invocation, move long-running tasks to async/background flows, or raise the timeout in manifest limits when the action type supports it.
  • Payload too large: Web actions are limited to 1 MB for both request and response payloads. Trim request bodies, avoid returning large blobs inline, and use external storage or pass URLs instead.
  • IMS token not available / auth fails: If an action expects Adobe user context, set annotations.require-adobe-auth: true, confirm the shell or caller actually provides the token, and verify aio auth login plus Adobe project/workspace access for the target APIs.
  • Two-layer auth confusion: Actions can enforce auth at two independent layers — the require-adobe-auth: true manifest annotation (gateway-level rejection) and a code-level Authorization header check inside the action. Disabling one layer does not disable the other. During local dev, set require-adobe-auth: false and stub the code-level check; otherwise 401 errors persist across redeploy cycles. See references/runtime-reference.md § "Common Auth Issues" for the full debugging guide.

First-Wave Accelerator Kit

  • Use references/implementation-template.md to structure delivery artifacts for this high-frequency capability.
  • Run scripts/accelerator.py to generate an execution checklist from request context.

Asset Templates

  • assets/action-scaffold-template.js — Minimal scaffold for quick prototyping. Use this when you are starting from scratch, want the bare minimum action shape, or need to validate the basic params-in / response-out flow before adding production concerns.
  • assets/action-boilerplate.js — Production-ready template with logging, input validation, error handling, and response formatting. Use this when the action is meant for production use, shared team handoff, or any implementation that should start with observability and defensive defaults already in place.
  • assets/database-action-template.js — Durable database CRUD starter with collection initialization, indexes, and document-style operations.
  • assets/event-webhook-template.js — Adobe I/O Events webhook receiver with challenge handling, signature verification, and idempotent event processing.
  • assets/event-provider-template.js — Custom event provider starter for bootstrapping provider metadata and publishing domain events.
  • assets/journaling-consumer-template.js — Scheduled journaling consumer that polls the journal, stores the cursor, and processes replayable event batches.
  • assets/large-payload-template.js — large payload response starter that writes oversized responses to Files storage and returns a redirect URL.
  • assets/action-sequence-template.js — Starter manifest and action layout for a linear action sequence pipeline.
  • assets/asset-compute-worker-template.js — Asset Compute worker scaffold for AEM rendition processing with the Asset Compute SDK.

Agent Integration

  • The agents/ directory stores agent-platform integration metadata that complements the standard skill directories.
  • agents/openai.yaml defines the OpenAI-facing skill configuration, including the display name, short description, and default prompt used to invoke this skill in OpenAI-compatible agent experiences.
  • Keep the core skill instructions in SKILL.md; use agents/ only for platform-specific integration details.

App Builder CI/CD Pipeline

Set up CI/CD pipelines for Adobe App Builder projects — GitHub Actions (primary), Azure DevOps, GitLab CI. Uses OAuth S2S credentials with IMS authentication. Repository secrets only (no environment secrets).

Pattern Quick-Reference

User wantsTemplate
GitHub Actions deploy-to-stageassets/deploy-stage.yml
GitHub Actions deploy-to-prodassets/deploy-prod.yml
GitHub Actions PR testsassets/pr-test.yml
Extract secrets from workspaceassets/fetch-secrets.sh
Azure DevOps / GitLab CI / Jenkinsreferences/generic-pipeline-guide.md
Secrets setup guidereferences/secrets-management.md
Debugging deploy failuresreferences/debugging.md

Fast Path (for clear requests)

When the user says "set up CI/CD for my App Builder project" and they use GitHub, generate all 3 workflow files + secrets guide immediately:

  1. Copy assets/deploy-stage.yml → .github/workflows/deploy_stage.yml
  2. Copy assets/deploy-prod.yml → .github/workflows/deploy_prod.yml
  3. Copy assets/pr-test.yml → .github/workflows/pr_test.yml
  4. Guide secrets setup using references/secrets-management.md

If user specifies Azure DevOps, GitLab CI, or Jenkins → use references/generic-pipeline-guide.md.

Quick Reference

  • Workflow location: .github/workflows/ at repository root
  • Bootstrap command: aio app add ci generates starter workflow files
  • Official actions: adobe/aio-cli-setup-action@1.3.0 (CLI install) + adobe/aio-apps-action@4.1.0 (build/test/deploy)
  • Auth model: OAuth Server-to-Server (S2S) with IMS — the auth command in aio-apps-action is DEPRECATED (JWT). Do not use it.
  • Secrets scope: Repository secrets only. App Builder does NOT support GitHub environment secrets.
  • Secrets per workspace: 14 secrets with workspace suffix (_STAGE, _PROD)
  • Prerequisite: Add "I/O Management API" to each workspace in Developer Console before extracting secrets
  • Workspace config: Run aio app use <workspace.json> to configure .aio and .env files

Full Workflow (for ambiguous or complex requests)

  1. Check existing setup: Look for .github/workflows/ (from aio app add ci or manual). Check if workflows already exist.
  2. Determine CI/CD platform: GitHub Actions is default. Ask if user needs Azure DevOps, GitLab CI, or Jenkins.
  3. Generate workflow files: Copy templates from assets/ to .github/workflows/. Customize triggers, branch names, and environment suffixes as needed.
  4. **Guide secrets setup:**a. Ensure "I/O Management API" is added to the workspace in Developer Consoleb. Download workspace.json from Developer Consolec. Run aio app use <workspace.json> to configure local .aio and .envd. Run assets/fetch-secrets.sh to extract credential valuese. Guide user to add each secret to GitHub repository secrets (NOT environment secrets)f. Add _STAGE or _PROD suffix to each secret name
  5. Add custom secrets: If the app uses custom env vars, add them under the env key in the Deploy step
  6. Validate: Run through references/checklist.md before merge
  7. Troubleshoot: If deploy fails, consult references/debugging.md for common scenarios
  8. Test: Push to a branch and verify workflow runs successfully

Inputs To Request

  • Current repository path and CI/CD platform preference
  • Target Adobe organization, project, and workspace names
  • Whether Stage, Production, or both workspaces need CI/CD
  • Any custom secrets the application requires

Deliverables

  • Workflow YAML files in .github/workflows/
  • Secrets extraction output for repository configuration
  • Pre-merge validation against references/checklist.md

Quality Bar

  • All workflow YAML must be syntactically valid
  • Secrets must use repository scope, never environment scope
  • OAuth S2S credentials only — no JWT auth references
  • Each workspace gets its own secret set with correct suffix
  • Workflows must use pinned action versions (@3, @3.3.0)

References

  • Use references/github-actions-guide.md for GitHub Actions workflow patterns and secrets table.
  • Use references/generic-pipeline-guide.md for Azure DevOps, GitLab CI, and Jenkins patterns.
  • Use references/secrets-management.md for OAuth S2S credential extraction and GitHub secrets setup.
  • Use references/debugging.md for troubleshooting deploy failures, CI errors, and workspace promotion issues.
  • Use references/checklist.md for pre-merge CI readiness validation.
  • Use assets/deploy-stage.yml, assets/deploy-prod.yml, assets/pr-test.yml as workflow templates.
  • Use assets/fetch-secrets.sh to extract secret values from workspace configuration.
  • Official Adobe docs: https://developer.adobe.com/app-builder/docs/guides/app_builder_guides/deployment/cicd-using-github-actions

Common Issues

  • Workflow not triggering: Verify workflow files are committed to the default branch and triggers match your branching strategy.
  • Deploy fails with auth error: The auth command is deprecated. Ensure you are using OAuth S2S credentials, not JWT. Verify all 14 secrets are set correctly with the right workspace suffix.
  • "I/O Management API not found": Add the I/O Management API service to the workspace in Developer Console before extracting secrets.
  • Environment secrets not working: App Builder does NOT support GitHub environment secrets. Move all secrets to repository-level secrets.
  • Missing secrets: Run fetch-secrets.sh and compare output against the 14-secret table in references/github-actions-guide.md. Each value must be present and correctly suffixed.
  • Custom env vars not available in action: Add custom secrets under the env key in the Deploy step of the workflow, not just in GitHub secrets.

Chaining

  • Chains FROM appbuilder-action-scaffolder (after actions are implemented)
  • Chains FROM appbuilder-testing (automated test execution in CI)
  • Standalone after setup (workflows run automatically on push/PR/release)

App Builder E2E Testing

Playwright-based browser E2E testing for Adobe App Builder SPAs and AEM extensions. This skill generates Playwright configs, test files, and CI workflows for browser-level validation.

Pattern Quick-Reference

Identify the user's intent, then read the referenced sections to generate tailored tests.

User wantsReferenceAsset
E2E test for ExC Shell SPAreferences/e2e-testing-patterns.mdassets/playwright.config.ts, assets/e2e-test-template.spec.ts
Test AEM extension in browserreferences/aem-extension-testing.mdassets/playwright.config.ts
E2E tests in CI pipelinereferences/ci-integration.mdassets/e2e-ci-workflow.yml

Fast Path (for clear requests)

When the user says "add E2E tests" or "write Playwright tests" and intent is clear:

  1. Scan project for web-src/ (SPA) or @adobe/uix-guest in dependencies (AEM extension)
  2. Install Playwright if not present: npm install -D @playwright/test && npx playwright install chromium
  3. Generate playwright.config.ts from assets/playwright.config.ts
  4. For ExC Shell SPA: read references/e2e-testing-patterns.md, generate test with iframe navigation, shell wait, Spectrum ARIA selectors
  5. For AEM extension: read references/aem-extension-testing.md, generate test with Extension Tester URL, nested iframe handling, modal flows
  6. Run tests: npx playwright test
  7. If CI requested: generate GitHub Actions workflow from assets/e2e-ci-workflow.yml

Quick Reference

  • Test directory: e2e/ at project root (separate from Jest test/)
  • Config file: playwright.config.ts at project root
  • Install command: npm install -D @playwright/test && npx playwright install chromium (installs Playwright + Chromium browser)
  • Run command: npx playwright test (headless) or npx playwright test --headed (visible browser)
  • Debug command: npx playwright test --debug (step-through mode)
  • Report command: npx playwright show-report (open HTML report)
  • ExC Shell iframe: Access SPA inside shell via page.frameLocator('iframe') — exact selector varies, see references/e2e-testing-patterns.md
  • Spectrum selectors: Use ARIA roles, not CSS classes: getByRole('button', { name: 'Save' }), getByRole('grid'), getByRole('textbox')
  • Auth note: Full ExC Shell auth automation is complex — recommend testing against aio app dev (local) first. See references/e2e-testing-patterns.md § Authentication.
  • AEM extensions: Use Extension Tester URL with devMode=true. See references/aem-extension-testing.md.

Full Workflow (for ambiguous or complex requests)

  1. Scan project — Check for web-src/ (SPA), @adobe/uix-guest (AEM extension), existing test setup, app.config.yaml extension type
  2. Confirm scope — Which pages/flows to test? Local dev or deployed? CI needed?
  3. Install Playwright — npm install -D @playwright/test && npx playwright install chromium if not already installed
  4. Generate config — Copy and customize assets/playwright.config.ts for the project
  5. Generate test files — Read appropriate reference doc, generate tests matching project structure:
    • ExC Shell SPA → references/e2e-testing-patterns.md
    • AEM extension → references/aem-extension-testing.md
  6. Add action stubbing — If tests need deterministic backend responses, add page.route() intercepts
  7. Run and iterate — npx playwright test, fix selectors/timing as needed
  8. Add CI workflow — If requested, read references/ci-integration.md and generate workflow from assets/e2e-ci-workflow.yml
  9. Validate — All tests pass, use ARIA selectors, have assertions, no hardcoded waits

Inputs To Request

  • Current repository path and project type (SPA vs AEM extension)
  • Which pages or user flows need E2E coverage
  • Whether tests should run against local dev or deployed environment
  • Whether CI integration is needed

Deliverables

  • playwright.config.ts configured for the project
  • E2E test files in e2e/ directory
  • GitHub Actions workflow (if CI requested)
  • Passing test run output

Quality Bar

  • All tests use ARIA selectors (getByRole, getByLabel) — no CSS class selectors
  • Iframe navigation uses frameLocator() — no frame() with index
  • All tests have await expect() assertions — no assertion-free tests
  • Action responses are stubbed with page.route() for deterministic results
  • No hardcoded page.waitForTimeout() — use waitForSelector, waitForResponse, or Playwright auto-waiting
  • Tests run in < 60s on local machine

References

  • Use references/e2e-testing-patterns.md for Playwright E2E patterns for ExC Shell SPAs (iframe nav, Spectrum selectors, auth, action stubbing).
  • Use references/aem-extension-testing.md for AEM extension testing patterns (Extension Tester, nested iframes, modal lifecycle, extension points).
  • Use references/ci-integration.md for running Playwright in GitHub Actions (browser install, artifact upload, headless config).
  • Use assets/playwright.config.ts as the base Playwright configuration template.
  • Use assets/e2e-ci-workflow.yml as the GitHub Actions workflow template for E2E tests.

Common Issues

  • Iframe not found: The ExC Shell iframe selector varies — use DevTools to inspect. Try page.frameLocator('iframe[src*="your-app"]') or discover with page.frames().
  • Shell spinner never dismissed: Ensure runtime.done() is called in the SPA. For E2E, wait for content inside the iframe rather than the shell itself.
  • Spectrum component not clickable: React Spectrum components render ARIA roles — use getByRole() instead of CSS selectors. Check references/e2e-testing-patterns.md § Spectrum Selectors.
  • Auth popup blocks test: Test against local dev (aio app dev) which skips shell auth. See auth section in references/e2e-testing-patterns.md.
  • AEM extension not loading: Extension Tester requires IMS login. Use generous timeouts (10s+) for extension load. Check references/aem-extension-testing.md § Common Gotchas.
  • Tests flaky in CI: Add retries (retries: 1), use waitForResponse() for action calls, and check references/ci-integration.md for headless configuration.

Chaining

  • Chains FROM appbuilder-ui-scaffolder (after UI components are generated, add E2E tests)
  • Chains FROM appbuilder-testing (when user wants browser-level validation beyond Jest unit tests)
  • Chains TO appbuilder-cicd-pipeline (add E2E test job to CI/CD pipeline)

App Builder Project Initialization

Maps user intent to the right Adobe App Builder template and runs non-interactive aio app init. Default: @adobe/generator-app-excshell (SPA + actions). For headless/bare projects, use init-bare.

When the Developer Console project, workspace or API subscriptions don't exist yet, create them non-interactively with aio console … first (see Bootstrap below). Install the latest @adobe/aio-cli: its bundle has the non-interactive Console commands and aio app init --org/--project/--template-options.

Machine setup (first time)

Do this once per machine before initializing a project — plus a login per environment. If the CLI is already installed and you're logged in, skip to Bootstrap below.

1. Node 20

App Builder needs Node 20 (npm ships with it). Check what's active: node -v → expect v20.17 or later (@adobe/aio-cli 11 requires >=20.17.0).

  • Have nvm? nvm install 20 && nvm use 20 && nvm alias default 20 so new shells keep it. If several Node versions are installed, the active one must be 20.
  • No Node / no nvm? Ask the user before installing anything. Prefer brew install node@20 or the official installer at nodejs.org. If they want nvm, have them install it from nvm's instructions themselves; don't pipe an installer from the network into a shell. Once nvm is there, in a new shell:
    nvm install 20 && nvm use 20 && nvm alias default 20
    

Older Adobe docs say Node 18 — use 20. A global aio belongs to whichever Node was active when you ran npm i -g; if you switch Node versions the old aio won't be on PATH. Symptom of a mismatch: aio dies with SyntaxError: Unexpected token '??=' (a pre-20 Node parsing the Node-20 aio) — fix with nvm use 20 and reinstall aio there.

2. Install the aio CLI + log in

npm install -g @adobe/aio-cli      # on Node 20
aio login                          # opens a browser; `aio login -f` forces a fresh prompt
aio where                          # confirm the correct IMS org/context
aio console org list               # list orgs and their IDs (then `aio console org select <id>` if needed)

Tokens are stored by the CLI automatically; a normal aio login lasts hours/days — one login per session, not per command. Confirm the correct IMS org — wrong-org is the most common setup mistake.

3. Stage vs prod

The default environment is prod. To target stage, set the env var and re-authenticate:

export AIO_CLI_ENV=stage
aio logout && aio login

Unset the variable (or open a new shell) to return to prod. The stage CLI talks to the stage Console (developer-stage).

Logging in without a browser (CI / no human)

  • Import creds: in the Developer Console open the workspace → Download all → console.json, then aio app init <app> --import path/to/console.json (fills .env/.aio — treat console.json as a secret, gitignore it).
  • CI / pipeline: add an OAuth Server-to-Server credential to the workspace; aio and Runtime authenticate from the client id/secret with no human. Don't script SSO/MFA headlessly.

Bootstrap the Developer Console (project, workspace, APIs)

If the user is starting from zero — no Developer Console project yet, or an existing project that is missing a workspace or API subscription — bootstrap that state before aio app init. Otherwise aio app init / aio app use / aio app deploy have nothing to wire the local app to.

The bootstrap is plain aio console … commands; call them directly, not through a wrapper script, so you can branch on "already exists" or "needs a product profile". Follow references/bootstrap.md for the commands, the name-vs-ID rules and per-step recovery.

User stateNext action
"Create a project + workspace + add APIs from scratch"Run the bootstrap chain (project → workspace → APIs), then aio app init.
Project exists, workspace missingSkip project-create. Run aio console workspace create, then optionally aio console workspace api add.
Project + workspace exist, only need to add an APIRun aio console api list to discover service codes, then aio console workspace api add.
Everything already wiredSkip bootstrap. Go straight to Initialize via Script.
  • Inspect before you create (aio console project list --json, aio console workspace list, aio console workspace api list): create/add commands fail on "already exists" and have no upsert.
  • aio console project create already provisions Production and Stage workspaces; create a workspace only when you need another one.
  • A service that needs a product profile takes --license-config CODE=PROFILE on aio console workspace api add; ask the user or org admin for the profile name.
  • Wire the local app with --org/--project on init.sh init (below), or run aio app use --no-input in the project after init.

Fast Path (for clear requests)

When the user's intent maps unambiguously to a single template — for example, they name a template directly or describe an app that clearly matches exactly one entry below — skip straight to Initialize via Script below. Use the matched template and any project name the user provided (or a sensible default).

If there is any ambiguity — multiple templates could fit, or the user's constraints are unclear — use the full template decision table and workflow below.

Template Decision Table

Pick the template that matches the user's intent. When unclear, default to @adobe/generator-app-excshell.

User wantsTemplate
SPA with actions + React UI@adobe/generator-app-excshell
Content Hub extension (asset details panel, card action, bulk action)No generator — scaffold from sample app, see references/templates.md
AEM Content Fragment Console extension@adobe/aem-cf-admin-ui-ext-tpl
AEM React SPA (WKND-based)@adobe/generator-app-aem-react
Adobe API Mesh (GraphQL)@adobe/generator-app-api-mesh
Asset Compute custom worker@adobe/generator-app-asset-compute
Remote server on App Builder@adobe/generator-app-remote-mcp-server-generic
Bare / from-scratch project (no pre-scaffolded actions or UI)init.sh init-bare

For a headless/backend-only request, prefer init-bare when possible. If the user still needs a template that generates UI files, plan a post-init cleanup so the final project has no web-src frontend directory or web manifest wiring.

Initialize via Script

The aio app * wrappers go through a single script: scripts/init.sh. (Console bootstrap commands are called directly — see the Bootstrap section above for the rationale.)

Note: The path to this skill's scripts may be skills/, .augment/skills/, or .github/skills/ depending on your platform and repository layout. Adjust the prefix in the commands below accordingly.

With a template:

skills/appbuilder-project-init/scripts/init.sh init "@adobe/generator-app-excshell" ./my-project

With a template, fully wired to a specific Console org/project (no post-init aio app use needed):

skills/appbuilder-project-init/scripts/init.sh init \
  "@adobe/generator-app-excshell" ./my-project \
  --org <orgId> --project my-project

--org, --project, --template-options (base64-encoded JSON), and --no-config-validation are passed straight through to aio app init. Use the latest @adobe/aio-cli so they're all recognised; --no-config-validation is the escape hatch for the rare case where a partial scaffold shouldn't yet have to pass schema validation.

Bare project (no template):

skills/appbuilder-project-init/scripts/init.sh init-bare ./my-project

Use init-bare only when the user explicitly wants to configure everything from scratch. In that case, "bare" means the generated project should stay minimal:

  • app.config.yaml exists with an empty or minimal application.runtimeManifest
  • package.json exists with only the basic project dependencies
  • No pre-scaffolded src/, web-src/, or actions/ directories

The script outputs JSON with success, path, and output fields. Check success before proceeding.

Full Workflow (for ambiguous or complex requests)

Step 1 — Gather intent

Ask the user (or infer from conversation context):

QuestionExamples
What type of app?SPA shell, headless API, AEM extension, Asset Compute worker, API Mesh, remote server
Needs a UI?Yes (React Spectrum in ExC Shell), No (actions only)
Extension point?dx/excshell/1, aem/cf-console-admin/1, dx/asset-compute/worker/1, or N/A
Additional actions?Names and purposes of custom actions beyond the default
Console state?Existing project + workspace? Or do we need to create them and subscribe APIs first?
APIs needed?e.g. Adobe I/O Management, Analytics, Target — including any that require a product profile

If the Console state is "from scratch" or unknown, run the Bootstrap the Developer Console flow before continuing to template selection. See references/bootstrap.md for the full agentic bootstrap playbook.

Step 2 — Select template

Consult the Template Decision Table above and references/templates.md to map the user's intent to a template.

Step 3 — Initialize, customize, validate

Follow the Initialize via Script, Post-init customization, and Validate sections below.

Post-init Customization

Consult references/templates.md for template-specific post-init guidance. Common tasks:

  1. Install dependencies — Run npm install in the project directory. The init script uses --no-install to keep initialization fast, but dependencies are required before building or testing.
  2. For API Mesh projects, verify mesh.json is at the project root — After aio app init with @adobe/generator-app-api-mesh, confirm ./mesh.json exists before treating the scaffold as ready. If the file only exists at node_modules/@adobe/generator-app-api-mesh/templates/mesh.json, copy it into place with cp node_modules/@adobe/generator-app-api-mesh/templates/mesh.json ./mesh.json. The file under node_modules/ is the generator's template source, not the project's active API Mesh configuration. Then customize the root mesh.json with the user's real source handlers; for multi-backend scenarios, configure at least two handlers.
  3. Clean up bare-project scaffolding if needed — After init-bare, inspect the generated project. If the initializer created actions/, src/, or web-src/, remove those directories before continuing. A bare project should not keep auto-generated action code or web assets.
  4. Headless cleanup after template init — If the user wants a headless project with no frontend, delete any generated UI directory after aio app init: rm -rf web-src/ or the template-specific path such as rm -rf src/<extension>/web-src/. Then remove matching web-src config from app.config.yaml or ext.config.yaml if present, especially web: web-src and operations.view / impl: index.html entries. This avoids unnecessary frontend build artifacts and stale manifest wiring in a backend-only project.
  5. Add actions — If the user later wants custom actions, run cd ./my-project && skills/appbuilder-project-init/scripts/init.sh add-action "my-action".
  6. Add web assets — Only if the user later decides the bare project needs a UI, run skills/appbuilder-project-init/scripts/init.sh add-web-assets.
  7. Edit ext.config.yaml directly — Customize action definitions:
  • Set runtime: nodejs:22 for production. Stage workspaces also accept runtime: nodejs:24.
  • Add inputs: for environment variables the action needs
  • Set annotations.require-adobe-auth: true if the action needs IMS tokens
  • Set web: 'yes' or web: 'raw' depending on HTTP access needs
  1. Edit app.config.yaml — For multi-extension projects, add $include entries.
  2. Apply action boilerplate — Use the appbuilder-action-scaffolder skill's boilerplate pattern for production-ready action code with logging, input validation, and error handling.

Validate

Verify the project structure by checking these items directly:

  1. app.config.yaml** exists** and contains valid YAML
  2. All $include paths resolve to real files
  3. ext.config.yaml (if present) has runtimeManifest.packages with at least one action
  4. Action JS files exist at all declared function: paths
  5. package.json** exists** with name, version, and an Adobe SDK dependency (@adobe/aio-sdk or @adobe/aio-lib-core-logging)
  6. **No root-level **runtimeManifest in app.config.yaml (see Manifest guardrail below)

Read the relevant files and verify each check. Fix any issues before proceeding.

Build, Test, Deploy (optional)

If the user wants to go beyond scaffolding:

aio app build       # Build
aio app test        # Run tests
aio app deploy      # Deploy to Adobe I/O Runtime
aio app dev         # Run locally for development (use `aio app run` instead if actions use State SDK, Files SDK, or sequences)

Manifest guardrail

Extension projects: Actions are defined under runtimeManifest in ext.config.yaml, referenced via $include from app.config.yaml.

Standalone apps: Actions go under application.runtimeManifest in app.config.yaml.

Do not place a root-level runtimeManifest directly in app.config.yaml: the CLI ignores those actions, so they will not deploy. If you see this shape, move it under application.runtimeManifest or into ext.config.yaml.

Troubleshooting & Edge Cases

  • aio** CLI not installed:** If aio --version returns command not found or fails, stop before initialization. Ask the user to install Adobe I/O CLI, complete aio auth login, and retry only after the CLI is available.
  • npm install** fails after init:** The scaffold can still be created because init runs with --no-install, but builds/tests will fail until dependencies install cleanly. Capture the first package error, confirm the Node/npm version is compatible, rerun npm install from the project root, and only continue once it succeeds.
  • Template choice is ambiguous: If the request could map to multiple templates, ask one clarifying question about UI vs headless, extension point, or target Adobe product. If the user has no preference, default to @adobe/generator-app-excshell and state that assumption explicitly.
  • Project directory already exists or is not empty: Do not overwrite it silently. Ask whether to use a different directory, clear the existing folder, or initialize into a new path.
  • aio console …** subcommand or flag not recognised:** Almost always means the CLI bundle is stale. Run npm install -g @adobe/aio-cli and retry — that's the supported way to refresh every plugin (console, app, runtime, ims-oauth, telemetry). Only dig deeper if the same command still fails after a clean reinstall.
  • No org selected: Console bootstrap commands will fail with an org-selection error. Run aio console org list then aio console org select <orgId> (or pass --orgId to every command) before retrying.
  • Validation errors from a freshly scaffolded but partially edited project: aio app * commands validate app.config.yaml by default. Pass --no-config-validation to the single command you need to unblock, then drop it once the manifest is whole; never bake it into scripts. See references/debugging.md.
  • aio** commands die instantly with ERR_REQUIRE_ESM (exit 127):** A clean install can resolve @adobe/aio-cli-plugin-certificate to 2.2.0 (shipped as ESM), which the bundled CommonJS console lib cannot require() — every aio where / login / console command exits 127 with [ERR_REQUIRE_ESM] (though aio -v still prints a version, which is misleading). Pin the plugin to the last CommonJS 2.x inside the global package: cd "$(npm root -g)/@adobe/aio-cli" && npm install @adobe/aio-cli-plugin-certificate@2.1.0. Re-check after any aio update.
  • aio console org list** returns nothing / []:** Login succeeded but the org list is empty — almost always the wrong environment (internal Adobe/App Builder dev lives on stage, but the CLI defaults to prod). Switch: export AIO_CLI_ENV=stage && aio logout && aio login. If stage is also empty, it's an entitlement problem, not an environment one (needs an App Builder license and the user added under Admin Console → Users → Developers).
  • aio console project list** → 451 … accept developer terms:** The org's Adobe Developer Terms of Use haven't been accepted — a one-time, per-org acceptance the CLI can't do for you. Open the Developer Console (Stage https://developer-stage.adobe.com/console, Prod https://developer.adobe.com/console), confirm the correct org (top-right), accept the prompt, then re-run the command.

Chaining with other skills

After initialization, hand off to:

  • appbuilder-action-scaffolder — For scaffolding actions with playbook, checklist, boilerplate templates, and manifest validation
  • appbuilder-ui-scaffolder — Build React Spectrum UI for ExC Shell SPAs and AEM extensions

References

  • references/bootstrap.md — Agentic Developer Console bootstrap (project, workspace, API subscriptions) via raw aio console … commands from the latest @adobe/aio-cli
  • references/templates.md — Template catalog with intent mapping and per-template post-init guidance (includes the Content Hub extension)
  • references/debugging.md — Troubleshooting guide for init failures, Node/npm issues, login problems, and first-run errors

App Builder Testing

Generate and run Jest tests for Adobe App Builder actions and React Spectrum UI components. Scaffolds unit tests, integration tests, component tests, and mock helpers for Adobe SDKs.

Pattern Quick-Reference

Pick the template or reference that matches the user's intent. Default to assets/unit-test-template.js for generic test requests.

User wantsReferenceTemplate / Asset
Unit test for an existing actionreferences/testing-patterns.mdassets/unit-test-template.js
Integration test against deployed actionreferences/testing-patterns.mdassets/integration-test-template.js
Component test for React Spectrum UIreferences/component-testing-patterns.mdassets/component-test-template.js
Mock ExC Shell context in testsreferences/component-testing-patterns.mdassets/shell-mock-helper.js
Mock AEM extension context in testsreferences/component-testing-patterns.mdassets/uix-guest-mock-helper.js
Mock State SDK in testsreferences/mock-catalog.mdassets/mock-state-sdk.js
Mock Files SDK in testsreferences/mock-catalog.mdassets/mock-files-sdk.js
Mock Events SDK in testsreferences/mock-catalog.mdassets/mock-events-sdk.js
Mock Database SDK in testsreferences/mock-catalog.mdassets/mock-database-sdk.js
Full mock catalog (all SDKs)references/mock-catalog.md—
Contract test for API interactionsreferences/testing-patterns.md—
Pre-deployment verificationreferences/checklist.md—
Debug test failuresreferences/debugging.md—

Fast Path (for clear requests)

When the user's request maps unambiguously to a single pattern above — they name a specific test type, reference a template, or describe a use case that clearly matches one entry — skip straight to generation. Use the matched template and proceed directly.

Examples of fast-path triggers:

  • "Write tests for my action" → Read the action source, use assets/unit-test-template.js, generate immediately
  • "Help me mock State SDK" → Use assets/mock-state-sdk.js, inject into test file
  • "Add integration tests" → Use assets/integration-test-template.js, configure for deployed action
  • "Run tests with coverage" → Execute npx jest --coverage or aio app test
  • "Test my component/page/form/table" → Read the component source, use assets/component-test-template.js, wrap in Provider
  • "Mock shell context" → Use assets/shell-mock-helper.js, inject into test file
  • "Test my AEM extension component" → Use assets/uix-guest-mock-helper.js + assets/component-test-template.js

If there is any ambiguity — multiple test types needed, project structure unclear, or the user hasn't specified enough — fall through to the full workflow below.

Quick Reference

  • Test directory: Place test files in test/ mirroring the action path, e.g., test/actions/<action-name>/index.test.js.
  • Jest configuration: App Builder projects use Jest by default. Config lives in package.json or jest.config.js.
  • Test command: aio app test (wrapper) or npx jest --coverage (direct).
  • Mock pattern: Use jest.mock() at the top of test files to mock Adobe SDK dependencies before importing the action.
  • Response shape: All actions return { statusCode, body } — assert both in every test.
  • Error paths: Always test 200 (success), 400 (bad input), and 500 (SDK failure) scenarios.
  • CommonJS: Action test files use require() and module.exports (not ES imports).
  • Component test directory: test/web-src/components/<ComponentName>.test.js (or test/components/).
  • Provider wrapper: Always wrap in <Provider theme={defaultTheme}> — Spectrum renders nothing without it.
  • ARIA selectors: Use getByRole(), not CSS classes — see references/component-testing-patterns.md selector table.
  • Async testing: Use findBy* for data that appears async, queryBy* for absence, waitFor for state changes.

Full Workflow (for ambiguous or complex requests)

  1. Scan project structure — Check for existing test/ directory, jest.config.js, and test scripts in package.json. Scan both src/ for actions AND web-src/ for UI components.
  2. Identify targets to test — Parse ext.config.yaml (or app.config.yaml) for declared actions and their source paths. Check web-src/src/components/ for React components.
  3. Determine test types needed — Unit tests for logic, integration tests for deployed actions, contract tests for API interactions.
  4. **For each action:**a. Read the action source to identify SDK dependencies (State, Files, Events, Logger, etc.).b. Generate unit test using assets/unit-test-template.js as the base.c. Inject appropriate mocks from references/mock-catalog.md based on detected dependencies.d. Add error scenario tests (missing params, auth failures, SDK errors).
  5. **For each UI component:**a. Read the component source to identify dependencies (shell context, UIX guest, action calls).b. Generate component test using assets/component-test-template.js as the base.c. Wrap all renders in <Provider theme={defaultTheme}> — Spectrum renders nothing without it.d. Inject shell mock (assets/shell-mock-helper.js) or UIX guest mock (assets/uix-guest-mock-helper.js) as needed.e. Add loading, success, and error state tests for async data using findBy* and waitFor.
  6. Run tests — Execute aio app test or npx jest --coverage and report results.
  7. Validate — Check against references/checklist.md before marking done.

Example User Prompts

  • "Write unit tests for my generic action"
  • "Add integration tests for my deployed action"
  • "My action uses State SDK — help me mock it in tests"
  • "Run tests and show me coverage"
  • "Set up Jest for my App Builder project"
  • "Test my action handles errors properly"
  • "Write component tests for my data table page"
  • "Test my AEM extension panel component"
  • "Help me mock shell context in my tests"
  • "Add tests for my React Spectrum form"

Inputs To Request

  • Current repository path and action file locations
  • Which actions need tests (or test all declared actions)
  • Target test types: unit, integration, contract, or all
  • Whether action is deployed (needed for integration tests)

Deliverables

  • Test files in test/ matching the action directory structure
  • Component test files in test/web-src/components/ for UI components
  • Mock helpers for detected Adobe SDK dependencies
  • Shell or UIX Guest mock helpers when components depend on context SDKs
  • Jest configuration if not already present (including jsdom environment for component tests)
  • Coverage report from test execution

Quality Bar

  • Every action test covers at minimum: success (200), bad input (400), and SDK failure (500) paths
  • Mocks are isolated per test via beforeEach(() => jest.clearAllMocks())
  • No real SDK calls in unit tests — all external dependencies are mocked
  • Tests are deterministic and can run offline (no network dependencies in unit tests)
  • Coverage reporting is enabled (--coverage flag)
  • All component tests wrap in <Provider theme={defaultTheme}> — Spectrum renders nothing without it

References

  • Use references/testing-patterns.md for unit, integration, and contract test patterns with annotated examples.
  • Use references/component-testing-patterns.md for React Spectrum component testing with Provider wrapping, ARIA selectors, and async patterns.
  • Use references/mock-catalog.md for mock helpers covering all Adobe SDKs (State, Files, Events, Logger, Database, Shell, UIX Guest).
  • Use references/checklist.md for pre-deployment test verification.
  • Use assets/unit-test-template.js for Jest unit test boilerplate (CommonJS).
  • Use assets/integration-test-template.js for integration test against deployed actions.
  • Use assets/component-test-template.js for React Spectrum component test boilerplate with renderWithSpectrum() helper.
  • Use assets/shell-mock-helper.js for ExC Shell context mock (@adobe/exc-app).
  • Use assets/uix-guest-mock-helper.js for AEM UIX Guest mock (@adobe/uix-guest).
  • Use assets/mock-state-sdk.js, assets/mock-files-sdk.js, assets/mock-events-sdk.js, and assets/mock-database-sdk.js for ready-to-use SDK mock setups.

Common Issues

  • Tests fail with "Cannot find module": Ensure the action path in require() matches the actual file location. App Builder actions are typically at src/dx-excshell-1/actions/<name>/index.js.
  • Mocks not working: jest.mock() calls must appear before require() of the module under test. Jest hoists mock declarations but order still matters for manual mocks.
  • State/Files SDK tests fail: These SDKs require Runtime environment for real calls. Always mock them in unit tests. Use aio app run (not aio app dev) for integration tests that need real SDK access.
  • Coverage too low: Add tests for error branches — missing params, invalid auth headers, SDK init() failures, and timeout scenarios.
  • aio app test** vs npx jest:** aio app test is a thin wrapper around Jest. Use npx jest --coverage directly for more control over flags and reporters.
  • Spectrum components render blank in tests: Missing <Provider theme={defaultTheme}> wrapper. Use renderWithSpectrum() helper from assets/component-test-template.js.
  • ARIA role queries return null: Spectrum components use ARIA roles, not CSS classes. See references/component-testing-patterns.md section g for the role reference table.

Chaining

  • Chains FROM appbuilder-action-scaffolder (test actions after implementation)
  • Chains FROM appbuilder-ui-scaffolder (test UI components after scaffolding)
  • Chains TO appbuilder-cicd-pipeline (automated test execution in CI)

App Builder UI Scaffolder

Generate React Spectrum UI for Adobe Experience Cloud Shell SPAs. This is a reference-based skill — the agent reads patterns and generates context-appropriate code rather than copying static templates.

Building a Workfront extension UI? The Workfront extension points (Main Menu, per-object left panel, custom-form widgets) and the Workfront shared context live in workfront-ui-extension. Use this skill for the generic Spectrum component patterns (pages, forms, tables, dialogs, navigation) it calls into.

Pattern Quick-Reference

Identify the user's intent, then read the referenced sections to generate tailored code.

User wantsReferenceKey components
New page with shell contextreferences/ui-patterns.md § Page + references/shell-integration.mdView, Heading, Content
Form with validationreferences/ui-patterns.md § FormForm, TextField, NumberField, Picker, Button
Data table (sortable, paginated)references/ui-patterns.md § TableTableView, TableHeader, Column, TableBody, Row, Cell
Confirmation dialog / modalreferences/ui-patterns.md § DialogDialogTrigger, AlertDialog, Dialog
Navigation layoutreferences/ui-patterns.md § NavigationTabs, Breadcrumbs, Flex
ExC Shell setupreferences/shell-integration.md@adobe/exc-app, Provider, defaultTheme
Connect UI to backend actionsreferences/action-integration.mdfetch() with IMS token
AEM UI Extension (CF Console, CF Editor, Universal Editor, Assets View)references/aem-extensions.md@adobe/uix-guest, register(), sharedContext
Content Hub extension (panels, card actions, bulk actions)references/aem-extensions.md § Content Hub@adobe/uix-guest, register(), attach(), assetDetails/card/selectionBar namespaces, host.modal.openDialog
Debug UI issuesreferences/debugging.mdShell spinner, CORS, blank screen, auth

Fast Path (for clear requests)

When the user's request maps unambiguously to a single pattern above — they name a specific component type, reference a UI pattern, or describe a use case that clearly matches one entry — proceed directly:

  1. Read the user's existing project structure (web-src/src/) for conventions (file naming, import style, existing components)
  2. Read the matched references/ file for component guidance and annotated examples
  3. Generate code that fits the user's existing conventions
  4. Wire into existing routing if React Router is present
  5. Validate against references/checklist.md

Examples of fast-path triggers:

  • "Add a data table page" → Read references/ui-patterns.md § Table, generate directly

  • "Create a form for submitting data" → Read references/ui-patterns.md § Form, generate directly

  • "Add a confirmation dialog" → Read references/ui-patterns.md § Dialog, generate directly

  • "Set up the shell integration" → Read references/shell-integration.md, generate directly

  • "Build a Content Fragment Console extension" → Read references/aem-extensions.md § CF Console, generate directly

  • "Add a header menu button to the Universal Editor" → Read references/aem-extensions.md § Universal Editor, generate directly

  • "Create an AEM extension with uix-guest" → Read references/aem-extensions.md § Core Registration, generate directly

  • "Add a Content Hub panel / card action / bulk action" → Read references/aem-extensions.md § Content Hub, generate directly

  • "Create / scaffold a new extension from scratch" → Redirect to the appbuilder-project-init skill (Console setup, template selection, file generation, dev server)

If there is any ambiguity — multiple patterns could fit, constraints are unclear, or the user hasn't specified enough — fall through to the full workflow below.

Quick Reference

  • UI entry point: Place components in web-src/src/components/. This is the standard App Builder SPA layout.
  • Shell integration: Always initialize with @adobe/exc-app and call runtime.done() to dismiss the loading spinner. See references/shell-integration.md.
  • Spectrum imports: All components from @adobe/react-spectrum. See references/spectrum-components.md for the full catalog.
  • Routing: Use react-router-dom for SPA navigation within the shell. See references/routing-patterns.md.
  • Backend calls: Pass the shell's IMS token when calling App Builder actions. See references/action-integration.md.
  • Theming: Wrap the app in <Provider theme={defaultTheme}> for Spectrum styling.
  • Accessibility: All Spectrum components have built-in ARIA support. Add labels to interactive elements. See references/checklist.md.
  • Debugging: For common issues (blank screen, CORS errors, auth failures, slow loads), see references/debugging.md.

Full Workflow (for ambiguous or complex requests)

  1. Read the user's project — check web-src/ structure, React version, existing imports, routing setup, app.config.yaml for extension type
  2. Confirm target outcome, constraints, and acceptance criteria with the user
  3. Identify the UI pattern(s) needed from the quick-reference table above
  4. Read the corresponding references/ files for component guidance and annotated examples
  5. Generate code that fits the user's existing conventions (not a generic template)
  6. Wire into existing routing if React Router is present (references/routing-patterns.md)
  7. Connect to backend actions if data fetching is needed (references/action-integration.md)
  8. Validate against references/checklist.md before marking done
  9. If the user reports issues, consult references/debugging.md for common SPA debugging scenarios
  10. Summarize decisions, component choices, and any follow-up actions

Example User Prompts

  • "Add a page to my App Builder SPA that shows a data table."
  • "Create a form for submitting customer data in my App Builder app."
  • "Set up the Experience Cloud Shell integration for my App Builder app."
  • "Add a confirmation dialog before deleting a record."
  • "Build a navigation sidebar for my App Builder SPA."
  • "My App Builder app needs a settings page with form fields."
  • "Build a Content Fragment Console extension with an action bar button."
  • "Add a custom RTE toolbar button in the Content Fragment Editor."
  • "Create a Universal Editor extension with a header menu button."
  • "Add a custom panel to the Content Hub Asset Details Dialog."
  • "Build a Content Hub extension."
  • "Add an action button to Content Hub asset cards."
  • "Add a bulk action to the Content Hub selection bar."
  • "Customize the Content Hub extension UI."

Inputs To Request

  • Current repository path and web-src/ structure
  • Target UI pattern and specific data requirements
  • Existing routing setup (if any)
  • Backend action URLs for data fetching (if applicable)
  • Non-functional constraints: accessibility requirements, responsive breakpoints

Deliverables

  • React Spectrum component files matching the user's project conventions
  • Updated routing configuration (if applicable)
  • Integration with backend actions (if applicable)
  • Validation against quality checklist

Quality Bar

  • All generated components use React Spectrum — no custom CSS for standard patterns
  • Shell integration includes runtime.done() call
  • Interactive elements have accessible labels
  • Loading and error states are handled
  • IMS token passed correctly to backend action calls

References

  • Use references/ui-patterns.md for annotated UI pattern examples (page, form, table, dialog, navigation).
  • Use references/spectrum-components.md for React Spectrum v3 component catalog with imports, props, and accessibility.
  • Use references/shell-integration.md for ExC Shell integration (@adobe/exc-app, runtime.done(), IMS tokens).
  • Use references/routing-patterns.md for SPA routing with React Router in ExC Shell.
  • Use references/action-integration.md for calling backend actions from the SPA.
  • Use references/checklist.md for pre-handoff UI quality validation.
  • Use references/aem-extensions.md for AEM UI Extension patterns (@adobe/uix-guest) — Content Fragment Console/Editor, Universal Editor, Assets View, and Content Hub.
  • Use references/debugging.md for common SPA debugging scenarios (shell spinner, CORS, auth, blank screen, performance).

Chaining

  • Chains FROM appbuilder-project-init — once the extension is scaffolded and running locally, this skill handles UI customization and React Spectrum patterns
  • Works alongside appbuilder-action-scaffolder for full-stack features (UI calls backend actions)
  • Chains TO appbuilder-testing (test generated UI components)
  • Chains TO appbuilder-cicd-pipeline (deploy frontend changes)

Workfront UI extensions on App Builder

A customized Workfront UI, built as an App Builder app. It has two halves:

  • a front end — the screens the user sees. Built with React/Spectrum (Adobe's UI toolkit); in App Builder terms it's the SPA ("single-page app"). → workfront-ui-extension
  • a back end — small functions that run in Adobe's cloud (Runtime actions; "serverless" = you write the function, Adobe runs it, no server to manage). They hold the credentials and call the Workfront / Planning / Adobe APIs. → workfront-actions

The front end plugs into Workfront at fixed spots called extension points: a Main Menu button, an item in an object's left panel, or a widget embedded inside a custom form.

End-to-end flow → which skill

StepWhat you doSkill
0–1. Set up + create projectNode 20, install @adobe/aio-cli, aio login, pick IMS org, stage vs prod, create the project (Developer Console or aio console project create)appbuilder-project-init
2. Scaffoldaio app init with template @adobe/workfront-ui-ext-tpl; pick extension pointsappbuilder-project-init + this skill's references/commands.md
3. Build front endExtension points (Main Menu, secondaryNav, widgets), routing, shared context, actionWebInvokeworkfront-ui-extension
4. Build back endAction anatomy, config, auth, inputs; call Workfront (Public API v21) / Planning / servicesworkfront-actions
5. Run + test in Workfrontaio app dev, then extensionOverride (local build) or Extension Manager / BYO (deployed app, no publish)workfront-local-testing
6. Deployaio app deployreferences/commands.md
7. Publish (org-wide)Submit for approval from the Production workspace; make sure Production has every API/service your actions need. Not required for BYO/override testing.— (see below)

Publishing makes the app available to everyone in the IMS org without an extensionOverride. Deploy from the Production workspace (aio app deploy), then submit for approval in the Developer Console / App Builder distribution UI (guide: https://developer.adobe.com/uix/docs/guides/publication/). To use a deployed app in one org without approval, register its URL in Workfront's Extension Manager (Bring Your Own extension) instead — see workfront-local-testing. After deploy, the app's direct link is the Experience Cloud shell URL …/workfront/custom-applications/<extensionId>/<menuRoute> (not the bare CDN) — build and hand it over per workfront-local-testing.

Hit a wall? A symptom → cause → fix table of the real gotchas (Node/aio errors, the Main Menu id trap, 401 Org Id undefined, BYO testing, and more) is in references/troubleshooting.md. The full aio command catalog is in references/commands.md.

Plain-language glossary

TermIn plain words
SPA / front endThe app screens the user sees inside Workfront.
Runtime action / "serverless"A small function in Adobe's cloud that does the real work (fetching/saving data) and keeps credentials off the user's browser.
Extension pointA spot where your app appears in Workfront: the Main Menu, an object's left panel, or a custom-form widget.
Shared contextInfo Workfront hands the app automatically — who's signed in, which object they're on, the instance URL.
actionWebInvokeHow the front end calls a back-end action.
IMS orgYour Adobe organization (identity / login).
Developer Console / workspaceAdobe's web admin where the project and its Production / Stage environments live.
Layout templateThe Workfront admin setting that decides where an app actually shows up for users.

Invariants for the whole family

  • Auth comes from sharedContext (imsToken, hostname) — Workfront hands the app the signed-in user and instance, so never build a custom login.
  • The browser never calls Workfront/Adobe APIs directly — always through a Runtime action via actionWebInvoke, so login tokens stay on the server. (The IMS org id is already in sharedContext at auth.imsOrgID — no WF call needed.)
  • Actions are CommonJS (exports.main; not ESM); secrets/inputs flow .env → action inputs → params, and are never read from process.env at runtime.
  • Node 20. The default environment is prod (live); targeting stage (test) needs AIO_CLI_ENV=stage plus a re-login.
  • Workfront Public API is v21.0; custom DE: fields need {field}_Mod=notblank on search/count.

Workfront Runtime actions

Actions are the back end — small functions Adobe runs in its cloud on demand ("serverless"; Adobe I/O Runtime, built on OpenWhisk). The front end (SPA, see workfront-ui-extension) calls them via actionWebInvoke; they hold the credentials and call external APIs. The browser must never call Workfront/Adobe APIs directly — that is the action's job, so login tokens never reach the user's browser.

For generic action patterns and templates (webhook receiver, database CRUD, custom event provider, journaling consumer, large-payload redirect, action sequence, Asset Compute worker) and the App Builder SDKs (State/Files/Events/DB), use appbuilder-action-scaffolder. This skill is the Workfront-specific layer: the {data,error} contract, IMS passthrough, and Workfront's own Public API.

Anatomy

actions/<name>/index.js     # exports main(params)
  • CommonJS only — export your function as exports.main. (App Builder supports only CommonJS, not ES Modules.)
  • Register every action in app.config.yaml, or in an extension's ext.config.yaml (which compiles into app.config.yaml), following the OpenWhisk wskdeploy YAML spec.
async function main (params) {
  // ...
  return { statusCode: 200, body: { data, error: null } }
}
exports.main = main

Response shape

Always return { data, error } in the body; the UI checks error before using data.

return { statusCode: 400, body: { data: null, error: 'missing parameter(s) ...' } }

Auth & inputs

  • require-adobe-auth is a per-action choice, off by default (the platform default) — decide deliberately, don't blanket-enable it. When true, Adobe validates the user's IMS token at the gateway before your code runs.
    • Turn it on when the action itself is the security boundary (privileged work, or nothing downstream authorizes the caller).
    • Leave it off when the downstream API enforces its own authorization — e.g. the action just forwards the user's imsToken to Workfront/Planning, which rejects bad tokens — or unless explicitly asked to enable it.
  • The UI passes imsToken (→ Authorization: Bearer …) and the Workfront instance URL as params; never hardcode them.
  • The IMS org id is in the shared context at auth.imsOrgID (capital ID — not imsOrgId/imsOrg; that casing trap costs hours). The front end reads sharedContext.get('auth').imsOrgID and passes it down; the action uses params.imsOrgId / the x-gw-ims-org-id header. Two traps: (1) reject the strings "undefined"/"null"/empty — an empty front-end value becomes the header string "undefined" (→ 401 "Org Id undefined is not in the list of user org Ids"); (2) with require-adobe-auth: true the gateway validates the org header before your code runs.
  • Inputs flow .env → action inputs (in config) → params. Do NOT read process.env at runtime. Under aio app dev actions run in-process, so process.env may appear to work locally but will be empty once deployed. Wire keys/secrets as inputs and read them from params.

Calling external APIs (the pattern)

For any API — Workfront, Planning, Adobe services:

  1. Receive imsToken plus any apiKey / IDs as params.
  2. fetch the public REST endpoint with Authorization: Bearer <imsToken> (add x-api-key / x-gw-ims-org-id where required).
  3. Map the result to { data, error }. Never log the token.
  • Workfront Planning → verify the Workfront MCP is connected, then fetch the v2 endpoint reference and data from it (details in references/integrations.md); if it isn't connected, stop and tell the user to connect the Workfront MCP before continuing. Other Adobe services → references/integrations.md. Confirm endpoints from the live source rather than guessing.

Workfront Public API v21.0

Workfront's own REST API — the /attask/api/v21.0 layer. Call it from an action (never from the SPA).

  • wfClient / base URL: {workFrontInstanceUrl}/attask/api/v21.0{path} — a single version constant. workFrontInstanceUrl and imsToken arrive as params (never hardcoded).
  • Search / count objects (projects, tasks, issues) via the documented query params; map the response into { data, error }.
  • Custom DE: fields need {field}_Mod=notblank on search/count, or they are silently omitted from results.
  • Bulk update with PUT /{obj}?updates=[...] (the updates array in the query string) — chunk requests to stay under the ~8 KB URL-length limit; fall back to per-record PUT /{obj}/{ID} when a chunk is still too long.
  • Wrap the calls in a small wfFetch helper; register the action in app.config.yaml; the SPA reaches it via actionWebInvoke only.

Time budget

The action the SPA calls via actionWebInvoke is a web action, so it's bound by Adobe I/O Runtime's 60 s cap on web/blocking actions — raising limits.timeout doesn't lift it (full limits table in appbuilder-action-scaffolder). So don't fetch or process a big dataset in one call: page Workfront search and chunk bulk-PUT work across multiple actionWebInvoke calls (see Workfront Public API v21.0 above), and show partial progress from the UI. A user-facing timeout is a candidate action-timeout, but can equally be a slow CDN/static load, cold start, or downstream API — check aio app logs before concluding.

Add a new action

  1. aio app add action (or hand-create actions/<name>/index.js).
  2. Register it in app.config.yaml / ext.config.yaml with a runtime kind (e.g. runtime: nodejs:20) and its inputs; set require-adobe-auth per the Auth & inputs rule above. runtime is mandatory — deploy fails with Invalid or missing property "runtime" without it (and, when require-adobe-auth is on, the same error fires on the generated __secured_<action> wrapper).
  3. Expose its URL to the SPA (the UI reads injected action URLs — never hardcodes them). See workfront-ui-extension.
  4. Add tests under test/actions/; run aio app test. View logs with aio app logs (command catalog: appbuilder-workfront → references/commands.md).
  5. Deploy with aio app deploy. A ready-to-edit starting point is in assets/action-boilerplate.js.

Test a local extension inside Workfront

After aio app dev (command catalog in appbuilder-workfront → references/commands.md) you have a localhost URL. This makes Workfront load your local app instead of (or alongside) published ones — no deploy required.

1. extensionOverride (the key step)

In the browser, on your Workfront tab (*.workfront.com or *.workfront.adobe.com): DevTools → Application → Local Storage → add an entry:

  • key: extensionOverride
  • value: your dev URL, e.g. https://localhost:9080

Take the exact URL/port from the aio app dev output. Reload the layout-template page — your extension's buttons/widgets appear.

For custom-form widgets, the widget picker lists locally-active apps when the override is set (surfaced as extensionoverride=TRUE).

Deployed app, no publish? Extension Manager (Bring Your Own)

extensionOverride points Workfront at a local (localhost) build. To use a deployed app (its CDN URL) in an org without the prod publish + approval process, register it in Extension Manager:

Workfront → Extension Manager — always give the user the direct link (pick the org in the switcher if @<org> differs):

  • Stage: https://experience-stage.adobe.com/#/@<org>/workfront/extension-manager
  • Prod: https://experience.adobe.com/#/@<org>/workfront/extension-manager

(If the org has more than one Workfront instance, the shell scopes the link with a so:<instance> segment before /workfront/ — …/@<org>/so:<instance>/workfront/extension-manager. If the link lands on the wrong instance, copy @<org>/so:<instance> verbatim from a Workfront page you're already on.)

→ Bring Your Own extension, then fill in (always list these fields):

  • Extension Url — the deployed app's index.html, e.g. https://<namespace>.dev.runtime.adobe.io/index.html
  • Extension Name, Description, Support Email

Save, then toggle it on under Installed Extensions — it defaults to Disabled. No cert / Chrome-flag hassle (it's a real HTTPS CDN URL) and no approval. Then place it via a layout template (below).

Three tiers, least → most permanent: extensionOverride (local build) → Extension Manager / BYO (deployed app, one org, no approval) → publish (org-wide, needs approval; see appbuilder-workfront).

Open the deployed app — the direct link

Once the app is deployed and registered in that instance (BYO-enabled above, or published), the Main Menu button opens a real, shareable Experience Cloud URL. After aio app deploy, hand the user this link so they can open the app directly:

https://experience{-stage}.adobe.com/#/@<org>/so:<instance>/workfront/custom-applications/<extensionId>/<menuRoute>

e.g. https://experience-stage.adobe.com/#/@workfrontaidevarm/so:ai-dev-arm-Dev/workfront/custom-applications/combined-timeline-view/combined-timeline

SegmentSource
experience-stage / experiencestage vs prod — the env you deployed to (AIO_CLI_ENV=stage → experience-stage)
@<org>org handle (e.g. @workfrontaidevarm) — copy from a Workfront page the user already has open; don't derive it from the org name
so:<instance>selects the Workfront instance (e.g. so:ai-dev-arm-Dev) — copy verbatim from that same URL (the segment right after @<org>)
<extensionId>the registration id — the non-empty extensionId in Constants.js (the id passed to register())
<menuRoute>the Main Menu item's route — the #/ fragment of its getItems() url (…#/combined-timeline → combined-timeline); matches the <Route path> in App.js

aio app deploy prints the CDN URL but not @<org> or so:<instance> — those are tenant/env facts. Reliable recipe: you already know <extensionId> and <menuRoute> from the code you built; take the whole prefix up to and including /workfront/ from a live Workfront page (or the Extension Manager link above) and append custom-applications/<extensionId>/<menuRoute>.

Two traps: the bare CDN …/index.html#/<menuRoute> renders with no Workfront host → no sharedContext; and the second path segment must be the real menu route — reusing the app id there (…/<extensionId>/<extensionId>) loads the background registration frame, not the view.

2. Accept the dev certificate

If you haven't already, open https://localhost:<port> directly → Advanced → Proceed to localhost (unsafe). Workfront can't load your app until the self-signed cert is trusted.

3. Chrome 142+ Local Network Access

Chrome 142+ blocks a public origin from reaching localhost and will silently break the override. Disable the check: chrome://flags/#local-network-access-check → Disabled → Relaunch.

4. Make the app visible

Extension points only render where a layout template places them. Toggling a BYO extension to Enabled is not enough by itself — until it's placed in a layout template's Main Menu (or an object's left panel), it's registered but invisible to every user, including you.

Concrete click path for Main Menu placement (Workfront web UI):

  1. Setup (Main Menu → Setup, bottom of the menu) → Interface (expand it in the left sidebar) → Layout Templates.
  2. Pick the template actually assigned to your user — don't blindly edit a shared/Default template, since that affects every user assigned to it; a personally-named template (or checking the layout template's Assignments panel) is the safer target for testing.
  3. Open it → click Set Main Menu (top-right, under "Main Menu").
  4. Find your app's tile in the grid — greyed out with a + icon means it's not yet placed; click it to toggle it active (it turns blue with a - icon, next to the other already-placed custom apps).
  5. Done (closes the Main Menu dialog) → Save and close (top of the layout template editor) — the dialog's Done alone does not persist the change.
  6. Reload the Workfront tab and open Main Menu — the item now appears alongside the native items.

Do this yourself via Playwright/browser MCP — don't ask the human to click through it

Everything above (Extension Manager registration, the Enabled toggle, the entire Layout Template → Set Main Menu flow) is ordinary UI navigation once a session is authenticated — an agent with browser automation (Playwright MCP) should drive it directly instead of asking the user to do the clicking. The only steps that genuinely require the human are the ones no tool can do on someone's behalf: completing Adobe SSO/MFA (entering a password or approving an MFA prompt), and giving informed consent to a legal agreement (e.g. accepting Developer Terms of Use — read the actual terms before clicking "Accept" on someone's behalf, or better, have the human click it after you've navigated them to the exact screen). A fresh Playwright browser session starts logged out — get the human to sign in once in that session, then keep driving every subsequent screen (Extension Manager, Setup, Layout Templates, dialogs, toggles) yourself. Don't default to "please open X and click Y" for steps that are just navigation; that's the point of having browser automation available.

Not showing up? Checklist

  • Is aio app dev still running, and is the exact https://localhost:<port> in extensionOverride?
  • Cert accepted? Chrome LNA flag disabled (Chrome 142+)?
  • Are you on the right Workfront domain's Local Storage?
  • Registered via Extension Manager (BYO) instead? It defaults to Disabled — toggle it on under Installed Extensions.
  • Does a layout template that includes your app actually apply to you?
  • Do the id/url in ExtensionRegistration match a real route in App.js? (see workfront-ui-extension)
  • Is extensionId non-empty, and is id: extensionId kept under methods in register()? An empty extensionId, or dropping id from methods, makes the item register but silently not render (see workfront-ui-extension). This is the usual cause — before blaming the environment, check this.
  • Registers but still missing from the live menu (it shows in the layout-template picker, and the console shows the host calling getItems)? Suspect the Workfront environment, not your code — a shell error like …/jumpseat/api/…/configuration 503 or "Detected multiple done events" breaks nav rendering. Reload later or try a healthy instance.
  • extensionOverride is only for unpublished apps. For the item to appear in the live menu without an override, the app must be published (submit + approve from Production — see appbuilder-workfront).

Workfront UI extension (front end)

Part of the appbuilder-workfront family. This is the front end — the app screens the user sees (the "SPA"). It registers extension points (the spots where the app appears in Workfront) and calls Runtime actions (the cloud back end) for all data.

This skill is the Workfront-specific front end (extension points, WF shared context). For generic React/Spectrum patterns (pages, forms, data tables, dialogs, navigation) and ExC Shell / AEM UI surfaces, use appbuilder-ui-scaffolder. A ready-to-edit registration example is in assets/ExtensionRegistration.example.js.

Rules

  • One register() call wires everything up; individual views use attach().
  • Auth comes from sharedContext + getWFInstanceUrl() — Workfront supplies the signed-in user and instance; don't build a login.
  • Talk to the back end with actionWebInvoke only — the browser must never call Workfront directly (/attask/api/…). Back-end code lives in workfront-actions.
  • Every action replies with { data, error } — always check error before using data.

Extension points (in ExtensionRegistration)

register() takes id at the top level (a non-empty slug identifying the extension); the extension points go inside methods. Each item's url must map to a route in App.js, and every id must be unique.

const guestConnection = await register({
  id: extensionId,               // top-level id, non-empty
  metadata,                      // from app-metadata.json (generated by a build hook)
  methods: {
    id: extensionId,             // ⚠️ REQUIRED here too — the menu item won't render without it (see Gotchas)
    mainMenu: {
      getItems() { return [{ id, url: '/index.html#/route', label, icon }] }
    },
    secondaryNav: {              // left panel, per object type
      PROJECT: { getItems() { return [{ id, label, icon, url: '/route' }] } },
      // register each separately: PROJECT, TASK, ISSUE, PORTFOLIO, PROGRAM
    },
    widgets: {                   // embed in a custom-form field
      getItems() {
        return [{
          id, url: '/index.html#/widgets1', label,
          dimensions: { height, width, maxHeight, maxWidth }   // all optional
        }]
      }
    },
  }
})

Widget id/url/label are required; dimensions is optional.

Routing (App.js)

Add a <Route> per extension-point url:

<Route exact path="custom-application" element={<CustomApplication />} />

Shared context

sharedContext is get-only (.get(key) — not iterable). Confirmed shape from the Workfront host:

const ctx  = conn?.sharedContext
const auth = ctx?.get('auth')      // { imsClientId, imsOrgID, imsToken }
const user = ctx?.get('user')      // { ID, email }
const host = ctx?.get('hostname')  // e.g. ai-dev-arm.devtest.workfront-dev.adobe.com (no protocol)
// also: protocol; plus objCode, objID, isLoginAs, isInBulkEditing on object-scoped points

const imsToken = auth?.imsToken
const imsOrgId = auth?.imsOrgID     // ⚠️ key is `imsOrgID` (capital ID) — NOT imsOrgId / imsOrg

Everything an action needs is right here — pass imsToken, imsOrgId (auth.imsOrgID), and host into actionWebInvoke. Don't call Workfront for the org: it's in auth, and a cross-origin currentUser fetch from the SPA is CORS-blocked anyway. Only set the x-gw-ims-org-id header when you have a value — Fetch turns undefined into the string "undefined" (→ 401 Org Id undefined). Widgets receive the same context.

Workers / errors

Do heavy CSV/XLSX (spreadsheet) work in Web Workers — background threads, so the screen doesn't freeze — but never call the WF API inside a worker. Show a toast (small popup notice) on failure; never expose tokens.

Gotchas (from building a real Main Menu extension)

  • Main Menu item not rendering? It's the id, and the fix is trivial. The WF template scaffolds register({ metadata, methods: { id: extensionId, mainMenu } }) with extensionId = '' in Constants.js. Two things are required for the item to appear: (1) give extensionId a non-empty value in Constants.js, and (2) keep id: extensionId under methods — that placement is exactly what the menu needs; if you remove it, the item still registers (Workfront even calls getItems) but silently never renders. Simplest working form: set extensionId, and keep id: extensionId inside methods (having it at the top level of the config too is fine). Don't be thrown off by reading @adobe/uix-guest: register(config) does new GuestServer(config.id) then guest.register(config.methods, …) and just forwards methods to the host — so from the guest source a bare methods.id looks like an ignored no-op. It isn't: Workfront's host side consumes methods.id, and that behavior isn't visible in the guest package. Verified in a live Main Menu extension — the item does not render without it. (This is easy to misdiagnose as an environment problem, or as dead code — it's neither.)
  • aio app init -y (or skipping the "Add a custom button to Main Menu Item" prompt) generates no menu item at all — no mainMenu block, no view component, no App.js route, no icons.js, empty extensionId. Either answer that prompt during init, or hand-add: icons.js (exporting icon1/icon2), the mainMenu block, a <Route>, and the view component.
  • Calling actions: the template's web-src/src/utils.js exports actionWebInvoke(url, headers, params, options = { method: 'POST' }). Action URLs are injected into web-src/src/config.json at build time under both "<action>" and "<package>/<action>" — import actions from '../config.json' and look up by name; never hardcode a Runtime URL.
  • register vs attach: the background registration frame uses register() (a GuestServer, declares the extension points); a displayed view uses attach() (a GuestUI). Both expose sharedContext.
  • The deployed app's URL is the Experience Cloud shell link — not the bare CDN. Clicking the Main Menu button navigates to …/workfront/custom-applications/<extensionId>/<menuRoute> (org- and instance-scoped); that is the app's shareable URL, and after aio app deploy you should hand it to the user (build recipe in workfront-local-testing). First segment = the registration id; second = the menu item's #/route. Two traps: reusing the app id as the second segment (…/<extensionId>/<extensionId>) loads the background registration frame, not the view; and the raw CDN …/index.html#/route renders with no host → no sharedContext. If the item registers but won't render live, suspect the Workfront environment, not the code (see workfront-local-testing).
  • React Spectrum TableView's "select all" header checkbox gives you the string 'all', not a Set. onSelectionChange for selectionMode="multiple" normally hands you a Set of row keys, and code like selectedKeys.size > 0 works fine when the user checks rows one at a time. But clicking the header's own "select all" checkbox sets selectedKeys to the literal string 'all' instead — 'all'.size is undefined, so a naive selectedKeys.size > 0 check silently evaluates to false and a bulk-action button stays disabled with no visible error. Always branch on the string case: const count = selectedKeys === 'all' ? totalItems : selectedKeys.size, and use the same branch anywhere you turn the selection into an array of ids (selectedKeys === 'all' ? items.map(i => i.id) : Array.from(selectedKeys)). This is easy to miss in testing if you only ever click individual row checkboxes.

Sponsors

Details

Marketplace
adobe/skills
Source
plugins/app-builder
Category
Community

More from adobe/skills

All 19