1 files changed, 15 insertions, 0 deletions
diff --git a/doc/builders/special/mkshell.section.md b/doc/builders/special/mkshell.section.md
new file mode 100644
index 000000000000..1feb75cbd6f7
--- /dev/null
+++ b/doc/builders/special/mkshell.section.md
@@ -0,0 +1,15 @@
+# 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 {
+  # this will make all the build inputs from hello and gnutar
+  # available to the shell environment
+  inputsFrom = with pkgs; [ hello gnutar ];
+  buildInputs = [ pkgs.gnumake ];
+}
+```