diff --git a/docs/commands/def.md b/docs/commands/def.md
new file mode 100644
index 0000000000..8570272d80
--- /dev/null
+++ b/docs/commands/def.md
@@ -0,0 +1,17 @@
+# def
+
+Use `def` to create a custom command.
+
+## Examples
+
+```
+> def my_command [] { echo hi nu }
+> my_command
+hi nu
+```
+
+```
+> def my_command [adjective: string, num: int] { echo $adjective $num meet nu }
+> my_command nice 2
+nice 2 meet nu
+```