diff --git a/README.md b/README.md
index 290cbeae..8933940f 100644
--- a/README.md
+++ b/README.md
@@ -131,14 +131,6 @@ Yes. Puppeteer runs Chromium in [headless mode](https://developers.google.com/we
 
 Since Puppeteer's code is run by Node, it exists out-of-process to the controlled Chromium instance. This requires most of the API calls to be asynchronous to allow the necessary roundtrips to the browser.
 
-#### Q: What is the "Phantom Shim"?
-
-To make sure Puppeteer's API is comprehensive, we built [PhantomShim](https://github.com/GoogleChrome/puppeteer/tree/master/phantom_shim) - a lightweight phantomJS script runner built atop of Puppeteer API. We run phantomJS tests against PhantomShim with an ultimate goal to pass them all.
-
-To emulate PhantomJS which runs automation scripts in-process to the automated page, PhantomShim spawns [nested event loops](https://github.com/abbr/deasync). On practice, this might result in unpredictable side-effects and makes the shim unreliable, but this works pretty good for testing goals.
-
-> **NOTE** It is strictly **not recommended** to use PhantomShim out in the wild.
-
 #### Q: What is the difference between Puppeteer and Selenium / WebDriver?
 
 Selenium / WebDriver is a well-established cross-browser API that is useful for testing cross-browser support.
diff --git a/phantom_shim/README.md b/phantom_shim/README.md
new file mode 100644
index 00000000..cdbe8e78
--- /dev/null
+++ b/phantom_shim/README.md
@@ -0,0 +1,21 @@
+# PhantomShim
+
+PhantomShim is a phantomJS script runner built atop of Puppeteer API.
+
+### Q: Can I use PhantomShim to run my scripts?
+No.
+
+PhantomShim aims to pass PhantomJS tests rather then to be a valid PhantomJS script runner:
+- PhantomShim shortcuts a lot of corners (e.g. [handling only a few keys](https://github.com/GoogleChrome/puppeteer/blob/4269f6a1bb0c2d1cc27a9ed1132017669c33a259/phantom_shim/WebPage.js#L75) that are necessary to pass tests).
+- PhantomShim spawns [nested event loops](https://github.com/abbr/deasync) to emulate PhantomJS execution model. This might result in unpredictable side-effects, e.g. in [unexpected reenterability](https://github.com/GoogleChrome/puppeteer/blob/4269f6a1bb0c2d1cc27a9ed1132017669c33a259/phantom_shim/WebPage.js#L694).
+
+### Q: What's the purpose of PhantomShim? 
+The goal is to prove comprehensiveness of Puppeteer API.
+
+PhantomShim is built atop of Puppeteer API and is used to run PhantomJS tests.
+Whenever PhantomShim can't implement certain capability to pass phantomJS test, Puppeteer API is improved to make it possible.
+
+### Q: Are there plans to evolve PhantomShim into a real PhantomJS script runner?
+No.
+
+On the contrary, PhantomShim is likely to be removed from the Puppeteer repository as it passes all interesting PhantomJS tests.
\ No newline at end of file