diff --git a/packages/unixfs/README.md b/packages/unixfs/README.md
index 22527bdb..ac26f11f 100644
--- a/packages/unixfs/README.md
+++ b/packages/unixfs/README.md
@@ -13,6 +13,49 @@
 
 > A Helia-compatible wrapper for UnixFS
 
+# About
+
+`@helia/unixfs` is an implementation of a filesystem compatible with Helia.
+
+See the interface for all available operations.
+
+## Example
+
+```typescript
+import { createHelia } from 'helia'
+import { unixfs } from '@helia/unixfs'
+
+const helia = createHelia({
+  // ... helia config
+})
+const fs = unixfs(helia)
+
+// create an empty dir and a file, then add the file to the dir
+const emptyDirCid = await fs.addDirectory()
+const fileCid = await fs.addBytes(Uint8Array.from([0, 1, 2, 3]))
+const updateDirCid = await fs.cp(fileCid, emptyDirCid, 'foo.txt')
+
+// or doing the same thing as a stream
+for await (const entry of fs.addAll([{
+  path: 'foo.txt',
+  content: Uint8Array.from([0, 1, 2, 3])
+}])) {
+  console.info(entry)
+}
+```
+
+## Example
+
+Recursively adding a directory (Node.js-compatibly environments only):
+
+```typescript
+import { globSource } from '@helia/unixfs'
+
+for await (const entry of fs.addAll(globSource('path/to/containing/dir', 'glob-pattern'))) {
+  console.info(entry)
+}
+```
+
 ## Table of contents <!-- omit in toc -->
 
 - [Install](#install)