Create a Category Add-on Using an AI Coding Agent

Overview

The Action Skill is an AI agent skill that guides your coding agent through building an Alexa+ action add-on from your API. It handles:

• Scaffolding — Creates the project structure via the Alexa AI CLI
• Feasibility Analysis — Analyzes your API against each SPI operation
• Code Generation — Implements operations using TDD (test-driven development)
• POI upload - Validates POI and allows you to upload either for testing or production use case
• Integration Testing — Validates your implementation against category-defined tests

The skill works with any compatible AI coding agent (Kiro, Claude Code, Cursor, VS Code Copilot).

Prerequisites

Before you begin, make sure you meet the prerequisites for the Category SDK.

In addition, you need the following for the agentic workflow:

• Alexa AI CLI: Installed and on PATH (npm install -g @alexa-ai/cli)
• git setup for CodeCommit: Update gitconfig to add codecommit helper. See AWS CodeCommit Setup.
• AI coding agent: Kiro, Claude Code, Cursor, or VS Code Copilot
• Your API spec: OpenAPI/Swagger YAML, API docs URL, or equivalent

Step 1: Clone the skills repository

The skills are hosted in a CodeCommit repository. Clone it:

git clone https://git-codecommit.us-west-2.amazonaws.com/v1/repos/alexaplus-addon-agent-skills
cd alexaplus-addon-agent-skills

The repository contains three skills that work together:

alexaplus-addon-agent-skills/
├── alexaplus-addon-action-skill/      # Main skill — feasibility, code gen, testing
│   ├── SKILL.md
│   ├── references/
│   └── assets/
├── alexaplus-addon-lifecycle-skill/   # CLI executor — deploy, test, scaffold
│   ├── SKILL.md
│   └── references/
└── alexaplus-addon-horizontals-skill/ # Account linking, permissions, payments
    ├── SKILL.md
    └── references/

Step 2: Add the skills to your AI agent / IDE

The following sections describe how to add an agent skill to popular AI agents. Consult the documentation for the agent you are using for more details.

Kiro

Option A: Import via Kiro IDE (recommended)

1. Open Kiro IDE and open your project workspace
2. Open the Skills panel (click the Skills icon in the sidebar)
3. Click "Import Skill"

4. Enter the CodeCommit repository URL:

   https://git-codecommit.us-west-2.amazonaws.com/v1/repos/alexaplus-addon-agent-skills
   

5. Kiro detects the skills in the repository. Select all the skills detected from the repository
6. Click Import to add them to your project

Once imported, the skills appear in your project's .kiro/skills/ directory and are automatically loaded by the agent.

Option B: Manual copy (Kiro CLI / terminal)

# From your project root
mkdir -p .kiro/skills
cp -r /path/to/alexaplus-addon-agent-skills/. .kiro/skills/

Kiro automatically detects and loads the skills from the .kiro/skills/ directory.

Claude Code

Add the skills directory to your project configuration. In your project root, create or update .claude/settings.json:

{
  "skills": [
    "/path/to/alexaplus-addon-agent-skills/alexaplus-addon-action-skill/SKILL.md",
    "/path/to/alexaplus-addon-agent-skills/alexaplus-addon-lifecycle-skill/SKILL.md",
    "/path/to/alexaplus-addon-agent-skills/alexaplus-addon-horizontals-skill/SKILL.md"
  ]
}

Cursor

Place the skill files where Cursor's agent can access them. Add to your .cursor/rules or project instructions:

Use the skills at:
- ./skills/alexaplus-addon-action-skill/SKILL.md
- ./skills/alexaplus-addon-lifecycle-skill/SKILL.md
- ./skills/alexaplus-addon-horizontals-skill/SKILL.md

Or copy the skills into your workspace:

mkdir -p skills
cp -r /path/to/alexaplus-addon-agent-skills/. skills/

VS Code Copilot

Add the skills as context files in your .github/copilot-instructions.md or reference them in your workspace:

