[Botskills] Update Tool documentation (microsoft#1342)

* Update commands documentation * Fix typo, change one line * Fix typos in list.md file * Fix typos in connect-disconnect.md * Update how-to documentations * Update prerequisites and botskills readme * Restore Dispatch as prerequisite
bhushang19 · May 15, 2019 · 6849ee2 · 6849ee2
1 parent 0993afe
commit 6849ee2
Show file tree

Hide file tree

Showing 10 changed files with 73 additions and 58 deletions.
diff --git a/docs/howto/skills/addingskills.md b/docs/howto/skills/addingskills.md
@@ -3,10 +3,10 @@
 ## Prerequisites
 
 - [Node.js](https://nodejs.org/) version 10.8 or higher
-- Install the Dispatch CLI tool
+- Install the Dispatch, LUDown and LUISGen CLI tools
 
     ```shell
-    npm install -g botdispatch
+    npm install -g botdispatch ludown luisgen
     ```
 
 ## Adding Skills
@@ -16,12 +16,10 @@ We have two approaches to add Skills to your Virtual Assistant which can be used
 1. The first leverages a `add_remote_skill.ps1` PowerShell script included as part of your Virtual Assistant solution (located in the `Deployment\Scripts` folder of your assistant).
 2. `botskills` command line tool which is in preview.
 
-> Skills requiring authentication (e.g. the productivity skills) should be added using the PowerShell script at this time.
-
-If you wish to use the `botskills` CLI then you can install using the following npm command:
+If you wish to use the `botskills` CLI then you can install it using the following npm command:
 
 ```bash
-npm install -g botdispatch, botskills
+npm install -g botskills
 ```
 
 > Your Virtual Assistant must have been deployed using the [deployment tutorial](/docs/tutorials/assistantandskilldeploymentsteps.md) before using the add_remote_skill `botskills` tool as it relies on the Dispatch models being available and a deployed Bot for authentication connection information.
@@ -44,7 +42,7 @@ The PowerShell script and CLI provides automation of all key steps required to a
 
 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 `skills.json` file present.
 
-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.
+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.
 
 - PowerShell:
 
@@ -58,7 +56,7 @@ The `--luisFolder` parameter can be used to point the Skill CLI at the source LU
 botskills connect --botName YOUR_BOT_NAME --remoteManifest "http://<YOUR_SKILL_MANIFEST>.azurewebsites.net/api/skill/manifest" --luisFolder [path] --cs
 ```
 
-See the [Skill CLI documentation](/lib/typescript/botskills/docs/connect-disconnect.md) for detailed CLI documentation,
+See the [Skill CLI documentation](/lib/typescript/botskills/docs/connect-disconnect.md) for detailed CLI documentation.
 
 ## Manual Authentication Connection configuration
 
@@ -94,6 +92,7 @@ botskills:
 botskills disconnect --skillId SKILL_ID
 ```
 
+> Note: The id of the Skill can also be aquired using the `botskills list` command. You can check the [Skill CLI documentation](/lib/typescript/botskills/docs/list.md) on this command.
 ## Updating an existing Skill to reflect changes to Actions or LUIS model
 
 > A botskills refresh command will be added shortly. In the meantime, run the above disconnect command and then connect the skill again.
diff --git a/docs/tutorials/csharp/skill.md b/docs/tutorials/csharp/skill.md
@@ -130,7 +130,7 @@ To add your new Skill to your assistant/Bot, run the following command from a co
 botskills connect --botName YOUR_BOT_NAME --remoteManifest "http://<YOUR_SKILL_MANIFEST>.azurewebsites.net/api/skill/manifest" --luisFolder "<YOUR-SKILL_PATH>\Deployment\Resources\LU\en\" --cs
 ```
 
-See the [Adding Skills](/docs/advanced/skills/addingskills.md) for more detail on how to add skills.
+See the [Adding Skills](/docs/howto/skills/addingskills.md) for more detail on how to add skills.
 
 ## Testing your Skill
 

diff --git a/docs/tutorials/typescript/customizeassistant.md b/docs/tutorials/typescript/customizeassistant.md
@@ -139,4 +139,4 @@ You can now leverage multiple QnA sources as a part of your assistant's knowledg
 
 ## Next steps
 
-Now that you've learned how to personalize a Virtual Assistant, it's time to [create a new Bot Framework Skill](/docs/tutorials/csharp/skill.md).
+Now that you've learned how to personalize a Virtual Assistant, it's time to [create a new Bot Framework Skill](/docs/tutorials/typescript/skill.md).
diff --git a/docs/tutorials/typescript/skill.md b/docs/tutorials/typescript/skill.md
@@ -64,7 +64,7 @@ A Bot Framework Skill app (in TypeScript) that greets a new user.
 Install the botbuilder-assistant generator
 
 ```bash
-    npm install -g generator-botbuilder-assistant
+npm install -g generator-botbuilder-assistant
 ```
 
 Now you can execute the Skill sub-generator with this command.
@@ -189,15 +189,15 @@ You can now publish your Skill to Azure using the usual deployment tools and ena
 
 To add your new Skill to your assistant/Bot, run the following command from a command prompt **within the directory of your assistant/Bot**. At this time we have a powershell script and a preview botskills CLI.
 
-``
+```bash
 .\Deployment\scripts\add_remote_skill.ps1 -botName "YOUR_BOT_NAME" -manifestUrl https://YOUR_SKILL.azurewebsites.net/api/skill/manifest
-``
+```
 
 ```bash
-botskills connect --botName YOUR_BOT_NAME --remoteManifest "http://<YOUR_SKILL_MANIFEST>.azurewebsites.net/api/skill/manifest" --luisFolder "<YOUR-SKILL_PATH>\deployment\resources\LU\en\" --ts 
+botskills connect --botName YOUR_BOT_NAME --remoteManifest "http://<YOUR_SKILL_MANIFEST>.azurewebsites.net/api/skill/manifest" --luisFolder "<YOUR-SKILL_PATH>\deployment\resources\LU\en" --ts
 ```
 
-See the [Adding Skills](/docs/advanced/skills/addingskills.md) for more detail on how to add skills.
+See the [Adding Skills](/docs/howto/skills/addingskills.md) for more detail on how to add skills.
 
 ## Testing your Skill
 

diff --git a/lib/typescript/botskills/README.md b/lib/typescript/botskills/README.md
@@ -3,6 +3,11 @@ The Botskills tool is a command line tool to manage the skills connected to your
 
 ## Prerequisite
 - [Node.js](https://nodejs.org/) version 10.8 or higher
+- Install the LUDown and LUISGen CLI tools
+
+```shell
+npm install -g ludown luisgen
+```
 
 ## Installation
 To install using npm
@@ -20,21 +25,14 @@ npm uninstall -g botskills
 - [Disconnect](./docs/connect-disconnect.md) a Skill from your assistant
 - [List](./docs/list.md) all Skills connected to your assistant
 
-## Nightly builds
-Nightly 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.
+## 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.
 
-You can get the latest nightly build of Botskills from the [BotBuilder MyGet]() feed. To install the nightly
-```bash
-npm config set registry https://botbuilder.myget.org/F/aitemplates/npm/
-```
-Install using npm
-```bash
-npm install -g botskills
-```
-To reset registry
+You can get the latest daily build of Botskills from the [BotBuilder MyGet]() feed. To install the daily
 ```bash
-npm config set registry https://registry.npmjs.org/
+npm install -g botskills --registry https://botbuilder.myget.org/F/aitemplates/npm/
 ```
 
 ## Further Reading
-- [Create and customize Skills for your assistant](https://github.com/Microsoft/AI/blob/master/docs/skills/typescript/create.md).
+- [Create and customize Skills for your assistant](../../../docs/tutorials/typescript/skill.md)
+- [Connect a Skill to your Assistant](../../../docs/howto/skills/addingskills.md)
diff --git a/lib/typescript/botskills/docs/connect-disconnect.md b/lib/typescript/botskills/docs/connect-disconnect.md
@@ -1,6 +1,10 @@
 # Connect a Skill to your assistant
 
-To connect a Skill to your assistant:
+The `connect` command allows you to connect a Skill, be it local or remote, to your assistant bot. The Skill and assistant can be in different coding languages without problem, this is, you can connect a  Skill coded in C# into an assistant coded in TypeScript, but be sure to specify your assistants coding language using `--cs` or `--ts`.
+
+> **Tip:** It's highly advisable to execute this command from the root folder of your assistant bot, so if you are using the suggested folder structure from the Templates, you may ommit most of the optional arguments, as they default to the expected values from the Templates' folder structure.
+
+The basic command to connect a Skill to your assistant:
 
 ```bash
 botskills connect [options]
@@ -13,54 +17,67 @@ botskills connect [options]
 | -b, --botName \<name>         | Name of your assistant bot                                                                                                                                  |
 | -l, --localManifest \<path>   | Path to local Skill Manifest file                                                                                                                           |
 | -r, --remoteManifest \<url>   | URL to remote Skill Manifest                                                                                                                                |
+| --cs                          | Determine your assistant project structure to be a csharp-like structure                                                                                    |
+| --ts                          | Determine your assistant project structure to be a TypeScript-like structure                                                                                |
 | --dispatchName [name]         | (OPTIONAL) Name of your assistant's '.dispatch' file (defaults to the name displayed in your Cognitive Models file)                                         |
 | --language [language]         | (OPTIONAL) Locale 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 assistant folder)             |
 | --dispatchFolder [path]       | (OPTIONAL) Path to the folder containing your assistant's '.dispatch' file (defaults to './deployment/resources/dispatch/en' inside your assistant folder)  |
-| --outFolder [path]            | (OPTIONAL) Path for any output file that may be generated (defaults to your assistant's root folder')                                                       |
-| --lgOutFolder [path]          | (OPTIONAL) Path for the LuisGen output (defaults to a 'service' folder inside your assistant's folder')                                                     |
+| --outFolder [path]            | (OPTIONAL) Path for any output file that may be generated (defaults to your assistant's root folder)                                                        |
+| --lgOutFolder [path]          | (OPTIONAL) Path for the LuisGen output (defaults to a 'service' folder inside your assistant's folder)                                                      |
 | --skillsFile [path]           | (OPTIONAL) Path to your assistant Skills configuration file (defaults to the 'skills.json' inside your assistant's folder)                                  |
 | --resourceGroup [name]        | (OPTIONAL) Name of your assistant's resource group in Azure (defaults to your assistant's bot name)                                                         |
-| --appSettingsFile [path]      | (OPTIONAL) Path to your app settings file (defaults to 'appsettings.json' inside your assistant's folder)                                                   |
+| --appSettingsFile [path]      | (OPTIONAL) Path to your appsettings 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 assistant's folder)                                           |
 | --verbose                     | (OPTIONAL) Output detailed information about the processing of the tool                                                                                     |
 | -h, --help                    | Output usage information                                                                                                                                    |
 
 An example on how to use it with a local Skill manifest file:
 
 ```bash
-botskills connect --localManifest "./skills/customSkill/customSkillManifest.json" --assistantSkills "./skills.json" --verbose 
+botskills connect --localManifest "./skills/customSkill/customSkillManifest.json" --skillsFile "./skills.json" --cs --verbose
 ```
 
 > **Note:** The paths to both the Skill Manifest and the assistant Skills configuration file 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?inlineTriggerUtterances=false" --assistantSkills "./skills.json" --verbose 
+botskills connect --remoteManifest "http://<YOUR_SKILL_MANIFEST>.azurewebsites.net/api/skill/manifest?inlineTriggerUtterances=false" --skillsFile "./skills.json" --cs --verbose
 ```
 
 # Disconnect a Skill from your assistant
 
-To disconnect a Skill from your assistant:
+The `disconnect` command allows you to disconnect a Skill from your assistant. You can always check the Skills already connected to your assistant using the [`list` command](./list.md). Remember to specify the coding language of your assistant using `--cs` or `--ts`.
+
+> **Tip:** It's highly advisable to execute this command from the root folder of your assistant bot, so if you are using the suggested folder structure from the Templates, you may ommit most of the optional arguments, as they default to the expected values from the Templates' folder structure.
+
+The basic command to disconnect a Skill from your assistant:
 
 ```bash
 botskills disconnect [option]
 ```
 
 ### Options
 
-| Option                   | Description                                                             |
-|--------------------------|-------------------------------------------------------------------------|
-| -n, --skillName <path>   | Name or id of the skill to remove from your assistant (case sensitive)  |
-| -f, --skillsFile <path>  | Path to the assistant Skills configuration file                         |
-| --verbose                | (OPTIONAL) Output detailed information about the processing of the tool |
-| -h, --help               | Output usage information                                                |
+| Option                        | Description                                                                                                                                                 |
+|-------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| -i, --skillId \<id>           | Id of the skill to remove from your assistant (case sensitive)                                                                                              |
+| --cs                          | Determine your assistant project structure to be a csharp-like structure                                                                                    |
+| --ts                          | Determine your assistant project structure to be a TypeScript-like structure                                                                                |
+| --dispatchName [name]         | (OPTIONAL) Name of your assistant's '.dispatch' file (defaults to the name displayed in your Cognitive Models file)                                         |
+| --dispatchFolder [path]       | (OPTIONAL) Path to the folder containing your assistant's '.dispatch' file (defaults to './deployment/resources/dispatch/en' inside your assistant folder)  |
+| --outFolder [path]            | (OPTIONAL) Path for any output file that may be generated (defaults to your assistant's root folder)                                                        |
+| --lgOutFolder [path]          | (OPTIONAL) Path for the LuisGen output (defaults to a 'service' folder inside your assistant's folder)                                                      |
+| --skillsFile [path]           | (OPTIONAL) Path to your assistant Skills configuration file (defaults to the 'skills.json' inside your assistant's folder)                                  |
+| --cognitiveModelsFile [path]  | (OPTIONAL) Path to your Cognitive Models file (defaults to 'cognitivemodels.json' inside your assistant's folder)                                           |
+| --verbose                     | (OPTIONAL) Output detailed information about the processing of the tool                                                                                     |
+| -h, --help                    | Output usage information                                                                                                                                    |
 
 An example on how to use it:
 
 ```bash
-botskills disconnect --skillName "customSkill" --assistantSkills "./skills.json" --verbose
+botskills disconnect --skillId "customSkill" --skillsFile "./skills.json" --cs --verbose
 ```
 
 > **Note:** The path to the assistant Skills configuration file can be relative or absolute path, and should be explicitly a `.json` file.
diff --git a/lib/typescript/botskills/docs/list.md b/lib/typescript/botskills/docs/list.md
@@ -1,14 +1,18 @@
-# Listing connected skills
+# Listing connected Skills
 
-To acces the list of connected skills:
+The `list` command allows you to acknowledge the Skills currently connected to your assistant.
+
+> **Tip:** It's highly advisable to execute this command from the root folder of your assistant bot, so if you are using the suggested folder structure from the Templates, you may omit most of the optional arguments, as they default to the expected values from the Templates' folder structure.
+
+The basic command to list the Skills connected to your assistant:
 ```bash
 botskills list [options]
 ```
 
 ### Options
 
-| Option                        | Description                                                             |
-|-------------------------------|-------------------------------------------------------------------------|
-| -a, --assistantSkills <path>  | Path to the assistant Skills configuration file                         |
-| --verbose                     | (OPTIONAL) Output detailed information about the processing of the tool |
-| -h, --help                    | Output usage information                                                |
+| Option                   | Description                                                             |
+|--------------------------|-------------------------------------------------------------------------|
+| -f, --skillsFile [path]  | (OPTIONAL) Path to the assistant Skills configuration file              |
+| --verbose                | (OPTIONAL) Output detailed information about the processing of the tool |
+| -h, --help               | Output usage information                                                |
Original file line number	Diff line number	Diff line change
Expand Up		@@ -139,4 +139,4 @@ You can now leverage multiple QnA sources as a part of your assistant's knowledg

		## Next steps

		Now that you've learned how to personalize a Virtual Assistant, it's time to [create a new Bot Framework Skill](/docs/tutorials/csharp/skill.md).
		Now that you've learned how to personalize a Virtual Assistant, it's time to [create a new Bot Framework Skill](/docs/tutorials/typescript/skill.md).