diff --git a/.config/fish/functions/mksh.fish b/.config/fish/functions/mksh.fish
index 522e1dad..2054dc28 100644
--- a/.config/fish/functions/mksh.fish
+++ b/.config/fish/functions/mksh.fish
@@ -1,13 +1,30 @@
 function mksh --description 'make executable shell script'
-    argparse 'e/edit' -- $argv
+    # edit flag opens in kakoune
+    argparse 'e/edit' 'h/help' -- $argv
+    if set -q _flag_h
+        echo Make and edit a shell script.
+        echo "Usage: mksh [-e/--edit] <name>"
+        echo "<name> should be the name of the script without an extension."
+        echo "Flags: -e/--edit -h/--help"
+        echo "The EDIT flag does the following:"
+        echo "Opens Kakoune with shebang populated and cursor in correct"
+        echo "position in insert mode. When the file is saved for the first time,"
+        echo "it's made executable with chmod +x"
+        return 0
+    end
+    # name of file (no extension)
     set name $argv[1]
     set file $name.sh
+    # check for edit mode
     if set -q _flag_e
-        set cmd (printf 'rename-buffer -file %s \\n set buffer filetype sh \\n hook -once -always buffer BufWritePost %s %s \\n hook -once -always buffer NormalIdle .* %s' "$file" "$(string replace -a . \\. -- $(path resolve $file))" "%{ nop %sh{ notify-send hey } }" "%{ exec -with-hooks gji }")
-        # set cmd (printf 'rename-buffer -file %s ; set buffer filetype sh ; hook -once -always buffer BufWritePost %s %s ; hook -once -always buffer NormalIdle .* %s' "$file" "$(string replace -a . \\. -- $file)" "%{ nop %sh { chmod +x $(path resolve $file) } }" "%{ exec -with-hooks gji }")
+        # populate a buffer with shebang and set to the right path
+        # but we don't write it to disk yet! we also get the cursor in insert mode
+        # in the right place to start writing the script, and we make the file executable only
+        # when the user actually saves the file!
+        set cmd (printf 'rename-buffer -file %s ; set buffer filetype sh ; hook -once -always buffer BufWritePost %s %s ; hook -once -always buffer NormalIdle .* %s' "$file" "$(string replace -a . \\. -- $(path resolve $file))" "%{ nop %sh{ chmod +x $(path resolve $file) } }" "%{ exec -with-hooks gji }")
         printf '#!/bin/sh\n\n' | kak -e "$cmd"
-        # printf '#!/bin/sh\n\n' | kak -e "echo -debug -- $cmd"
     else
+        # in this case we just write the shebang, make executable, and exit
         printf '#!/bin/sh\n\n' >$file
         chmod +x $file
     end