diff --git a/docs/src/tasks.md b/docs/src/tasks.md
index 54705d3fd393d2b640e34e29275cade2c68c4451..98cbd6dfc18eaa50aa3b70c66dec2a3fc8020c0b 100644
--- a/docs/src/tasks.md
+++ b/docs/src/tasks.md
@@ -93,6 +93,38 @@ You can also use verbose syntax that allows specifying a default if a given vari
 
 These environmental variables can also be used in tasks `cwd`, `args` and `label` fields.
 
+### Variable Quoting
+
+When working with paths containing spaces or other special characters, please ensure variables are properly escaped.
+
+For example, instead of this (which will fail if the path has a space):
+
+```json
+{
+  "label": "stat current file",
+  "command": "stat $ZED_FILE"
+}
+```
+
+Provide the
+
+```json
+{
+  "label": "stat current file",
+  "command": "stat",
+  "args": ["$ZED_FILE"]
+}
+```
+
+Or explicitly include escaped quotes like so:
+
+```json
+{
+  "label": "stat current file",
+  "command": "stat \"$ZED_FILE\""
+}
+```
+
 ## Oneshot tasks
 
 The same task modal opened via `task: spawn` supports arbitrary bash-like command execution: type a command inside the modal text field, and use `opt-enter` to spawn it.