diff --git a/plugins/circleci/README.md b/plugins/circleci/README.md
index 46d48e9411..d1a2a7c9e0 100644
--- a/plugins/circleci/README.md
+++ b/plugins/circleci/README.md
@@ -1,6 +1,49 @@
-# Title
-Welcome to the circleci plugin!
+# <img src="./src/assets/circle-logo-badge-black.png" width="32" /> CircleCI Plugin
 
-## Sub-section 1
+Website: [https://circleci.com/](https://circleci.com/)
 
-## Sub-section 2
+<img src="./src/assets/screenshot-1.png" />
+<img src="./src/assets/screenshot-2.png" />
+## Setup
+
+0. If you have standalone app (you didn't clone this repo), then do
+
+```bash
+yarn add @backstage/plugin-circleci
+```
+
+1. Add plugin API to your Backstage instance:
+
+```js
+// packages/app/src/api.ts
+import { ApiHolder } from '@backstage/core';
+import { CircleCIApi, circleCIApiRef } from '@backstage/plugin-circleci';
+
+const builder = ApiRegistry.builder();
+builder.add(circleCIApiRef, new CircleCIApi(/* optional custom url for your own CircleCI instance */));
+
+export default builder.build() as ApiHolder;
+```
+
+2. Add plugin itself:
+
+```js
+// packages/app/src/plugins.ts
+export { plugin as Circleci } from '@backstage/plugin-circleci';
+```
+
+3. Run app with `yarn start` and navigate to `/circleci/settings`
+4. Enter project credentials and **project** token, acquired according to [https://circleci.com/docs/2.0/managing-api-tokens/](https://circleci.com/docs/2.0/managing-api-tokens/)
+
+## Features
+
+- List top 50 builds for a project
+- Dive into one build to see logs
+- Polling
+- Retry builds
+
+## Limitations
+
+- Currently working only with project token (personal credentials WIP)
+- Currently only top 50 builds in table view
+- CircleCI has pretty strict rate limits per token, be careful with opened tabs
diff --git a/plugins/circleci/src/assets/circle-logo-badge-black.png b/plugins/circleci/src/assets/circle-logo-badge-black.png
new file mode 100644
index 0000000000..dc5de12c8a
Binary files /dev/null and b/plugins/circleci/src/assets/circle-logo-badge-black.png differ
diff --git a/plugins/circleci/src/assets/screenshot-1.png b/plugins/circleci/src/assets/screenshot-1.png
new file mode 100644
index 0000000000..2c84d8a828
Binary files /dev/null and b/plugins/circleci/src/assets/screenshot-1.png differ
diff --git a/plugins/circleci/src/assets/screenshot-2.png b/plugins/circleci/src/assets/screenshot-2.png
new file mode 100644
index 0000000000..8c4fef13b9
Binary files /dev/null and b/plugins/circleci/src/assets/screenshot-2.png differ