diff --git a/.github/workflows/linters.yml b/.github/workflows/linters.yml
index 1bdd674..215241a 100644
--- a/.github/workflows/linters.yml
+++ b/.github/workflows/linters.yml
@@ -33,4 +33,4 @@ jobs:
 
       - name: Run PR Lint
         # https://github.com/ivuorinen/actions
-        uses: ivuorinen/actions/pr-lint@625c37446b1c7e219755a40807f825c9283f6e05 # 25.7.7
\ No newline at end of file
+        uses: ivuorinen/actions/pr-lint@625c37446b1c7e219755a40807f825c9283f6e05 # 25.7.7
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..f92609c
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,34 @@
+# Project guidelines
+
+This repository contains configuration files and helper scripts for managing a development environment. Dotbot drives the installation and host specific folders under `hosts/` include extra configs.
+
+## Keeping the repository up to date
+
+1. Update submodules with `git submodule update --remote --merge`.
+2. Pull the latest changes and run `./install`.
+3. Run `yarn install` whenever `package.json` changes.
+
+## Linting and tests
+
+- Format files with:
+
+  ```bash
+  yarn fix:prettier
+  yarn fix:markdown
+  ```
+
+- Shell scripts must pass `shellcheck`. Run:
+
+  ```bash
+  find . -path ./node_modules -prune -o -name '*.sh' -print0 | xargs -0 shellcheck
+  ```
+
+- Execute tests with `yarn test`.
+
+## Debugging lint issues
+
+- `yarn lint:prettier` and `yarn lint:markdown` show formatting errors.
+- Ensure shell scripts have a shebang or `# shellcheck shell=bash` directive.
+- Consult `.shellcheckrc` for project specific checks.
+
+Scripts rely on helpers in `config/shared.sh` so they run under Bash, Zsh and Fish by default.
diff --git a/config/direnv/lib/use_asdf.sh b/config/direnv/lib/use_asdf.sh
index 5efed70..dfba325 100644
--- a/config/direnv/lib/use_asdf.sh
+++ b/config/direnv/lib/use_asdf.sh
@@ -1,4 +1,5 @@
 ### Do not edit. This was autogenerated by 'asdf direnv setup' ###
+# shellcheck shell=bash
 use_asdf() {
   source_env "$(asdf direnv envrc "$@")"
 }
diff --git a/config/op/plugins.sh b/config/op/plugins.sh
index e78acdd..013afc9 100644
--- a/config/op/plugins.sh
+++ b/config/op/plugins.sh
@@ -1,2 +1,3 @@
+# shellcheck shell=bash
 export OP_PLUGIN_ALIASES_SOURCED=1
 alias gh="op plugin run -- gh"
diff --git a/config/shared.sh b/config/shared.sh
index 8248375..ecffc60 100755
--- a/config/shared.sh
+++ b/config/shared.sh
@@ -26,7 +26,7 @@ x-path-prepend()
   local dir=$1
   case "$CURRENT_SHELL" in
     fish)
-      set -U fish_user_paths "$dir" $fish_user_paths
+      set -U fish_user_paths "$dir" "$fish_user_paths"
       ;;
     sh | bash | zsh)
       PATH="$dir:$PATH"
@@ -106,7 +106,7 @@ if ! declare -f msg_done > /dev/null; then
   # $1 - message (string)
   msg_done()
   {
-    msgr done "$1"
+    msgr "done" "$1"
     return 0
   }
 fi
diff --git a/scripts/install-cargo-packages.sh b/scripts/install-cargo-packages.sh
index 6cf6b6d..0d3caf8 100755
--- a/scripts/install-cargo-packages.sh
+++ b/scripts/install-cargo-packages.sh
@@ -38,7 +38,7 @@ install_packages()
     if [[ ${pkg:0:1} == "#" ]]; then continue; fi
 
     msgr run "Installing cargo package $pkg"
-    cargo install --jobs $BUILD_JOBS "$pkg"
+    cargo install --jobs "$BUILD_JOBS" "$pkg"
     msgr run_done "Done installing $pkg"
     echo ""
   done
@@ -56,13 +56,13 @@ post_install_steps()
 
   msgr run "Removing cargo cache"
   cargo cache --autoclean
-  msgr done "Done removing cargo cache"
+  msgr "done" "Done removing cargo cache"
 }
 
 main()
 {
   install_packages
-  msgr done "Installed cargo packages!"
+  msgr "done" "Installed cargo packages!"
   post_install_steps
 }
 
diff --git a/scripts/install-ntfy.sh b/scripts/install-ntfy.sh
index e65ce49..672697f 100755
--- a/scripts/install-ntfy.sh
+++ b/scripts/install-ntfy.sh
@@ -9,7 +9,7 @@ VERBOSE="${VERBOSE:-0}"
 
 # Check if ntfy is already installed
 if x-have "ntfy"; then
-  msgr done "ntfy already installed"
+  msgr "done" "ntfy already installed"
   exit 0
 fi
 
@@ -50,7 +50,7 @@ install_ntfy()
 main()
 {
   install_ntfy
-  msgr done "ntfy installation complete"
+  msgr "done" "ntfy installation complete"
 }
 
 main "$@"