Update documentation

Split out README into INFO and SETTINGS.

INFO.md

@@ -0,0 +1,27 @@
+If you develop web applications or services running on Node.js, you want to make
+sure your code builds and passes tests. This skill will build and test your code
+on every push of commits or tags.
+
+When writing JavaScript, or any one of the numerous languages that transpile
+into JavaScript, sooner or later you develop code that you want to use in
+multiple projects. The solution is to create and publish an npm package. This
+skill is also able to create and publish your code as an npm package to either
+the default npm.js registry or your own, private registry.
+
+This skill supports the follow features:
+
+-   Set up this skill with multiple configurations to run your tests on
+    different versions of Node.js and npm
+-   Configure the build to match _your_ desired workflow
+-   Provide a consistent build configuration across _all_ your projects
+-   Optionally publish both public and restricted packages to a variety of npm
+    registries
+-   Install the custom tools needed for your build and test to complete
+    successfully
+-   Create custom npm dist tags
+-   Cache files from build to build
+-   Trigger npm builds on pushes of commits and/or tags
+
+### Build and publish an npm package
+
+![Build and publish npm package](docs/images/npm-package-publish.png)

README.md

@@ -1,132 +1,81 @@
 # `atomist/npm-build-skill`
 
-<!---atomist-skill-description:start--->
+Run NPM scripts to build and optionally publish your JavaScript project.
 
-Run npm scripts to compile or test your JavaScript project
+:sparkles: [_**View this skill in the Atomist Skills Catalog**_][atomist-skill]
+to enable this skill on your repositories. :sparkles:
 
-<!---atomist-skill-description:end--->
+See the [Atomist website][atomist] for general information about Atomist Skills
+and the [Atomist documentation site][atomist-doc] for instructions on how to get
+started using Atomist Skills.
 
