Create Site

Create a New AEM Edge Delivery Site

This skill walks through the full onboarding flow for a new AEM Edge Delivery site. It handles everything that can be automated and clearly signals the steps that require human action.

When to Use This Skill

Use this skill when:

• A user wants to create a brand-new AEM Edge Delivery site from scratch
• A user asks to "set up a new site", "create a new EDS project", or "onboard a new site"
• No GitHub repository or DA content exists yet for the project

Do NOT use this skill for:

• Importing or migrating existing pages (use page-import skill)
• Building or modifying blocks on an existing site (use content-driven-development skill)

Prerequisites

• A GitHub account with permission to create repositories in the target org
• An Adobe IMS account with access to DA (da.live)
• gh CLI authenticated (gh auth status) or a GitHub personal access token with repo scope
• Node.js (for DA token management via da-auth-helper)

Related Skills

• page-import — Import existing pages into the newly created site
• content-driven-development — Build and modify blocks once the site exists
• building-blocks — Implement new block code

Step 0: Create TodoList

Create a checklist to track progress (use your agent's task-tracking tool if available):

1. Gather inputs — org, repo name, site name collected
2. Create GitHub repository — repo created from boilerplate template
3. Install aem-code-sync (human action) — GitHub App installed on repo
4. Authenticate with DA — valid IMS token obtained
5. Create initial content in DA — nav, footer, index created
6. Trigger preview — all three paths return 200/201
7. Hand off — preview URL and DA links delivered to user

Step 1: Gather Inputs

Ask the user for the following. Do not proceed until all required inputs are provided.

1. GitHub org — the GitHub organization or username where the repo will be created (e.g. my-org)
2. Project name — the repository name, lowercase, hyphens only (e.g. my-site)
3. Site name — the human-readable name used in content (e.g. My Site). If not provided, derive it from the project name.

Store as: {{ORG}}, {{REPO}}, {{SITE_NAME}}

Step 2: Create GitHub Repository

Create a new repository using the adobe/aem-boilerplate template.

Option A — GitHub CLI (preferred, handles auth automatically):

gh repo create {{ORG}}/{{REPO}} \
  --template adobe/aem-boilerplate \
  --description "{{SITE_NAME}} — AEM Edge Delivery site" \
  --public

Check if gh is available with gh auth status. If not authenticated, run gh auth login first.

Option B — GitHub API (if gh CLI is not available):

POST https://api.github.com/repos/adobe/aem-boilerplate/generate
Authorization: Bearer {{GITHUB_TOKEN}}
Content-Type: application/json

{
  "owner": "{{ORG}}",
  "name": "{{REPO}}",
  "description": "{{SITE_NAME}} — AEM Edge Delivery site",
  "private": false,
  "include_all_branches": false
}

To obtain a token: https://github.com/settings/tokens/new — scope: repo.

Success: HTTP 201 (API) or exit code 0 (CLI). The repo is now live at https://github.com/{{ORG}}/{{REPO}}.

Step 3: Install aem-code-sync (human action required)

The aem-code-sync GitHub App connects the repository to AEM's content delivery pipeline. This step cannot be automated — the user must complete it in the browser.

Tell the user:

Action required: Install the AEM Code Sync app on your new repository.

1. Open this URL: https://github.com/apps/aem-code-sync/installations/new
2. Under "Repository access", select Only select repositories
3. Choose {{ORG}}/{{REPO}} from the list
4. Click Save

Reply "done" when complete.

Wait for confirmation before proceeding.

Verify: After confirmation, check that https://admin.hlx.page/status/{{ORG}}/{{REPO}}/main/ returns a valid JSON response (not 404). If it does, the app is correctly installed.

Step 4: Authenticate with DA

DA requires Adobe IMS authentication. Choose the appropriate path:

Option A — da-auth-helper (preferred)

da-auth-helper (https://github.com/adobe-rnd/da-auth-helper) caches IMS tokens at ~/.aem/da-token.json. Always check the cache first before triggering a new OAuth flow.

1. Check for a valid cached token:

node -e "
  const fs = require('fs');
  const p = process.env.HOME + '/.aem/da-token.json';
  if (!fs.existsSync(p)) { console.log('No cache'); process.exit(1); }
  const t = JSON.parse(fs.readFileSync(p));
  console.log('Valid:', t.expires_at > Date.now());
  console.log('Expires:', new Date(t.expires_at).toISOString());
"

2. If valid, capture the token and skip to Step 5:

DA_TOKEN=$(node -e "const t = require(process.env.HOME + '/.aem/da-token.json'); process.stdout.write(t.access_token);")

3. If missing or expired, install da-auth-helper from GitHub (it is not published to npm) and refresh:

npm install -g github:adobe-rnd/da-auth-helper
da-auth-helper token

This opens a browser for Adobe IMS login and writes the new token to ~/.aem/da-token.json. Then capture it as in step 2.

Option B — DA MCP is configured

If the DA MCP server is available, trigger the authentication tool to start the OAuth flow and share the authorization URL with the user.

Option C — Manual token

Ask the user to obtain an IMS token from their browser (e.g. from the DA network tab or an existing session) and paste it. Store as {{DA_TOKEN}}.