diff --git a/README.md b/README.md
index 1911cb5..9857c27 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,42 @@
 # shells
 
-oil
\ No newline at end of file
+This is a collection of general purpose and project specific nix shells.
+
+They are mostly for personal use.
+
+
+### Add adhoc `.envrc`
+
+The shells can easily be used in a project by creating a `.envrc` file, with contents like:
+
+```
+use flake git+ssh://git.pvv.ntnu.no/oysteikt/shells.git#rust
+```
+
+I've added `.envrc` to my global gitignore, so I don't accidentally commit these.
+
+
+### Add to flake registry
+
+```nix
+{
+  # NixOS / home-manager (API is similar)
+  nix.registry."shells".to = {
+    type = "git";
+    url = "https://git.pvv.ntnu.no/oysteikt/shells.git";
+    ref = "main";
+  };
+}
+```
+
+Lets you do this:
+
+```bash
+$ nix develop shells#rust
+```
+
+As well as shorthands in `.envrc`:
+
+```
+use flake shells#rust
+```