----
-
-<!---atomist-skill-readme:start--->
-
-# What it's useful for
-
-Run npm scripts with different versions of Node.js and npm in a consistent
-container environment. When your tests pass, you can immediately publish the
-package to the npmjs.com Registry.
-
--   Set up this skill with multiple configurations to run your tests on
-    different versions of Node.js
--   Decide to publish your packages consistently from a centralized
-    configuration
--   Own the container environment and install tools needed for your build and
-    test
-
-# Before you get started
-
-Connect and configure this integration:
-
--   **GitHub**
--   **npmjs.com Registry**
--   **Slack or Microsoft Teams**
-
-The **GitHub** integration must be configured in order to use this skill. At
-least one repository must be selected. If you want to publish a npm package to
-npmjs.com, you need to connect an **npmjs.com Registry**. We recommend that you
-configure the **Slack** or **Microsoft Teams** integration.
-
-# How to configure
-
-1. **Configure npm scripts to run**
-
-    Provide the name of the npm scripts from the project's `package.json`
-    scripts section. The order in which the scripts are specified is the order
-    in which they will get executed. If one script fails, the execution stops.
-
-1. **Define Node.js version**
-
-    Provide a valid Node.js version or alias as used by
-    [nvm](https://github.com/nvm-sh/nvm#usage).
-
-1. **Decide if the package should be published after running the scripts**
-
-    When checked, the skill will run `npm publish` after successful execution of
-    the configured scripts.
-
-1. **Define package access**
-
-    `npm publish` allows to publish packages with `public` or `restricted`
-    access.
+[atomist-skill]:
+    https://go.atomist.com/catalog/skills/atomist/npm-build-skill
+    "Atomist Skills Catalog - Automate All Your Software Tasks"
+[atomist-doc]: https://docs.atomist.com/ "Atomist Documentation"
 
-1. **Create additional npm distribution tags**
+## Contributing
 
-    Specify additional
-    [distribution tags](https://docs.npmjs.com/adding-dist-tags-to-packages)
-    like `next` or `stable` for the published version of the package.
+Contributions to this project from community members are encouraged and
+appreciated. Please review the [Contributing Guidelines](CONTRIBUTING.md) for
+more information. Also see the [Development](#development) section in this
+document.
 
-1. **Tag the Git commit on successful execution**
+## Code of conduct
 
-    Tag the Git commit with the version of the packcage that was just published.
+This project is governed by the [Code of Conduct](CODE_OF_CONDUCT.md). You are
+expected to act in accordance with this code by participating. Please report any
+unacceptable behavior to [email protected].
 
-1. **Specify an optional bash command**
+## Connect
 
-    In case your npm scripts need different tools - like databases - you can use
-    this parameter to install such tools. Provide a command that can in a Ubuntu
-    20.04 LTS container.
+Follow [@atomist][atomist-twitter] on Twitter and [The Atomist
+Blog][atomist-blog].
 
-    Here's is an example on how to install MongoDB and start it:
+[atomist-twitter]: https://twitter.com/atomist "Atomist on Twitter"
+[atomist-blog]: https://blog.atomist.com/ "The Atomist Blog"
 
-    ```bash
-    apt-get update \
-        && apt-get install -y wget libcurl4 openssl tar \
-        && wget https://fastdl.mongodb.org/linux/mongodb-linux-x86_64-ubuntu1804-4.2.8.tgz \
-        && tar -zxvf mongodb-linux-x86_64-ubuntu1804-4.2.8.tgz \
-        && cp mongodb-linux-x86_64-ubuntu1804-4.2.8/bin/* /usr/local/bin/ \
-        && rm -rf mongodb-linux-x86_64-ubuntu1804-4.2.8* \
-        && mkdir -p /var/lib/mongo \
-        && mkdir -p /var/log/mongodb \
-        && mongod --dbpath /var/lib/mongo --logpath /var/log/mongodb/mongod.log --fork
-    ```
+## Support
 
-1. **Enable file caching for faster execution times**
+General support questions should be discussed in the `#support` channel in the
+[Atomist community Slack workspace][slack].
 
-    You can speed up executions times by enabling file caching for certain
-    artifacts — for example, dependencies — by providing glob patterns of files
-    you'd like to cache between executions.
+If you find a problem, please create an [issue](../../issues).
 
-    Note that only files within the `/atm/home` directory can be cached.
+## Development
 
-    Caching the npm dependency cache could be accomplished with the following
-    pattern:
+You will need to install [Node.js][node] to build and test this project.
 
-    `.npm/**`
+[node]: https://nodejs.org/ "Node.js"
 
-1. **Determine repository scope**
+### Build and test
 
-    By default, this skill will be enabled for all repositories in all
-    organizations you have connected.
+Install dependencies.
 
-    To restrict the organizations or specific repositories on which the skill
-    will run, you can explicitly choose organization(s) and repositories.
+```
+$ npm ci
+```
 
-# How to build and publish your npm projects
+Use the `build` package script to compile, test, lint, and build the
+documentation.
 
-1. **Configure at least the npm scripts to run**
+```
+$ npm run build
+```
 
-1. **Make some pushes to your configured repositories**
+### Release
 
-1. **Enjoy automatic and consistent execution of npm scripts on every push**
+Releases are created by pushing a release [semantic version][semver] tag to the
+repository, Atomist Skills take care of the rest.
 
-To create feature requests or bug reports, create an
-[issue in the repository for this skill](https://github.com/atomist-skills/npm-build-skill/issues).
-See the [code](https://github.com/atomist-skills/npm-build-skill) for the skill.
+To make this skill globally available, set its maturity to "stable" via the set
+maturity drop-down in its Atomist Community Slack channel.
 
-<!---atomist-skill-readme:end--->
+[semver]: https://semver.org/ "Semantic Version"
 
 ---
 
 Created by [Atomist][atomist]. Need Help? [Join our Slack workspace][slack].
 
-[atomist]: https://atomist.com/ "Atomist - How Teams Deliver Software"
+[atomist]: https://atomist.com/ "Atomist - Automate All the Software Things"
 [slack]: https://join.atomist.com/ "Atomist Community Slack"

SETTINGS.md

@@ -0,0 +1,135 @@
+## Before you get started
+
+Connect and configure these integrations:
+
+1.  [**GitHub**][github] _(required)_
+2.  [**npm Registry**][npm] _(optional)_
+3.  [**Slack**][slack] or [**Microsoft Teams**][msteams] _(optional)_
+
+[github]: https://go.atomist.com/catalog/integration/github "GitHub Integration"
+[npm]:
+    https://go.atomist.com/catalog/integration/npmjs-registry
+    "npm Registry Integration"
+[slack]: https://go.atomist.com/catalog/integration/slack "Slack Integration"
+[msteams]:
+    https://go.atomist.com/catalog/integration/microsoft-teams
+    "Microsoft Teams Integration"
+
+## How to configure
+
+1.  **NPM Registry**
+
+    ![npm registry](docs/images/npm-registry.png)
+
+    Select the npm registry from the list of available registries. If you have
+    not already configured an npm registry, only your GitHub organizations, via
+    the GitHub Packages npm registry, will appear in the list.
+
+2.  **Triggers**
+
+    ![Event triggers for skill](docs/images/trigger.png)
+
+    Select the events that will trigger execution of the skill. You can select
+    GitHub pushes, GitHub tags, or both.
+
+3.  **npm scripts to run**
+
+    ![npm scripts to run](docs/images/scripts.png)
+
+    Provide the name of the npm scripts from the project's `package.json`
+    scripts section. This can be useful if you package needs compiled, tested,
+    or otherwise transformed before being published. Only provide the name of
+    the script, not the full `npm run SCRIPT` command. The order in which the
+    scripts are specified is the order in which they will get executed. If one
+    script fails, the execution stops. Scripts are run using
+    `npm run --if-present SCRIPT`, so it is safe to include scripts that are
+    only present in some of your packages.
+
+4.  **Node.js version**
+
+    ![Node.js version](docs/images/node-version.png)
+
+    Provide a valid Node.js version or alias as used by
+    [nvm](https://github.com/nvm-sh/nvm#usage), e.g., `12.3.1` or `14`.
+
+5.  **Publish package**
+
+    ![Publish package](docs/images/publish.png)
+
+    When checked, the skill will run `npm publish` after successful execution of
+    the configured scripts. This will create the package and publish it to the
+    configured npm registry. If not checked, the package will not be published.
+
+    _You must have an npm registry configured to publish packages._
+
+6.  **Package access**
+
+    ![Package access](docs/images/access.png)
+
+    `npm publish` allows to publish packages with `public` or `restricted`
+    access.
+
+7.  **Create additional npm distribution tags**
+
+    ![Package dist tags](docs/images/tags.png)
+
+    Specify additional [distribution tags][dist-tag] like `next` or `stable` for
+    the published version of the package. In addition to the tags you specify
+    here, if the skill is running on the default branch, it adds the `next` tag.
+    Similarly, if the skill is running on a git tag that looks like a release
+    [semantic version][semver], the `latest` tag is added, making the published
+    version the new default.
+
+8.  **Specify an optional bash command**
+
+    ![Shell command](docs/images/shell-command.png)
+
+    In case your npm scripts need different tools - like databases - you can use
+    this parameter to install such tools. Provide a command that can in a Ubuntu
+    20.04 LTS container. This command is after the code is checked out but
+    before Node.js is setup or any npm commands are run.
+
+    Here's is an example on how to install MongoDB and start it:
+
+    ```bash
+    apt-get update \
+        && apt-get install -y wget libcurl4 openssl tar \
+        && wget https://fastdl.mongodb.org/linux/mongodb-linux-x86_64-ubuntu1804-4.2.8.tgz \
+        && tar -zxvf mongodb-linux-x86_64-ubuntu1804-4.2.8.tgz \
+        && cp mongodb-linux-x86_64-ubuntu1804-4.2.8/bin/* /usr/local/bin/ \
+        && rm -rf mongodb-linux-x86_64-ubuntu1804-4.2.8* \
+        && mkdir -p /var/lib/mongo \
+        && mkdir -p /var/log/mongodb \
+        && mongod --dbpath /var/lib/mongo --logpath /var/log/mongodb/mongod.log --fork
+    ```
+
+9.  **Enable file caching for faster execution times**
+
+    ![Skill file caching](docs/images/cache.png)
+
+    You can speed up executions times by enabling file caching for certain
+    artifacts — for example, dependencies — by providing glob patterns of files
+    you'd like to cache between executions.
+
+    Note that only files within the `/atm/home` directory can be cached.
+
+    Caching the npm dependency cache could be accomplished with the pattern
+    `.npm/**/*`.
+
+10. **Determine repository scope**
+
+    ![Repository filter](docs/images/repo-filter.png)
+
+    By default, this skill will be enabled for all repositories in all
+    organizations you have connected.
+
+    To restrict the organizations or specific repositories on which the skill
+    will run, you can explicitly choose organization(s) and repositories.
+
+11. **Activate the skill**
+
+    Save your configuration and activate the skill by clicking the "Enable
+    skill" button.
+
+[dist-tag]: https://docs.npmjs.com/adding-dist-tags-to-packages "npm dist-tags"
+[semver]: https://semver.org/ "Semantic Versioning"

skill.ts

@@ -27,6 +27,7 @@ import { Configuration } from "./lib/configuration";
 export const Skill = skill<
 	Configuration & { repos: any; subscription_filter: any }
 >({
+	description: "Run npm scripts to compile or test your JavaScript project",
 	displayName: "npm Build",
 	categories: [Category.DevOps],