diff --git a/README.md b/README.md
index b25e8b0618..b3ded3914c 100644
--- a/README.md
+++ b/README.md
@@ -59,6 +59,15 @@ The command-line interface is generated via [docopt](http://docopt.org/). If you
 
 Please remember to update the [CHANGELOG](./CHANGELOG.md) when you make a change.
 
+## Generating a new abra-apps.json
+
+You'll need to install the following requirements:
+
+- [requests](https://docs.python-requests.org/en/master/) (`apt install python3-requests` / `pip install requests`)
+- [skopeo](https://github.com/containers/skopeo) (check the [install docs](https://github.com/containers/skopeo/blob/master/install.md))
+
+Then run `./bin/app-json.py` ([source](./bin/app-json.py)) and it will spit out the JSON file into [deploy/abra-apps.autonomic.zone/abra-apps.json](./deploy/abra-apps.autonomic.zone/abra-apps.json).
+
 ## Releasing
 
 ### `abra`
diff --git a/bin/app-json.py b/bin/app-json.py
index 61be448e3b..2b0ab4a0e1 100755
--- a/bin/app-json.py
+++ b/bin/app-json.py
@@ -1,7 +1,13 @@
 #!/usr/bin/env python3
 
+# Usage: ./app-json.py
+#
+# Gather metadata from Co-op Cloud apps in $ABRA_DIR/apps (default
+# ~/.abra/apps), and format it as JSON so that it can be hosted here:
+# https://abra-apps.autonomic.zone
+
 from json import dump
-from os import chdir, getcwd, listdir, mkdir
+from os import chdir, listdir, mkdir
 from os.path import exists, expanduser
 from pathlib import Path
 from re import findall, search