mkdir -p .github/skills
cp -r /path/to/alexaplus-addon-agent-skills/alexaplus-addon-action-skill .github/skills/
cp -r /path/to/alexaplus-addon-agent-skills/alexaplus-addon-lifecycle-skill .github/skills/
cp -r /path/to/alexaplus-addon-agent-skills/alexaplus-addon-horizontals-skill .github/skills/

Step 3: Start the development flow

Open a new chat session with your AI agent and say:

"I want to create a new Alexa+ action add-on for the restaurant-reservation category."

or

"Help me create an Alexa+ action add-on"

The agent (guided by the action skill) walks you through the entire flow.

Development workflow

The action skill orchestrates a structured, multi-phase workflow:

Phase 1: Scaffolding

The agent collects:

1. Add-on name — Display name (max 30 characters)
2. Category — e.g., restaurant-reservation

Then it scaffolds the project:

my-addon/
├── addon-package/
│   └── addon.json
├── restaurant-reservation-interface/
│   ├── documentation/       # SPI operation docs
│   ├── src/                 # Your implementation code
│   ├── testConfig.json      # Integration test data
│   ├── package.json
│   └── tsconfig.json
└── package.json

Phase 2: Operations implementation

For each SPI operation (e.g., GetAvailability, CreateReservation, and so on), the agent follows a strict pipeline:

1. Feasibility analysis — Analyzes your API endpoints, maps fields between SPI and your API, identifies gaps (auth, data, functional), and produces a detailed report.
2. Approval gate — You review the feasibility report and approve or provide feedback.
3. Implementation plan — Decomposes into tasks with acceptance criteria and identifies infrastructure dependencies.
4. Implementation (TDD) — Stub → Red (failing tests) → Green (passing) → Refactor. One operation at a time.
5. Integration testing — Regenerates test data from your API, runs category tests via alexa-ai test, and commits on success.

Key developer interactions:

• Provide your API spec — OpenAPI/Swagger YAML or docs URL
• Review feasibility reports — Approve or provide feedback per operation
• Provide API credentials — When integration tests need your API access
• Resolve gaps — Address any blocking issues the agent identifies

Phase 3: Full integration testing

Once all operations are implemented, the agent runs the complete test suite:

# The agent invokes this for you:
alexa-ai test --test-suite <interface>/testConfig.json

All integration tests must pass before deployment.

Phase 4: Deploy

After all tests pass, tell the agent: "Deploy my add-on"

The agent does the following:

1. Prompt you to authenticate via alexa-ai configure (first time only)
2. Run alexa-ai deploy

What you provide

Progress tracking

The agent maintains a progress.json tracker at:

<interface-folder>/.agent/progress.json

Example:

{
  "interface": "RestaurantReservation",
  "operations": [
    { "name": "GetAvailability", "status": "completed" },
    { "name": "CreateReservation", "status": "feasibility_complete" },
    { "name": "UpdateReservation", "status": "not_started" },
    { "name": "CancelReservation", "status": "not_started" }
  ]
}

Status values:

• not_started — Not yet analyzed
• feasibility_in_progress — Analysis underway
• feasibility_complete — Awaiting your approval
• feasibility_approved — You approved, implementation next
• implementation_in_progress — Code being written
• implementation_complete — Code done, testing next
• integration_test_in_progress — Tests running
• integration_test_complete — Tests passed
• completed — Done, committed
• not_feasible — Operation cannot be implemented (acknowledged)

Resuming work

If you close your session and return later, just open a new chat. The agent:

1. Detects the existing project (via the interface folder)
2. Reads progress.json to determine where you left off
3. Continues from the exact point you stopped

Configuring account linking (optional)

If your API requires user-level OAuth credentials, tell the agent:

"Configure account linking"

The agent invokes the alexaplus-addon-horizontals-skill to walk you through OAuth2 configuration.

Configuring permissions (optional)

If your operations need user PII (email, name, address, etc.):

"Configure permissions"

The agent guides you through scope selection and addon.json configuration.

Deploying

After all tests pass, tell the agent:

"Deploy my add-on"

