diff --git a/README.md b/README.md
new file mode 100644
index 0000000..35e8dec
--- /dev/null
+++ b/README.md
@@ -0,0 +1,85 @@
+# nix-develop (for GitHub Actions)
+
+This is the most explicit and compatible way I know of to load a nix shell environment into a GitHub Actions job.
+
+## Why?
+
+Why would you load a nix shell environment into a GitHub Actions job?
+
+If you haven't heard about nix, I highly recommend reading [a good introduction for it elsewhere](https://zero-to-nix.com/), but its relevant feature for our purposes right now is that you can use it to write succint and reliably reproducible cross-platform shell environments, and this can help you [manage build dependencies very well](https://determinate.systems/posts/nix-github-actions).  Currently this action cannot help you, so I wish you luck on your journey of discovery.
+
+If you have heard about nix, and you already have all your builds and tests expressed as derivations, then you do not need this action!  Your GitHub CI workflows are just checking out the code and running `nix-build` or `nix flake check`, and they benefit from result caching and build-skipping that the rest of us can only dream of!  Currently this action cannot help you, so only keep reading if you're curious.
+
+But finally, for the rest of us who already know the value of specifying shell environments in nix and using `nix develop`, and need to run commands in GitHub actions other _besides_ `nix-build` and `nix flake check`, this action is a better
+
+
+## How?
+
+How can you use this action usefully, and how does it interact with the rest of your system?
+
+Think of it like running `nix develop` in a way that works exactly like any other `setup-*` action:
+
+- In the step where you `use:` this action, it will run `nix develop`, which evaluates and build the `devShells.default` attribute of your repository's `flake.nix` file (or its `packages.default` attribute, or any other flake reference you like, (see below)). This will download any needed packages.
+- In all subsequent steps in that job, **including ones that `use:` third-party actions**, dependencies in that flake output will be added to PATH, and all environment variables in it will be present.
+
+(I bolded that last part because it isn't a feature I've seen in any other approach, and it's a feature I needed to install yarn via nix and then `use: actions/setup-node` to handle yarn caching.  Thanks for reading!)
+
+In other words, rather than [this](https://github.com/DeterminateSystems/nix-github-actions/blob/main/.github/workflows/nix.yml)...
+```yaml
+      - run: |
+          nix develop --command \
+            cargo fmt --check
+      - run: |
+          nix develop --command \
+            cargo-deny check
+      - run: |
+          nix develop --command \
+            eclint \
+              -exclude "Cargo.lock"
+      - run: |
+          nix develop --command \
+            codespell \
+              --skip target,.git \
+              --ignore-words-list crate
+```
+
+...or even this:
+```yaml
+      - run: cargo fmt --check
+        shell: nix develop --command bash -e {0}
+      - run: cargo-deny check
+        shell: nix develop --command bash -e {0}
+      - run: eclint \
+               -exclude "Cargo.lock"
+        shell: nix develop --command bash -e {0}
+      - run: codespell \
+              --skip target,.git \
+              --ignore-words-list crate
+        shell: nix develop --command bash -e {0}
+```
+
+...you can do this:
+```yaml
+      - uses: nicknovitski/nix-develop@1
+      - run: cargo fmt --check
+      - run: cargo-deny check
+      - run: eclint \
+               -exclude "Cargo.lock"
+      - run: codespell \
+              --skip target,.git \
+              --ignore-words-list crate
+```
+
+You can also pass arbitrary arguments, like using another flake reference:
+
+```yaml 
+  - uses: nicknovitski/nix-develop@1
+    with:
+      arguments: "github:DeterminateSystems/zero-to-nix#multi"
+```
+
+## Contributing
+
+Feel free!  The script can be run locally with any arguments you want to test, and unsurprisingly, running `nix develop` will give you the same dependencies used to test changes in CI.
+
+If you use [direnv](https://direnv.net), you can also bring those dependencies into your own shell with `nix-direnv-reload`.
diff --git a/action.yml b/action.yml
index 3bbf3b0..f059fef 100644
--- a/action.yml
+++ b/action.yml
@@ -1,5 +1,6 @@
-name: nix-develop-action
-description: Use nix development environments correctly with GitHub Actions
+name: Nix Develop Action
+description: Nix shell environments brought to GitHub Actions
+author: nick novitski
 inputs:
   arguments:
     description: Additional arguments to pass to the `nix develop` command