diff --git a/software/AGENTS.md b/software/AGENTS.md
new file mode 100644
index 0000000..c88c66a
--- /dev/null
+++ b/software/AGENTS.md
@@ -0,0 +1,8 @@
+# Makerspace authentication agents
+
+This document provides shared context and instructions for all agents.
+
+## Build environment
+
+All builds and tests should be performed within a virtual environment.  Run `make venv` and follow its instructions such as "run `. .venv/bin/activate` to use virtualenv" to enter the virtual environment.  
+