diff --git a/README.md b/README.md
index 99967ebd..527f996b 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,13 @@
 # vscode-extension-samples
+
 Sample code illustrating the VS Code extension APIs.
+
+* [Editor Decoration](/decorator-sample/README.me)
+* [Virtual Documents](/contentprovider-sample/README.md)
+* [Preview Html](/previewhtml-sample/README.md)
+
+# How to run locally
+
+* `git clone`
+* `npm run install-all`
+* run one of `npm run compile-decorator`, `npm run compile-previewhtml`, or `compile-contentprovider` 
diff --git a/contentprovider-sample/README.md b/contentprovider-sample/README.md
index 34b66796..0794660d 100644
--- a/contentprovider-sample/README.md
+++ b/contentprovider-sample/README.md
@@ -19,3 +19,7 @@ It is not intended as a product quality extension.
 - The content provider uses the decoration API to highlight matches inside the generated document
 
 
+# How to run locally
+
+* `npm run compile` to start the compiler in watch mode
+* open this folder in VS Code and press `F5`
\ No newline at end of file
diff --git a/decorator-sample/README.md b/decorator-sample/README.md
index 9b89550e..6b0f0fd9 100644
--- a/decorator-sample/README.md
+++ b/decorator-sample/README.md
@@ -9,3 +9,8 @@ demonstrates some of the decorator features such as borders, background colors,
 and hovers. 
 
 
+
+# How to run locally
+
+* `npm run compile` to start the compiler in watch mode
+* open this folder in VS Code and press `F5`
\ No newline at end of file
diff --git a/previewhtml-sample/README.md b/previewhtml-sample/README.md
index 693bb6ff..f87c2b89 100644
--- a/previewhtml-sample/README.md
+++ b/previewhtml-sample/README.md
@@ -20,4 +20,7 @@ The purpose of the extension is to show a preview of the properties in the decla
 - The generated HTML document contains a link that invokes a contributed command to highlight the CSS rule in the source editor
 - The generated HTML document is then opened in an editor in the 2nd Column using the command `vscode.previewHtml`.
 
+# How to run locally
 
+* `npm run compile` to start the compiler in watch mode
+* open this folder in VS Code and press `F5`
\ No newline at end of file