Build Custom Capabilities

---

Use the Smart Home AI Toolkit to chat with the Alexa+ smart home agent to describe your device and create a new capability. Or you can start with an existing specification and chat with the agent to fill in the gaps. The agent generates the custom capability, including the interface definition, directives, properties, and responses. You save the capability to a device that represents your physical product.

Describe your device capabilities

On the New Integration page, describe the capabilities of your smart home device by chatting with the agent or uploading one or more specifications. To complete the custom capability definition, answer all questions from the agent.

Chat and build

The chat-and-build path enables you to specify your device's capabilities through natural conversation, without explicitly defining directives, properties, or responses. The agent maps your plain-language descriptions to the formal structure internally.

To start, describe your smart home device in the chat box, including the type of device and what your device can do. Throughout the conversation, the agent summarizes what it understands and asks clarifying questions. You can continue to enter text in natural language or select an agent-suggested response to provide answers. Continue to chat with the agent as it requests missing or ambiguous information. You can tell the agent that you will define an item later and continue without providing that detail immediately.

In your conversation, describe the following elements of your device capabilities:

• Device type and function.
• Actions that the customer can request the device to perform, such as turn on, turn off, or adjust settings.
• Any limits, ranges, or fixed sets of options for each action, such as temperature range 60 to 80 degrees Fahrenheit.

Upload a specification

If you have technical documentation, you can skip the full guided conversation and upload reference, requirements, or JSON manifest files. To upload a file, choose the attachment icon (paper clip), and then browse to select the file. The upload path supports many file types, such as TXT, CSV, JSON, PDF, HTML, PY, MD, TSV, JS, and more.

The agent parses the file, generates the interface definition, and asks follow-up questions to fill any gaps. The agent is designed to prompt for missing values rather than fill them in silently.

Steps to create a custom capability

Complete the following steps to create a custom capability.

To describe your device capabilities in the Smart Home AI Toolkit

1. Sign in to the Smart Home AI Toolkit.
2. On the Alexa+ Smart Home page, choose New Integration.
3. To create your custom capability, use the chat and build option or the upload option.
4. Instruct the agent to save the capability and create a device.
   Example prompt: Save this capability and create a device.
5. After the agent suggests a device name, device type, and device version, confirm the defaults or instruct the agent with valid information.

Review and refine the capability

After the agent has enough information, it generates the interface definition and presents it in the capability workspace. The capability workspace includes the following four tabs:

• Controller View – Shows the generated interface definition for your custom capability, including the capability namespace, version, and description. The definition includes configuration attributes, properties, directives, events, and data types.
• JSON View – Displays the full capability definition in JSON. You can review and update the definition directly in the viewer.
• Test – Provides tools to generate test utterances for your capability, run a batch evaluation against the generated utterances, and test custom utterances. For details, see Test Custom Capabilities.
• Documentation – Generates a technical specification for the capability. You can use the specification to implement the capability in your smart home add-on.

To update the definition, open the JSON View, make changes directly in the viewer, and then choose Save. Or, you can instruct the agent to make the changes for you. The agent validates the JSON automatically as you make changes through conversation.

After you save the changes, the agent automatically marks any previous test utterances and batch evaluations as out of date (Stale).

View the device

After you save your capability to a device, you can view the custom and pre-built interfaces included in your device.

To view the device definition in the Smart Home AI Toolkit

1. On the Alexa+ Smart Home page, choose Devices, and then select the device to view.
2. To view the capabilities included in your device, open the Overview tab.
3. To view and copy a sample discovery response that includes the custom and pre-built capabilities, open the Discovery JSON tab.

Edit a published custom capability

You can make updates to your published custom capability by creating a new version of the definition. To make edits to an unpublished version, see Review and refine the capability.

To edit a published custom capability

1. On the menu, choose Capabilities, and then select a capability to edit.
2. In the chat window, instruct the agent to create a new version of the capability.
3. To make changes to the capability definition, chat with the agent or update the JSON View and save the changes. For more details, see Review and refine the capability.
4. Instruct the agent to save the modified version of the capability.
5. If you haven't added the capability to a device, instruct the agent to add it to a device.

Next steps

After you create or edit the custom capabilities and add them to a device, test your capabilities and device.

Related topics

• Add Custom Capabilities with the Smart Home AI Toolkit
• List of Alexa Interfaces
• Publish a Device with Custom Capabilities
• Steps to Build a Smart Home Add-on

---

---

Last updated: Aug 01, 2026