commerce-docs · bdenham · Jul 17, 2026 · Jul 17, 2026 · Jul 17, 2026 · Jul 17, 2026
diff --git a/astro.redirects.mjs b/astro.redirects.mjs
@@ -226,8 +226,13 @@ export function generateRedirects(basePath) {
         '/resources/product-discovery-diagrams': `${basePath}/dropins/product-discovery`,
         '/merchants/quick-start/visual-editor': `${basePath}/merchants/quick-start/universal-editor`,
         '/setup/aem-assets-integration': `${basePath}/merchants/quick-start/universal-editor`,
-        '/boilerplate/ai-agent-skills': `${basePath}/ai/ai-agent-skills`,
+        '/boilerplate/ai-agent-skills': `${basePath}/ai/boilerplate-skills`,
         '/build-with-ai': `${basePath}/get-started/build-with-ai`,
         '/resources/build-with-ai': `${basePath}/get-started/build-with-ai`,
+
+        // ========= AI SECTION REDIRECTS =========
+        // ai-agent-skills.mdx and build-with-ai.mdx renamed to match sidebar labels
+        '/ai/ai-agent-skills': `${basePath}/ai/boilerplate-skills`,
+        '/ai/build-with-ai': `${basePath}/ai/static-text-files`,
     };
 }
