diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d7c4388
--- /dev/null
+++ b/README.md
@@ -0,0 +1,23 @@
+# go-test-action
+
+GitHub Action for running `go test ...` and getting rich summary and annotations as output.
+
+Powered by [Job Summaries](https://github.blog/2022-05-09-supercharging-github-actions-with-job-summaries/), this Action will generate a convenient interactive viewer for tests based on Go's [test2json](https://pkg.go.dev/cmd/test2json) output.
+
+## Example
+
+Tests are organized per package, with a brief summary of individual test results:
+
+![summary overview](docs/img/overview.png)
+
+Expand for per-test (with subtest) results and to view raw test output:
+
+![summary expanded](docs/img/expanded.png)
+
+## Inputs
+
+- `moduleDirectory` (optional): relative path to the directory containing the `go.mod` of the module you wish to test
+  - Default: `.`
+- `testArguments` (optional): arguments to pass to `go test`, `-json` will be prepended
+  - Default: `./...`
+
diff --git a/docs/img/expanded.png b/docs/img/expanded.png
new file mode 100644
index 0000000..cac8c51
Binary files /dev/null and b/docs/img/expanded.png differ
diff --git a/docs/img/overview.png b/docs/img/overview.png
new file mode 100644
index 0000000..63886df
Binary files /dev/null and b/docs/img/overview.png differ