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)

Open Kiro IDE and open your project workspace
Open the Skills panel (click the Skills icon in the sidebar)
Click “Import Skill”

Enter the CodeCommit repository URL:

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

Kiro detects the skills in the repository. Select all the skills detected from the repository
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.”

“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:

Add-on name — Display name (max 30 characters)
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:

Feasibility analysis — Analyzes your API endpoints, maps fields between SPI and your API, identifies gaps (auth, data, functional), and produces a detailed report.
Approval gate — You review the feasibility report and approve or provide feedback.
Implementation plan — Decomposes into tasks with acceptance criteria and identifies infrastructure dependencies.
Implementation (TDD) — Stub → Red (failing tests) → Green (passing) → Refactor. One operation at a time.
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:

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

What you provide

When	What	Example
Scaffolding	Add-on name, category	”DineOut Reservations”, “restaurant-reservation”
Feasibility	Your API specification	OpenAPI YAML, Swagger URL, or pasted spec
Feasibility report	Your approval or feedback	”Looks good, proceed” or “The auth flow needs X”
Integration testing	API credentials (if needed for sample POI data)	API key, OAuth tokens
Infrastructure	Confirmation of local emulation	”Yes, use DynamoDB Local”

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:

Detects the existing project (via the interface folder)
Reads progress.json to determine where you left off
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”

“I need to ingest POI data for my add-on”

The agent asks for:

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

Ingestion workflow

The ingestion skill orchestrates a 5-phase pipeline:

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.
Approval gate — You review the field mapping and approve or provide corrections.
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.
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.
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.
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

Command	Purpose
`alexa-ai create-catalog` `--title "..." --type AMAZON.PointOfInterest --usage Alexa.Catalog.PointOfInterest.Test`	Create test catalog
`alexa-ai create-catalog` `--title "..." --type AMAZON.PointOfInterest --usage Alexa.Catalog.PointOfInterest`	Create production catalog
`alexa-ai associate-catalog-with-addon` `--addon-id <id> --catalog-id <id>`	Link catalog to add-on
`alexa-ai upload-catalog` `--catalog-id <id> --file <path.jsonl>`	Upload POI data
`alexa-ai get-content-upload-by-id` `--catalog-id <id> --upload-id <id>`	Check processing status

Test vs production catalogs

Aspect	Test Catalog	Production Catalog
Usage type	`Alexa.Catalog.PointOfInterest.Test`	`Alexa.Catalog.PointOfInterest`
Max upload size	1 MB	25 GB
Availability	Alexa+ Simulator only	Live Alexa search
Indexing speed	Instant	~1 week

Output files

File	Description
`schema-mapping.md`	Field mapping table (source → Alexa+ POI schema)
`transformer.py`	Reusable Python script for ongoing feed updates
`validate.py`	Validation script checking output against schema rules
`output_<timestamp>.jsonl`	Transformed POI records ready for upload
`errors_<timestamp>.jsonl`	Records that failed transformation (if any)

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

Issue	Resolution
`alexa-ai`: command not found	Install: `npm install -g @alexa-ai/cli`
[NOT_AUTHENTICATED]	Run `alexa-ai configure`
Agent doesn’t load skills	Verify skill files are in the correct directory for your IDE
Integration tests fail	Check server logs at `/tmp/server.log`, verify test data in `testConfig.json`
Profile “default” not configured	Run `alexa-ai configure --profile default`
Scaffolding fails	Ensure all `--name`, `--category`, `--language`, `--hosting` flags are provided

Multi-skill architecture

The three skills work together but have strict responsibilities:

Skill	What It Does	When It’s Used
`alexaplus-addon-action-skill`	Feasibility, code gen, TDD, integration testing	Main development flow
`alexaplus-addon-lifecycle-skill`	Runs ALL `alexa-ai` CLI commands	Scaffold, deploy, test, auth
`alexaplus-addon-horizontals-skill`	Account linking, permissions, payments	Cross-cutting concerns

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"

​Overview

​Prerequisites

​Step 1: Clone the skills repository

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

​Kiro

​Option A: Import via Kiro IDE (recommended)

​Option B: Manual copy (Kiro CLI / terminal)

​Claude Code

​Cursor

​VS Code Copilot

​Step 3: Start the development flow

​Development workflow

​Phase 1: Scaffolding

​Phase 2: Operations implementation

​Phase 3: Full integration testing

​Phase 4: Deploy

​What you provide

​Progress tracking

​Resuming work

​Configuring account linking (optional)

​Configuring permissions (optional)

​Deploying

​POI data ingestion

​When to use

​Starting the flow

​Ingestion workflow

​Key CLI commands

​Test vs production catalogs

​Output files

​Re-running for feed updates

​Important notes

​Troubleshooting

​Multi-skill architecture

​Quick start summary

​Related topics