diff --git a/README.md b/README.md
index ddd07b36..628224c1 100644
--- a/README.md
+++ b/README.md
@@ -9,37 +9,150 @@
 
 ## GitHub Actions Toolkit
 
-The GitHub Actions ToolKit provides a set of packages to make creating actions easier and drive consistency.
+The GitHub Actions ToolKit provides a set of packages to make creating actions easier.
 
 ## Packages
 
-The toolkit provides five separate packages.   See the docs for each action.
+:heavy_check_mark: [@actions/core](packages/core) 
 
-| Package | Description |
-| ------- | ----------- |
-| [@actions/core](packages/core) | Core functions for getting inputs, setting outputs, setting results, logging, secrets and environment variables |
-| [@actions/exec](packages/exec) | Functions necessary for running tools on the command line |
-| [@actions/io](packages/io) | Core functions for CLI filesystem scenarios |
-| [@actions/tool-cache](packages/tool-cache) | Functions necessary for downloading and caching tools |
-| [@actions/github](packages/github) | An Octokit client hydrated with the context that the current action is being run in |
+Provides functions for inputs, outputs, results, logging, secrets and variables. Read more [here](packages/core)
+
+```bash
+$ npm install @actions/core --save
+```
+<br/>
+
+:runner: [@actions/exec](packages/exec) 
+
+Provides functions to exec cli tools and process output. Read more [here](packages/exec)
+
+```bash
+$ npm install @actions/exec --save
+```
+<br/>
+
+:pencil2: [@actions/io](packages/io) 
+
+Provides disk i/o functions like cp, mv, rmRF, find etc. Read more [here](packages/io)
+
+```bash
+$ npm install @actions/io --save
+```
+<br/>
+
+:hammer: [@actions/tool-cache](packages/tool-cache) 
+
+Provides functions for downloading and caching tools.  e.g. setup-* actions. Read more [here](packages/tool-cache)
+
+```bash
+$ npm install @actions/tool-cache --save
+```
+<br/>
+
+:octocat: [@actions/github](packages/github) 
+
+Provides an Octokit client hydrated with the context that the current action is being run in. Read more [here](packages/github)
+
+```bash
+$ npm install @actions/github --save
+```
+<br/>
 
 ## Creating an Action with the Toolkit
 
-Actions run in a container or on the host machine.
+:question: [Choosing an action type](docs/action-types.md)
 
-[Choosing an action type](docs/action-types.md): Outlines the differences and why you would want to create a JavaScript or a container based action.
+Outlines the differences and why you would want to create a JavaScript or a container based action.
+<br/>
+<br/>
 
-[Hello World JavaScript Action](https://github.com/actions/hello-world-javascript-action): Illustrates how to create a simple hello world javascript action.
+[Hello World JavaScript Action](https://github.com/actions/hello-world-javascript-action)
 
-[JavaScript Action Walkthrough](https://github.com/actions/javascript-action): Walkthrough creating a JavaScript Action with tests, linting, workflow, publishing, and versioning.
+Illustrates how to create a simple hello world javascript action.
 
-[TypeScript Action Walkthrough](https://github.com/actions/typescript-action): Walkthrough creating a TypeScript Action with compilation, tests, linting, workflow, publishing, and versioning.
+```javascript
+...
+  const nameToGreet = core.getInput('who-to-greet');
+  console.log(`Hello ${nameToGreet}!`);
+...
+```
+<br/>
+<br/>
 
-[Docker Action Walkthrough](docs/container-action.md): Create an action that is delivered as a container and run with docker.
+[JavaScript Action Walkthrough](https://github.com/actions/javascript-action)
+ 
+ Walkthrough and template for creating a JavaScript Action with tests, linting, workflow, publishing, and versioning.
 
-[Docker Action Walkthrough with Octokit](docs/container-action-toolkit.md): Create an action that is delivered as a container which uses the toolkit.  This example uses the GitHub context to construct an Octokit client.
+ ```javascript
+PASS ./index.test.js
+  ✓ throws invalid number 
+  ✓ wait 500 ms 
+  ✓ test runs
 
-[Versioning](docs/action-versioning.md): Recommendations on versioning, releases and tagging your action.
+Test Suites: 1 passed, 1 total    
+Tests:       3 passed, 3 total
+ ```
+<br/>
+<br/>
+
+[TypeScript Action Walkthrough](https://github.com/actions/typescript-action) 
+
+Walkthrough creating a TypeScript Action with compilation, tests, linting, workflow, publishing, and versioning.
+
+```javascript
+import * as core from '@actions/core';
+
+async function run() {
+  try {
+    const ms = core.getInput('milliseconds');
+    console.log(`Waiting ${ms} milliseconds ...`)
+    ...
+
+  } catch (error) {
+    core.setFailed(error.message);
+  }
+}
+
+run();
+```
+<br/>
+<br/>
+
+[Docker Action Walkthrough](docs/container-action.md)
+
+Create an action that is delivered as a container and run with docker.
+
+```docker
+FROM alpine:3.10
+
+COPY LICENSE README.md /
+
+COPY entrypoint.sh /entrypoint.sh
+
+ENTRYPOINT ["/entrypoint.sh"]
+```
+<br/>
+<br/>
+
+[Docker Action Walkthrough with Octokit](https://github.com/actions/container-toolkit-action)
+
+Create an action that is delivered as a container which uses the toolkit.  This example uses the GitHub context to construct an Octokit client.
+
+```javascript
+    const myInput = core.getInput('myInput');
+    core.debug(`Hello ${myInput} from inside a container`);
+
+    const context = github.context;
+    console.log(`We can even get context data, like the repo: ${context.repo.repo}`)    
+```
+<br/>
+<br/>
+
+:curly_loop: [Versioning](docs/action-versioning.md)
+
+Recommendations on versioning, releases and tagging your action.
+<br/>
+<br/>
 
 ## Contributing