diff --git a/.changeset/custom-commands-spec-clarity.md b/.changeset/custom-commands-spec-clarity.md
new file mode 100644
index 0000000..1073573
--- /dev/null
+++ b/.changeset/custom-commands-spec-clarity.md
@@ -0,0 +1,5 @@
+---
+"git-work-grove": patch
+---
+
+Improve custom commands spec: fix variable descriptions, clarify absolute paths, document env validation, add env usage example.
diff --git a/docs/spec/custom-commands.md b/docs/spec/custom-commands.md
index 75a33d4..af85608 100644
--- a/docs/spec/custom-commands.md
+++ b/docs/spec/custom-commands.md
@@ -29,11 +29,11 @@ Same variables as repository/worktree templates:
 
 | Variable | Value |
 |---|---|
-| `{name}` | Worktree folder name |
-| `{branch}` | Git branch (empty if detached HEAD) |
-| `{ref}` | Branch or short commit hash (always non-empty) |
+| `{name}` | Branch name, or `HEAD` if detached |
+| `{branch}` | Full branch name (empty if detached HEAD) |
+| `{ref}` | Branch name or short commit hash (always non-empty) |
 | `{head}` | Short commit hash (8 chars) |
-| `{path}` | Filesystem path |
+| `{path}` | Absolute worktree directory path |
 
 ### Workspace items (`customCommands.workspace`)
 
@@ -41,12 +41,12 @@ Same variables as worktree workspace templates, plus `{dir}`:
 
 | Variable | Value |
 |---|---|
-| `{name}` | File name (without `.code-workspace`) |
+| `{name}` | File name (without `.code-workspace` extension) |
 | `{branch}` | Parent worktree branch (empty if detached HEAD) |
-| `{ref}` | Branch or short commit hash (always non-empty) |
+| `{ref}` | Branch name or short commit hash (always non-empty) |
 | `{head}` | Short commit hash (8 chars) |
-| `{path}` | Workspace file path |
-| `{dir}` | Parent directory of workspace file path |
+| `{path}` | Absolute workspace file path |
+| `{dir}` | Absolute parent directory of workspace file |
 | `{worktree}` | Parent worktree folder name |
 
 Template syntax (fallback, conditional) is the same as display templates. See [templates.md](../../docs/templates.md) for syntax reference.
@@ -107,7 +107,7 @@ Same logic as Open in Terminal (see [open-in-terminal.md](open-in-terminal.md)):
 
 - **Spawn failure** (synchronous): try/catch around `spawn()` — shows error via `showErrorMessage`
 - **Process error** (asynchronous): `child.on("error")` — shows error with "Show Logs" action
-- **Settings validation**: Invalid entries (missing `label`, empty `command`) are skipped with a log message
+- **Settings validation**: Invalid entries are skipped with a log message. Checks: `label` must be a non-empty string, `command` must be a non-empty string array, and `env` values (if present) must all be strings
 - **Template rendering**: Uses the same `renderTemplate` function as display templates — unknown variables remain as-is
 
 ## Examples
@@ -175,6 +175,20 @@ Common terminal emulators:
 }
 ```
 
+### Using environment variables
+
+```json
+{
+  "git-work-grove.customCommands.directory": [
+    {
+      "command": ["open", "-a", "Ghostty", "--args", "--working-directory={path}"],
+      "env": { "GHOSTTY_TITLE": "{ref}" },
+      "label": "Open in Ghostty"
+    }
+  ]
+}
+```
+
 ### Multiple commands
 
 ```json