Build Alexa+ Add-ons: Development Stages
This guide covers the end-to-end process for building Alexa+ add-ons.
Development stages
Building an Alexa+ add-on flows through five stages: Discover, Build, Test, Submit, and Maintain.
Stage 1: Discover
The Discover stage is about awareness and access. You learn about the Alexa+ add-on opportunity and explore what's possible. You explore the documentation to see what kinds of experiences you can build.
After you decide to proceed, you request access to the Private Preview. After approval, you receive credentials and install the tooling, specifically the Alexa-AI command line interface (CLI) with an Add-on Agent Skill.
At the end of Discover, you run alexa-ai new and see a generated project. If you use an AI coding agent, load the Add-on Agent Skill and prompt the agent to generate your project.
Stage 2: Build
Your primary work in this stage depends on your integration path:
- Category SDK: Implement the category service provider interfaces (SPIs) against your APIs. For details, see the Category SDK Overview.
- MCP Toolkit: Adapt and connect your existing MCP server to Alexa+. For details, see the MCP Toolkit Overview.
CLI-driven add-on generation
Rather than manually creating add-on configuration files, the Alexa AI CLI provides an interactive flow. When you run alexa-ai new, the CLI:
- Collects required details, such as add-on name, description, icon, authentication details, and permission scopes.
- For MCP Toolkit add-ons, connects to your MCP server, introspects the available tools, and reads their schemas, descriptions, and capabilities.
- Confirms with you by presenting back what it found and asking for confirmation before proceeding.
- Generates the add-on with manifest files and configuration templates that you can enhance before deployment.
All Alexa configuration lives in the generated add-on manifest, separate from your server or API implementation. Your existing code stays portable and unchanged.
User interface (UI) implementation
Before implementing UI, understand that your add-on can run on two device modalities:
- Headless devices – The add-on delivers a complete experience through voice alone. If your add-on requires a screen, Alexa informs the customer at runtime that screen-enabled devices support the request.
- Devices with screens – The add-on renders fragments and full screen experiences. The visual layer can surface images, lists, and maps.
You should design for both modalities.
You must follow Alexa UX guidelines. The UI system supports two primary patterns:
- Full screen experiences are immersive views that take over the entire display
- Fragments are smaller, modular UI components that can appear as part of the conversation
You can build standard web UIs by using frameworks you already know, such as React, Vue, Svelte, or vanilla JS. Alexa provides a JS SDK for host communication and an optional component library with React components that follow Alexa UX guidelines.
Tool design guidelines
Start by designing or adapting your tools:
- Design tools for one-shot extraction. For example, a user might say "Find me a pet-friendly hotel in Seattle for December 5–7 under $150 with parking" and the tool schema accepts all those constraints in a single call.
- Return structured errors with enough information for Alexa to ask specific follow-up questions.
- Provide stable IDs and option labels in search results so users can say "Tell me more about Hotel B" or "Book the first one".
Stage 3: Test
In this stage, you test that your add-on works across a range of scenarios and device types.
Local and isolated testing
Before testing end-to-end with Alexa+, validate your integration in isolation.
- Category SDK: Run unit tests against your SPI implementations and use the
alexa-ai testcommand to start a local debugging session. - MCP Toolkit: Use the standard MCP Inspector to list tools, verify schemas, and call tools with valid and invalid inputs. Export traces for review.
Golden use case testing with Alexa AI CLI
Based on your service description, Alexa AI CLI generates a golden use cases test suite covering key scenarios. You can review and add to this test suite. To validate end-to-end behavior, run alexa-ai test --test-suite /path/to/test-suite.
Simulator and on-device testing
Deploy your add-on using alexa-ai deploy to test during development. Link your devices to your development environment, deploy your add-on to a development stage, and invoke it on the linked device.
Stage 4: Submit
In the Submit stage, you verify your add-on meets all requirements and send it to Amazon for certification before it goes live.
Pre-submission
Before submitting, review the following requirements:
- Add-on endpoint is accessible by Alexa (protected by OAuth or publicly accessible through HTTPS).
- All tests pass.
- Privacy policy URL is valid and accessible.
- Metadata contains information needed for account linking, permissions, and payments.
- UI passes an automated Alexa UX guidelines check.
- Complete on-device testing for the applicable device modalities.
Submission
Submit through the CLI by running alexa-ai submit. You receive a confirmation email with a reference number. The team reviews the submission based on the checklist requirements.
Lifecycle stages
The following diagram illustrates the add-on lifecycle.
The add-on moves through four stages:
- Development: You're building and testing, with full access to modify.
- Submitted for certification: You can view status and respond to questions but can't modify.
- Certified: Review has passed.
- Live: Published in Alexa+ Store, available to customers.
Add-ons that fail certification move back to Development stage with a detailed and actionable failure report.
Stage 5: Maintain
After your add-on is live, the Maintain stage helps you monitor performance and ship updates.
Analytics
You can access an analytics dashboard to see how your add-on is performing. View key performance indicators and export data for further analysis.
Iteration
When you want to ship updates, cycle back through the Build and Test stages for the new functionality. Then submit the update for certification. Version management lets you track what's in development, what's under review, and what's live.
Related topics
Last updated: Jul 10, 2026
