diff --git a/packages/claviature/README.md b/packages/claviature/README.md
new file mode 100644
index 00000000..eb540b2e
--- /dev/null
+++ b/packages/claviature/README.md
@@ -0,0 +1,29 @@
+# @strudel/claviature
+
+adds a `Patter.claviature` method that renders a [claviature](https://www.npmjs.com/package/claviature).
+
+example usage:
+
+```js
+chord("<Em9 A7 D^7@2>").voicing().piano()
+  .claviature()
+```
+
+All [claviature options](https://www.npmjs.com/package/claviature#options) will work.
+
+Here is an example that uses all available options:
+
+```js
+chord("<Em9 A7 D^7@2>").voicing().piano()
+.claviature({
+  range: ['C1', 'C6'], // rendered note range
+  color: 'yellow', // highlighting color
+  palette: ['cyan', 'magenta'],
+  stroke: 'black',
+  scaleX: 1, scaleY: 1,
+  upperHeight: 80, 
+  lowerHeight: 50
+})
+```
+
+Note: The `Pattern.claviature` method uses the `colorization` option internally, so don't override that and use the `color` option for changing the highlighting color.