1 files changed, 17 insertions, 0 deletions
diff --git a/doc/builders/special/mkshell.section.md b/doc/builders/special/mkshell.section.md
new file mode 100644
index 00000000000..8a62c50e17d
--- /dev/null
+++ b/doc/builders/special/mkshell.section.md
@@ -0,0 +1,17 @@
+# pkgs.mkShell {#sec-pkgs-mkShell}
+
+`pkgs.mkShell` is a special kind of derivation that is only useful when using
+it combined with `nix-shell`. It will in fact fail to instantiate when invoked
+with `nix-build`.
+
+## Usage {#sec-pkgs-mkShell-usage}
+
+```nix
+{ pkgs ? import <nixpkgs> {} }:
+pkgs.mkShell {
+  # specify which packages to add to the shell environment
+  packages = [ pkgs.gnumake ];
+  # add all the dependencies, of the given packages, to the shell environment
+  inputsFrom = with pkgs; [ hello gnutar ];
+}
+```