diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..ab46c68
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,35 @@
+- Every script is self contained.
+
+- Do not be chatty, do not summarize the code afterwards.
+- Use `#!/usr/bin/env -S uv run --script` as the shebang line.
+- Add dependencies under the shebang line as
+
+```
+# /// script
+# dependencies = [list of external dependencies as json array]
+# ///
+```
+
+and keep them updated as the code changes.
+
+- Keep comments to minimum
+- Use `uv` for package management.
+- Use logging instead of print statements. Use `logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s: %(message)s")` for configuration.
+- Use argparse for command-line arguments, keep argument parsing in a func called `parse_args() -> argparse.Namespace`, which gets called from `main`. Use `argparse.ArgumentDefaultsHelpFormatter` for the formatter class.
+- Use `pathlib.Path` for file operations. When the CLI args include a path, set its `type=Path`
+- Place imports at the top of the file.
+- Use httpx for HTTP requests. Do not use async.
+- Always add type annotations to function signatures, prefer built-in types, e.g. `list[str]` over `typing` module types when possible.
+- Prefer kwargs calling style for function calls, e.g. `func(arg1=value1, arg2=value2)` instead of `func(value1, value2)`.
+- Use `Path.cwd()` for the current working directory.
+- Prefer `os.getenv` over `os.environ.get` for environment variables.
+- Use `subprocess.run` for running shell commands, prefer `check=True` to raise an error on failure.
+- Use `tempfile.TemporaryDirectory()` for temporary directories.
+- Do not shorten parameter names unnecessarily, unless it's an idiomatic abbreviation.
+- Use f-strings for string formatting.
+- When calling an external command, use the long form of the arguments, e.g. `--output` instead of `-o`.
+
+## Testing
+
+- Use pytest for tests and name test files `<script_name>_test.py`.
+- Make test scripts self contained like `docker_refresh_test.py`: use the same uv shebang, declare pytest and all required external dependencies in inline script metadata, and run `pytest.main(args=[str(Path(__file__).resolve()), *sys.argv[1:]])` via `sys.exit` under the `__main__` guard so pytest CLI arguments are forwarded.