Understand the Directory Structure of the Alexa Conversations Description Language

When you create an Alexa Conversations skill by using an Alexa Skills Kit Command Line Interface (ASK CLI) quick-start template, the ASK CLI creates a skill directory. The directory includes the source code, interaction model, and Alexa Conversations artifacts for your skill. The Alexa Conversations artifacts use the Alexa Conversations Description Language (ACDL).

For a tutorial that walks you through creating a skill with ACDL by using the ASK CLI, see Tutorial: Create an Alexa Conversations Skill with ACDL.

Skill directory structure

The following table shows the directories contained within the skill directory.

<Skill Directory>/
├── .ask/
├── lambda/
└── skill-package/
    │── build/
    │   └── *.json files
    │── conversations/
    │   └── *.acdl files
    │── interactionModels/
    │   └── custom/
    │       └── < locale name >.json
    │       └── < another locale name >.json
    │       └── ...
    │── response
    │   │── display/
    │   │   │── < Folder for an APL document >
    │   │   │   └── document.json
    │   │   │── < Folder for another APL document >
    │   │   │    └── document.json
    │   │   └── < More folders for APL documents>
    │   └── prompts/
    │       │── < Folder for an APLA document >
    │       │   └── document.json
    │       │── < Folder for another APLA document >
    │       │    └── document.json
    │       └── < More folders for APL documents>
    └── skill.json

Directory descriptions

The skill directory contains the following components.

Path Description

.ask/

You can ignore this directory.

lambda/

This directory contains the dependency list (package.json) and the source code, such as index.js, for the run-time logic of your skill.

 
skill-package/
  └── build/
      └── *.json files

This directory contains the Alexa Conversations Intermediate Representation (ACIR) files that the ACDL compiler generates when the skill is compiled. You typically don't edit files in this directory.

 
skill-package/
  └── conversations/
      └── *.acdl files

This directory stores ACDL files that contain custom types, events, actions, and sample conversations called dialogs. Dialogs are examples of conversations that you expect to occur between Alexa and the user throughout the course of your skill.

 
skill-package/
  └── interactionModels/
      └── custom/

This directory contains the <locale>.json files that specify the invocation name, intents, and types for your skill. There is one interaction model file for each locale. For details about the interaction model, see Interaction Model Schemas. For Alexa Conversations, your interaction model file must contain at least an invocation name and the AMAZON.FallbackIntent.

 
skill-package/
  └── response
        └── display/
            │── < Folder for an APL document >
            │   └── document.json
            │── < Folder for another APL document >
            │    └── document.json
            └── < More folders for APL documents>

This directory houses APL files that contain the visual content, if any, that Alexa displays to the user. ASK CLI quick-start templates, such as the Weather Bot template, don't include this directory if there's no visual content. Each response display file is named document.json and resides in a directory named after the response prompt. For details about the response display file format, see Add Visuals and Audio to Your Skill.

 
skill-package/
  └── response
        └── prompts/
            │── < Folder for an APLA document >
            │   └── document.json
            │── < Folder for another APLA document >
            │    └── document.json
            └── < More folders for APLA documents>

This directory contains the speech that Alexa says to the user as APLA files. For details about using APLA with Alexa Conversations, see Response Prompt Files for Alexa Conversations. For the APLA reference documentation, see APL for Audio Reference. Each response prompt file is named document.json and resides in a directory named after the response prompt. For example, the response prompt file for the AlexaConversationsBye response prompt is <skill-directory>/skill-package/response/prompts/AlexaConversationsBye/document.json.

 
skill-package/
  └── skill.json

A file called the skill manifest contains the dialog management settings, endpoint settings, and other skill metadata information. All custom skills have a skill manifest. The skill manifest settings of specific interest to Alexa Conversations are the dialog management settings inside the manifest.apis.custom section. For details about the Alexa Conversations dialog management settings in the skill manifest, see Skill Manifest File for Alexa Conversations. For details about the skill manifest for all skills, see Skill Manifest Schema.
Was this page helpful?

Last updated: Mar 28, 2023