diff --git a/astro.sidebar.mjs b/astro.sidebar.mjs
@@ -33,13 +33,14 @@ export function generateSidebar() {
           ],
         },
         {
-          label: 'Build with AI',
+          label: 'AI Integrations',
           collapsed: false,
           items: [
-            { label: 'Overview', link: '/ai/' },
-            { label: 'Use docs in AI tools', link: '/ai/build-with-ai/' },
-            { label: 'Drop-ins MCP', link: '/ai/dropins-mcp/' },
-            { label: 'AI agent skills', link: '/ai/ai-agent-skills/' },
+            { label: 'Install the integrations', link: '/ai/' },
+            { label: 'Boilerplate skills', link: '/ai/boilerplate-skills/' },
+            { label: 'Dropins MCP', link: '/ai/dropins-mcp/' },
+            { label: 'Wayfinder', link: '/ai/wayfinder/' },
+            { label: 'Fallback docs', link: '/ai/static-text-files/' },
           ],
         },
         {

diff --git a/src/content/docs/ai/ai-agent-skills.mdx b/src/content/docs/ai/ai-agent-skills.mdx
diff --git a/src/content/docs/ai/boilerplate-skills.mdx b/src/content/docs/ai/boilerplate-skills.mdx
@@ -0,0 +1,149 @@
+---
+title: Boilerplate skills
+description: Learn how to install and use Boilerplate skills so your AI coding agent plans, codes, and tests Adobe Commerce storefront changes on Edge Delivery Services.
+sidebar:
+  label: Boilerplate skills
+  order: 8
+---
+
+import Aside from '@components/Aside.astro';
+import TableWrapper from '@components/TableWrapper.astro';
+import Link from '@components/Link.astro';
+import { Steps } from '@astrojs/starlight/components';
+
+Boilerplate skills provide instructions for your coding agent on how to work in an Adobe Commerce boilerplate storefront. When you install the **AEM Boilerplate Commerce** skill set, your agent can plan the task, choose the right storefront pattern, write code that follows project conventions, and test the result in a browser.
+
+## Benefits
+
+Use Boilerplate skills when you want your agent to help with a full storefront development task, not only to answer a question. The skills help your agent:
+
+- Plan the work before changing code.
+- Choose the right approach for blocks, drop-ins, content models, and browser tests.
+- Reduce repeated project explanations by storing storefront conventions in your repository.
+
+## What the skills provide
+
+The AEM Boilerplate Commerce skill set installs six specialized skills, each covering a focused area of storefront development.
+
+<TableWrapper nowrap={[0]}>
+
+| Skill | What it helps you do |
+|-------|----------------------|
+| **Project manager** | Breaks down tasks, guides phased delivery, and keeps development on track before any code is written |
+| **Researcher** | Looks up drop-in component APIs, slot names, event payloads, and TypeScript definitions before implementing |
+| **Block developer** | Builds and customizes Edge Delivery Services blocks using correct DOM patterns and CSS scoping |
+| **Drop-in developer** | Customizes drop-in components using containers, slots, events, and API functions |
+| **Content modeler** | Designs block table structures that are easy for content authors to work with |
+| **Tester** | Verifies implementations in a real browser and checks Core Web Vitals and accessibility |
+
+</TableWrapper>
+
+The skills work together: for every task, your agent uses the project manager skill to scope work, the researcher skill to prepare, and the appropriate developer skill to build.
+
+<Aside type="note" title="Drop-in API accuracy">
+Four of these skills — researcher, drop-in developer, project manager, and tester — call Dropins MCP tools to verify slots, events, API functions, and configuration against your project's source, not published documentation. Without the [Dropins MCP server](/ai/dropins-mcp/) installed, most checks fall back to local TypeScript definitions. A few, such as generating slot boilerplate, have no fallback. For the underlying APIs, see the [Blocks reference](/boilerplate/blocks-reference/) and [Drop-in components](/dropins/all/introduction/).
+
+Adding the MCP (Model Context Protocol) server or [Wayfinder](/ai/wayfinder/) doesn't automatically integrate them with this workflow. See [Install the integrations](/ai/#installation-steps), step 4, for the precedence rule.
+</Aside>
+
+## Prerequisites
+
+Before installing the skills, make sure you have the following:
+
+- **Node.js 22 or later** — Required by the Commerce plugin you install in the next step.
+- **An Adobe Commerce boilerplate project** — The skills are designed for projects based on the <Link href="https://github.com/hlxsites/aem-boilerplate-commerce" text="Adobe Commerce boilerplate" />. If you haven't created a boilerplate storefront, see [Getting started](/boilerplate/getting-started/) to create one.
+- **The Adobe I/O CLI and Commerce plugin** — Install both:
+
+  ```bash
+  npm install -g @adobe/aio-cli
+  aio plugins:install https://github.com/adobe-commerce/aio-cli-plugin-commerce
+  ```
+
+  See the <Link href="https://developer.adobe.com/app-builder/docs/guides/runtime_guides/tools/cli-install" text="Adobe I/O CLI installation page" /> and the <Link href="https://github.com/adobe-commerce/aio-cli-plugin-commerce" text="aio-cli-plugin-commerce repository" /> for details.
+
+  <Aside type="note" title="Authentication is optional">
+  You don't need to log in or have a specific org or entitlement to install the skills. Optionally, run `aio auth login` so documentation search can use Adobe's Identity Management System (IMS). The researcher skill falls back to web search otherwise.
+  </Aside>
+
+## Install the skills
+
+Run the following command from the root of your boilerplate project:
+
+```bash
+aio commerce extensibility tools-setup
+```
+
+The command guides you through two prompts, plus a third if it can't detect a package manager from an existing lock file:
+
+<Steps>
+
+1. **Select a starter kit.** A starter kit is a project template. Choose **AEM Boilerplate Commerce** to tell the installer which skill set and conventions to copy into your project.
+
+1. **Select your coding agent.** Choose your agent from the list of supported agents. This determines where the installer places the skill files so your agent can find them. See **Supported agents** below.
+
+1. **Select a package manager.** This step appears only if the installer can't detect one from a lock file in your project.
+
+</Steps>
+
+![CLI prompt with AEM Boilerplate Commerce selected in the starter kit menu](@images/boilerplate/aio-cli-commerce-skills-select.png)
+
+<Aside type="tip" title="Non-interactive install">
+To install without prompts — for example, in a continuous integration (CI) pipeline — pass all flags directly:
+
+```bash
+aio commerce extensibility tools-setup \
+  --starter-kit aem-boilerplate-commerce \
+  --agent Cursor \
+  --package-manager npm
+```
+
+</Aside>
+
+### Supported agents
+
+After the install completes, restart your coding agent so it loads the new skills and MCP configuration. Different agents and IDEs surface installed skills differently, so there's no single way to confirm installation — in Cursor, for example, you can open the settings panel to view detected skills. For other agents, see your own agent or IDE documentation for how to verify that your project's skills have loaded.
+
+<TableWrapper>
+
+| Agent | Skills location |
+|-------|-----------------|
+| Cursor | `.cursor/skills/` |
+| Claude Code | `.claude/skills/` |
+| GitHub Copilot | `.github/skills/` |
+| Windsurf | `.windsurf/skills/` |
+| Gemini CLI | `.gemini/skills/` |
+| OpenAI Codex | `.agents/skills/` |
+| Cline | `.cline/skills/` |
+| Kilo Code | `.kilocode/skills/` |
+| Antigravity | `.agent/skills/` |
+| Other | `./skills/` (project root) |
+
+</TableWrapper>
+
+## What gets installed
+
+The setup command adds `@adobe-commerce/commerce-extensibility-tools` as a dev dependency and creates:
+
+<TableWrapper nowrap={[0]}>
+
+| File or directory | Purpose |
+|-------------------|---------|
+| `AGENTS.md` (project root) | Top-level instructions your agent reads at the start of every session |
+| `<agent-skills-dir>/` | Skill files with domain-specific rules for each development area |
+| MCP config file | Connects your agent to the `commerce-extensibility:search-commerce-docs` tool (separate from Dropins MCP) for live documentation search |
+
+</TableWrapper>
+
+This MCP tool is separate from the [Dropins MCP](/ai/dropins-mcp/) server. It gives your agent access to Adobe Commerce documentation for integration patterns, architecture, and security guidance. For slot, event, and API lookups, see **Drop-in API accuracy** above.
+
+## How to use the skills
+
+Once installed, the skills work automatically. You don't need to reference them by name. Describe what you want to build: the project manager scopes the task, the researcher finds facts, the developer builds it, and the tester checks the result.
+
+**Example prompt** — trigger the planning workflow and developer skills with a single, detailed request:
+
+> Use the planning workflow to add a social sharing button below the product title on the product detail page, so shoppers can share products on social media.
+
+<Aside type="note" title="Browser testing">
+The tester skill requires a running local development server. Use `aem up` to start your local server before asking your agent to verify an implementation.
+</Aside>