The agent prompts you to run alexa-ai configure for authentication (only required at deploy time), then handles the full deploy cycle.

For subsequent deploys after code changes:

"Deploy my add-on"

The agent handles auth recovery automatically if your session has expired.

POI data ingestion

All task-completion add-ons (Restaurant Reservation, Local Booking, Food Ordering) require POI (Point of Interest) data so customers can discover your businesses via Alexa search. The alexaplus-addon-ingestion-skill handles the end-to-end ingestion workflow. For the accepted data format, see Point of Interest Catalog Schema.

When to use

After your add-on is deployed and you have POI data (restaurant locations, salon addresses, etc.) ready to upload for Alexa search and discovery.

Starting the flow

Tell your agent:

"Upload my POI data"

or

"I need to ingest POI data for my add-on"

The agent asks for:

1. Data feed location — Path to your POI file(s) (CSV, JSON, JSONL, XLSX)
2. Supported actions — What actions the POI supports (booking, delivery, or both)
3. Data feed description (optional) — Brief summary of the data structure

Ingestion workflow

The ingestion skill orchestrates a 5-phase pipeline:

1. Schema mapping — Reads your data feed (first 500 records), determines the source schema, maps fields to the Alexa+ POI schema by semantic meaning, and presents a mapping table for your confirmation.
2. Approval gate — You review the field mapping and approve or provide corrections.
3. Transformer script generation — Generates a Python transformer (transformer.py) that handles format detection, type coercions, and coordinates. Outputs JSON Lines (.jsonl) with timestamp naming and reports transformation metrics.
4. Run and validate — Executes the transformer against your full data feed, generates and runs validate.py against the output, checks required fields, types, patterns, and enums, and iterates until all records pass validation.
5. Upload test catalog — Creates a test catalog (one-time), associates the catalog with your add-on, uploads the validated JSONL file, monitors processing status, and guides Alexa+ Simulator testing.
6. Upload production catalog — Creates a production catalog (one-time), uploads the full dataset (up to 25 GB). Production ingestion takes approximately one week.

Key CLI commands

Test vs production catalogs

Output files

Re-running for feed updates

Once generated, re-run the transformer for periodic data updates:

python transformer.py --data-feed-path /path/to/updated_feed.csv
python validate.py --file output_<timestamp>.jsonl
alexa-ai upload-catalog --catalog-id <catalogId> --file output_<timestamp>.jsonl

Each upload fully replaces the previous catalog — no incremental updates.

Important notes

• Save your Catalog ID — There is no CLI command to retrieve it later.
• Save your Upload ID — Needed to poll processing status.
• Validation is all-or-nothing — If any record fails server-side validation, the entire file is rejected. Always run local validation first.
• Allowlisting required — Your account must be allowlisted for the Alexa+ add-on program. If uploads fail with permission errors, contact the Alexa BDSA team.

Troubleshooting

Multi-skill architecture

The three skills work together but have strict responsibilities:

You only interact with the action skill directly — it delegates to the others automatically.

Quick start summary

# 1. Clone the skills
git clone https://git-codecommit.us-west-2.amazonaws.com/v1/repos/alexaplus-addon-agent-skills
cd alexaplus-addon-agent-skills

# 2. Copy skills to your project (Kiro example)
mkdir -p /path/to/your-project/.kiro/skills
cp -r alexaplus-addon-action-skill /path/to/your-project/.kiro/skills/
cp -r alexaplus-addon-lifecycle-skill /path/to/your-project/.kiro/skills/
cp -r alexaplus-addon-horizontals-skill /path/to/your-project/.kiro/skills/

# 3. Start building (in your AI agent chat)
> "I want to create a new action add-on for the restaurant-reservation category."

# 4. When ready to deploy (after all tests pass)
alexa-ai configure
> "Deploy my add-on"

Related topics

• Create a Category Action Add-on
• Alexa AI CLI Reference
• Point of Interest Catalog Schema
• Alexa+ Add-On Program Materials License
• AWS CodeCommit Setup Guide

Last updated: Jul 20, 2026