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 directories.

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 during the skill compilation process. You typically don't edit files in this directory.

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

This directory contains custom types, events, actions, and sample conversations, called dialogs, in ACDL file format. 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 at least contain 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 contains the visual content, if any, that Alexa displays to the user as APL files. ASK CLI quick-start templates, such as the Weather Bot template, don't have 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 that are of specific interest to Alexa Conversations are the dialog management settings inside the manifest.apis.custom section.

For Alexa Conversation-specific details about the 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.

Last updated: Jan 03, 2022