diff --git a/README.md b/README.md
index 52ba37e..8e4a9f0 100644
--- a/README.md
+++ b/README.md
@@ -35,6 +35,7 @@ man ./minimap2.1
     - [Full genome/assembly alignment](#full-genome)
   - [Advanced features](#advanced)
     - [The cs optional tag](#cs)
+    - [Evaluation scripts](#eval)
   - [Algorithm overview](#algo)
   - [Getting help](#help)
   - [Citing minimap2](#cite)
@@ -201,6 +202,27 @@ the alignment. The above example will become
 `=CGATCG-ata=AATAGAGTAG+gtc=GAAT*at=GCA`. The long form of `cs` encodes both
 reference and query sequences in one string.
 
+#### <a name="eval"></a>Evaluation scripts
+
+Minimap2 comes with several (java)scripts for evaluating the accuracy of
+minimap2. These scripts require the [k8][k8] javascript shell to run.
+Recent minimap2 binary release tar-balls contain a copy of k8 executable, a
+single file. Here are a few examples on how to use these scripts:
+
+```sh
+# Generate reads from PBSIM alignment (truth encoded in read names)
+k8 misc/sim-pbsim.js ref.fa.fai pbsim-aln.maf > pbsim-reads.fq
+# Generate reads from mason2 alignment (not tested for simulated SVs)
+k8 misc/sim-mason2.js mason2-aln.sam > mason2-reads.fq
+# Evaluate mapping accuracy with ROC-like curve
+k8 misc/sim-eval.js my-aln.sam.gz > result.txt
+k8 misc/sim-eval.js my-aln.paf.gz > result.txt
+# Collect alignment statistics
+k8 misc/mapstat.js my-aln.sam > result.txt
+# Compare spliced junctions to existing gene annotations
+k8 misc/intron-eval.js anno.gtf my-spliced-aln.sam > result.txt
+```
+
 ### <a name="algo"></a>Algorithm overview
 
 In the following, minimap2 command line options have a dash ahead and are
@@ -300,3 +322,4 @@ warmly welcomed.
 [mappypypi]: https://pypi.python.org/pypi/mappy
 [mappyconda]: https://anaconda.org/bioconda/mappy
 [issue]: https://github.com/lh3/minimap2/issues
+[k8]: https://github.com/attractivechaos/k8