diff --git a/README.md b/README.md
index 3d726ad..d97a1d3 100644
--- a/README.md
+++ b/README.md
@@ -1,15 +1,27 @@
 # st-randomness-helpers
 
-To install dependencies:
+st-randomness-helpers is a extension for [SillyTavern](https://sillytavern.app/).
 
-```bash
-bun install
-```
+# Features
 
-To run:
+## WordLists
 
-```bash
-bun run index.ts
-```
+WordList are plaintext files containing one or more words per line. The name of the file is the name of the WordList.
 
-This project was created using `bun init` in bun v1.2.17. [Bun](https://bun.sh) is a fast all-in-one JavaScript runtime.
+## Macros
+
+Register [macros](https://docs.sillytavern.app/usage/core-concepts/macros/) that are usually replaced with a value at save time.
+
+## Placeholders
+
+Placeholders are strings that are replaced with a value at generation time.
+
+## Services
+
+### RandomWord
+
+Get a random word from a WordList. can be used as a Macro or a Placeholder. Macro format: `{{RandomWord::WordListName}}`. Placeholder format: `%%RandomWord:WordListName%%`.
+
+### Shuffle
+
+Shuffle a list of values. can be used as Placeholder only. Placeholder format: `%%Shuffle::Value1::Value2::Value3;;separator%%`. Example: `%%Shuffle::Value1::Value2::Value3;;, %%` will return `Value3, Value1, Value2`.