diff --git a/README.md b/README.md
new file mode 100644
index 0000000..1df02f7
--- /dev/null
+++ b/README.md
@@ -0,0 +1,39 @@
+# @yanick/remeda
+
+This package adds a few functions to the already awesome
+[remeda](https://remedajs.com/) library. For convenience, it 
+re-export everything that remeda has. 
+
+``` 
+import { matches, pipe } from '@yanick/remeda';
+
+// equivalent to 
+
+import { pipe }    from 'remeda';
+import { matches } from '@yanick/remeda';
+
+```
+
+## Additional functions
+
+### `matches`
+
+Compares the input with the matcher and returns `true` if they match.
+The matcher can be a function (which will be fed the input and is expected
+to return a boolean), or a value. If the value is an object, the matching
+will be recursive.
+
+```
+import { matches, pipe } from '@yanick/remeda';
+
+matches( 'potato', 'potato'); // => true
+matches( 'potato', 'turnip'); // => false
+matches( 'potato', vegetable => vegetable === 'potato'); // => true
+matches({ a: 1, b :2 }, { a: 1 } ); // => true
+matches({ 'a': 4, 'b': 5, 'c': 6 }, { 'a': 4, 'c': 6 }) // => true
+
+pipe({a:1,b:2}, R.matches({ a: 1 }) ) // => true
+pipe({a:1,b:2}, R.matches({ b: (val) => val < 5 }) ) // => true
+pipe({a:1,b:2}, R.matches({ c: 3 }) ) // => false
+pipe( { 'a': 4, 'b': 5, 'c': 6 }, R.matches({ 'a': 4, 'c': 6 })) // => true
+```