[Botskills] Update documentation (#3438)

* Update botskills documentation * Update output list of botskills commands
microsoft · Jun 8, 2020 · e685b5a · e685b5a
1 parent 5166ed9
commit e685b5a
Show file tree

Hide file tree

Showing 15 changed files with 50 additions and 49 deletions.
diff --git a/docs/_docs/skills/handbook/add-skills-to-a-virtual-assistant.md b/docs/_docs/skills/handbook/add-skills-to-a-virtual-assistant.md
@@ -46,12 +46,13 @@ See the [Skills Overview]({{site.baseurl}}/overview/skills) section for details
 
 Run the following command to add each Skill to your Virtual Assistant. This assumes you are running the CLI within the project directory and have created your Bot through the template and therefore have a `appsettings.json` file present in the working folder.
 
-The `--luisFolder` parameter can be used to point the Skill CLI at the source LU files for trigger utterances. For Skills provided within this repo these can be found in the `Deployment/Resources/LU` folder of each Skill. The CLI will automatically traverse locale folder hierarchies. This can be omitted for any of the skills we provide as the LU files are provided locally. Also, you have to specify the `--cs` (for C#) or `--ts` (for TypeScript) argument for determining the coding language of your assistant, since each language takes different folder structures that need to be taken into consideration.
-
 ```bash
 botskills connect --remoteManifest "{{site.data.urls.SkillManifest}}" --cs
 ```
 
+The `--luisFolder` parameter can be used to point the Skill CLI at the source LU files for trigger utterances. For Skills provided within this repo these can be found in the `Deployment/Resources/LU` folder of each Skill. The CLI will automatically traverse locale folder hierarchies. This can be omitted for any of the skills we provide as the LU files are provided locally. Also, you have to specify the `--cs` (for C#) or `--ts` (for TypeScript) argument for determining the coding language of your assistant, since each language takes different folder structures that need to be taken into consideration.
+
+
 Once the connect command finish successfully, you can see under the `botFrameworkSkills` property of your Virtual Assistant's appsettings.json file that the following structure was added with the information provided in the Skill manifest.
 
 ```json
@@ -62,7 +63,7 @@ Once the connect command finish successfully, you can see under the `botFramewor
         "name": "<SKILL_NAME>",
         "description": "<SKILL_DESCRIPTION>"
     },
-    "skillHostEndpoint": "<VA-SKILL_ENDPOINT>"
+    "skillHostEndpoint": "<VA_SKILL_ENDPOINT>"
 ```
 
 See the [Skill CLI documentation]({{site.baseurl}}/skills/handbook/botskills) for detailed CLI documentation.
@@ -87,13 +88,14 @@ To update a Skill to your assistant/Bot we provide a `botskills` command line to
 
 Run the following command to update a Skill to your Virtual Assistant. This assumes you are running the CLI within the project directory and have created your Bot through the template and therefore have a `appsettings.json` file present in the working folder.
 
-The `--luisFolder` parameter can be used to point the Skill CLI at the source LU files for trigger utterances. For Skills provided within this repo these can be found in the `Deployment/Resources/LU` folder of each Skill. The CLI will automatically traverse locale folder hierarchies. This can be omitted for any of the skills we provide as the LU files are provided locally. Also, you have to specify the `--cs` (for C#) or `--ts` (for TypeScript) argument for determining the coding language of your assistant, since each language takes different folder structures that need to be taken into consideration.
-
 ```bash
-botskills update --botName YOUR_BOT_NAME --remoteManifest "{{site.data.urls.SkillManifest}}" --cs
+botskills update --remoteManifest "{{site.data.urls.SkillManifest}}" --cs
 ```
 
+The `--luisFolder` parameter can be used to point the Skill CLI at the source LU files for trigger utterances. For Skills provided within this repo these can be found in the `Deployment/Resources/LU` folder of each Skill. The CLI will automatically traverse locale folder hierarchies. This can be omitted for any of the skills we provide as the LU files are provided locally. Also, you have to specify the `--cs` (for C#) or `--ts` (for TypeScript) argument for determining the coding language of your assistant, since each language takes different folder structures that need to be taken into consideration.
+
 ## Refresh Connected Skills
+
 To refresh the dispatch model with any changes made to connected skills use the following command, specifying the `--cs` (for C#) or `--ts` (for TypeScript) argument for determining the coding language of your assistant, since each language takes different folder structures that need to be taken into consideration. 
 
 ```bash

diff --git a/docs/_docs/skills/handbook/botskills.md b/docs/_docs/skills/handbook/botskills.md
@@ -41,7 +41,7 @@ The `connect` command allows you to connect a Skill, be it local or remote, to y
 
 Here is an example:
 ```bash
-botskills connect --remoteManifest "{{site.data.urls.SkillManifest}}" --luisFolder "<YOUR-SKILL_PATH>\Deployment\Resources\LU" --languages "en-us" --cs
+botskills connect --remoteManifest "{{site.data.urls.SkillManifest}}" --cs
 ```
 
 *Remember to re-publish your Assistant to Azure after you've added a Skill unless you plan on testing locally only*
@@ -69,7 +69,7 @@ The `update` command allows you to update a Skill, be it local or remote, to you
 
 Here is an example:
 ```bash
-botskills update --botName <YOUR_BOT_NAME> --remoteManifest "{{site.data.urls.SkillManifest}}" --luisFolder <YOUR_LUIS_FOLDER_PATH> --cs
+botskills update --remoteManifest "{{site.data.urls.SkillManifest}}" --cs
 ```
 
 For further information, see the [Update command documentation]({{site.repo}}/tree/master/tools/botskills/docs/commands/update.md).

diff --git a/docs/_docs/skills/tutorials/create-skill/csharp/7-add-your-skill.md b/docs/_docs/skills/tutorials/create-skill/csharp/7-add-your-skill.md
@@ -22,7 +22,7 @@ To add your new Skill to your assistant we provide the [botskills](https://www.n
 Run the following command from a command prompt **within the directory of your assistant/Bot**. 
 
 ```bash
-botskills connect --remoteManifest "https://<YOUR_SKILL_NAME>.azurewebsites.net/manifest/manifest-1.1.json" --cs --luisFolder "path-to-lu-folder"
+botskills connect --remoteManifest "https://<YOUR_SKILL_NAME>.azurewebsites.net/manifest/manifest-1.1.json" --cs
 ```
 Remember to re-publish your assistant to Azure after you’ve added a Skill unless you plan on testing locally only.
 
@@ -36,7 +36,7 @@ Once the connect command finish successfully, you can see under the `botFramewor
         "name": "<SKILL_NAME>",
         "description": "<SKILL_DESCRIPTION>"
     },
-    "skillHostEndpoint": "<VA-SKILL_ENDPOINT>"
+    "skillHostEndpoint": "<VA_SKILL_ENDPOINT>"
 ```
 
 For further documentation, please check the following links:

diff --git a/docs/_docs/skills/tutorials/create-skill/typescript/6-add-your-skill.md b/docs/_docs/skills/tutorials/create-skill/typescript/6-add-your-skill.md
@@ -13,7 +13,7 @@ order: 6
 
 ## Validate the Skill manifest endpoint
 
-To validate your Skill is deployed and working open up a browser window and navigate to your deployed Skill manifest (`/api/skill/manifest endpoint`). e.g.  `http://localhost:3978/api/skill/manifest`
+To validate your Skill is deployed and working open up a browser window and navigate to your deployed Skill manifest. e.g.  `http://localhost:3978/src/manifest/manifest-1.1.json`
 
 ## Adding your skill to an assistant
 
@@ -22,7 +22,7 @@ To add your new Skill to your assistant we provide the [botskills](https://www.n
 Run the following command from a command prompt **within the directory of your assistant/Bot**. 
 
 ```bash
-botskills connect --remoteManifest "https://<YOUR_SKILL_NAME>.azurewebsites.net/manifest/manifest-1.1.json" --ts --luisFolder "path-to-lu-folder"
+botskills connect --remoteManifest "https://<YOUR_SKILL_NAME>.azurewebsites.net/manifest/manifest-1.1.json" --ts
 ```
 
 Remember to re-publish your assistant to Azure after you’ve added a Skill unless you plan on testing locally only.
@@ -37,7 +37,7 @@ Once the connect command finish successfully, you can see under the `botFramewor
         "name": "<SKILL_NAME>",
         "description": "<SKILL_DESCRIPTION>"
     },
-    "skillHostEndpoint": "<VA-SKILL_ENDPOINT>"
+    "skillHostEndpoint": "<VA_SKILL_ENDPOINT>"
 ```
 
 For further documentation, please check the following links:

diff --git a/tools/botskills/README.md b/tools/botskills/README.md
@@ -27,6 +27,7 @@ npm uninstall -g botskills
 - [Update](./docs/commands/update.md) a Skill from your assistant 
 - [Refresh](./docs/commands/refresh.md) connected skills
 - [List](./docs/commands/list.md) all Skills connected to your assistant
+- [Migrate](./docs/commands/migrate.md) all the skills to the new schema configuration settings.
 
 ## Daily builds
 Daily builds are based on the latest development code which means they may or may not be stable and probably won't be documented. These builds are better suited for more experienced users and developers although everyone is welcome to give them a shot and provide feedback.

diff --git a/tools/botskills/docs/commands/connect.md b/tools/botskills/docs/commands/connect.md
@@ -48,13 +48,13 @@ For Skills that require other Authentication connection configuration please fol
 | -r, --remoteManifest \<url>   | URL to remote Skill Manifest                                                                                                                                                        |
 | --cs                          | Determine your Virtual Assistant project structure to be a csharp-like structure                                                                                                    |
 | --ts                          | Determine your Virtual Assistant project structure to be a TypeScript-like structure                                                                                                |
-| --noRefresh [true\|FALSE]                   | (OPTIONAL) Determine whether the model of your skills connected are not going to be refreshed (by default they are refreshed)                                                       |
+| --noRefresh [true\|FALSE]     | (OPTIONAL) Determine whether the model of your skills connected are not going to be refreshed (by default they are refreshed)                                                       |
+| -e, --endpointName \<name>    | (OPTIONAL) Name of the endpoint to connect to your assistant (case sensitive) (default to using the first endpoint)                                                                 |
 | --languages [languages]       | (OPTIONAL) Comma separated list of locales used for LUIS culture (defaults to `en-us`)                                                                                              |
 | --luisFolder [path]           | (OPTIONAL) Path to the folder containing your Skills' '.lu' files (defaults to './deployment/resources/skills/en' inside your Virtual Assistant folder)                             |
-| --dispatchFolder [path]       | (OPTIONAL) Path to the folder containing your Virtual Assistant's `.dispatch` file (defaults to `./deployment/resources/dispatch` inside your Virtual Assistant folder)          |
+| --dispatchFolder [path]       | (OPTIONAL) Path to the folder containing your Virtual Assistant's `.dispatch` file (defaults to `./deployment/resources/dispatch` inside your Virtual Assistant folder)             |
 | --outFolder [path]            | (OPTIONAL) Path for any output file that may be generated (defaults to your Virtual Assistant's root folder)                                                                        |
-| --lgOutFolder [path]          | (OPTIONAL) Path for the Luis Generate output (defaults to a 'service' folder inside your Virtual Assistant's folder)                                                                      |
-| --skillsFile [path]           | (OPTIONAL) Path to your Virtual Assistant Skills configuration file (defaults to the `skills.json` inside your Virtual Assistant's folder)                                           |
+| --lgOutFolder [path]          | (OPTIONAL) Path for the Luis Generate output (defaults to a 'service' folder inside your Virtual Assistant's folder)                                                                |
 | --resourceGroup [name]        | (OPTIONAL) Name of your Virtual Assistant's resource group in Azure (defaults to your Virtual Assistant's bot name)                                                                 |
 | --appSettingsFile [path]      | (OPTIONAL) Path to your appsettings file (defaults to `appsettings.json` inside your Virtual Assistant's folder)                                                                    |
 | --cognitiveModelsFile [path]  | (OPTIONAL) Path to your Cognitive Models file (defaults to `cognitivemodels.json` inside your Virtual Assistant's folder)                                                           |
@@ -64,13 +64,13 @@ For Skills that require other Authentication connection configuration please fol
 An example on how to use it with a local Skill manifest file:
 
 ```bash
-botskills connect --localManifest "./skills/customSkill/customSkillManifest.json" --skillsFile "./skills.json" --cs --verbose
+botskills connect --localManifest "./skills/customSkill/customSkillManifest.json" --cs
 ```
 
-> **Note:** The paths to both the Skill Manifest and the Virtual Assistant Skills configuration file can be relative or absolute paths equally, and should be explicitly a `.json` file.
+> **Note:** The paths to the Skill Manifest can be relative or absolute paths equally, and should be explicitly a `.json` file.
 
 An example on how to use it with a remote Skill manifest:
 
 ```bash
-botskills connect --remoteManifest "http://<YOUR_SKILL_MANIFEST>.azurewebsites.net/api/skill/manifest" --skillsFile "./skills.json" --cs --verbose
+botskills connect --remoteManifest "http://<YOUR_SKILL_MANIFEST>.azurewebsites.net/api/skill/manifest" --cs
 ```
diff --git a/tools/botskills/docs/commands/disconnect.md b/tools/botskills/docs/commands/disconnect.md
@@ -19,10 +19,10 @@ botskills disconnect [options]
 | --ts                          | Determine your Virtual Assistant project structure to be a TypeScript-like structure                                                                                        |
 | --noRefresh                   | (OPTIONAL) Determine whether the model of your skills connected are not going to be refreshed (by default they are refreshed)                                               |
 | --languages [languages]       | (OPTIONAL) Comma separated list of locales used for LUIS culture (defaults to `en-us`)                                                                                      |
-| --dispatchFolder [path]       | (OPTIONAL) Path to the folder containing your Virtual Assistant's `.dispatch` file (defaults to `./deployment/resources/dispatch` inside your Virtual Assistant folder)  |
+| --dispatchFolder [path]       | (OPTIONAL) Path to the folder containing your Virtual Assistant's `.dispatch` file (defaults to `./deployment/resources/dispatch` inside your Virtual Assistant folder)     |
 | --outFolder [path]            | (OPTIONAL) Path for any output file that may be generated (defaults to your Virtual Assistant's root folder)                                                                |
-| --lgOutFolder [path]          | (OPTIONAL) Path for the Luis Generate output (defaults to a `service` folder inside your Virtual Assistant's folder)                                                              |
-| --skillsFile [path]           | (OPTIONAL) Path to your Virtual Assistant Skills configuration file (defaults to the `skills.json` inside your Virtual Assistant's folder)                                  |
+| --lgOutFolder [path]          | (OPTIONAL) Path for the Luis Generate output (defaults to a `service` folder inside your Virtual Assistant's folder)                                                        |
+| --appSettingsFile [path]      | (OPTIONAL) Path to your app settings file (defaults to `appsettings.json` inside your assistant's folder)                                                                   |
 | --cognitiveModelsFile [path]  | (OPTIONAL) Path to your Cognitive Models file (defaults to `cognitivemodels.json` inside your Virtual Assistant's folder)                                                   |
 | --verbose                     | (OPTIONAL) Output detailed information about the processing of the tool                                                                                                     |
 | -h, --help                    | Output usage information                                                                                                                                                    |

diff --git a/tools/botskills/docs/commands/list.md b/tools/botskills/docs/commands/list.md
@@ -11,8 +11,8 @@ botskills list [options]
 
 ## Options
 
-| Option                   | Description                                                             |
-|--------------------------|-------------------------------------------------------------------------|
+| Option                   | Description                                                                                                                                  |
+|--------------------------|--------------------------------------------------------------------------------------------------------------------------------------------- |
 | --appSettingsFile [path] | (OPTIONAL) Path to your appsettings file where the skills are stored (defaults to `appsettings.json` inside your Virtual Assistant's folder) |
-| --verbose                | (OPTIONAL) Output detailed information about the processing of the tool |
-| -h, --help               | Output usage information                                                |
+| --verbose                | (OPTIONAL) Output detailed information about the processing of the tool                                                                      |
+| -h, --help               | Output usage information                                                                                                                     |
diff --git a/tools/botskills/docs/commands/migrate.md b/tools/botskills/docs/commands/migrate.md
@@ -11,17 +11,15 @@ botskills migrate [options]
 
 ## Options
 
-| Option                   | Description                                                             |
-|--------------------------|-------------------------------------------------------------------------|
-| --sourceFile             | (OPTIONAL) Path to your skills.json file, which contains the skills that will be migrated (defaults to `\skills.json\` inside your Virtual Assistant's folder)  |
-| --destFile               | (OPTIONAL) (OPTIONAL) Path to your appsettings file. The skills information will be migrated to this file (defaults to `\appsettings.json\` inside your Virtual Assistant's folder)  |
-| --verbose                | (OPTIONAL) Output detailed information about the processing of the tool  |
-| -h, --help               | Output usage information  |                           
+| Option                   | Description                                                                                                                                                                          |
+|--------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| --sourceFile             | (OPTIONAL) Path to your skills.json file, which contains the skills that will be migrated (defaults to `\skills.json\` inside your Virtual Assistant's folder)                       |
+| --destFile               | (OPTIONAL) Path to your appsettings file. The skills information will be migrated to this file (defaults to `\appsettings.json\` inside your Virtual Assistant's folder)             |
+| --verbose                | (OPTIONAL) Output detailed information about the processing of the tool                                                                                                              |
+| -h, --help               | Output usage information                                                                                                                                                             |                           
 
 Here is an example of how to use the `Migrate` command:
 
-> **Note:** The paths to both the Skill Manifest and the Virtual Assistant Skills configuration file can be relative or absolute paths equally, and should be explicitly a `.json` file.
-
 ```bash
-botskills migrate --sourceFile "<YOUR-ASSISTANT_PATH>/skills.json" --destFile "<YOUR-ASSISTANT_PATH>/appsettings.json" --verbose
+botskills migrate --sourceFile "<YOUR-ASSISTANT_PATH>/skills.json" --destFile "<YOUR-ASSISTANT_PATH>/appsettings.json"
 ```