diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a44151f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,75 @@
+# VDI ACF Block Scaffold Extension
+
+Scaffold WordPress ACF blocks from a reusable template inside Visual Studio Code.
+
+## Features
+
+- Command palette + keybinding to create a new block
+- Prompts for a block name and generates a slug automatically
+- Copies the `block-template` files into a new block folder
+- Replaces placeholders in the template with the provided name/slug
+- Opens the new block files for editing
+
+## Requirements
+
+- VS Code 1.80+
+- Node.js + npm
+
+## Installation (local development)
+
+1. Install dependencies:
+
+   ```bash
+   npm install
+   ```
+
+2. Build the extension:
+
+   ```bash
+   npm run compile
+   ```
+
+3. Open this folder in VS Code and press `F5` to start an Extension Development Host.
+
+## Usage
+
+1. Run the command:
+   - Command Palette: `VDI: Create ACF Block`
+   - Keybinding: `Ctrl+Alt+B` (`Cmd+Alt+B` on macOS)
+2. Enter a block name (e.g. "Testimonial").
+3. The extension creates a new block folder under the parent directory and opens the files.
+
+## Configuration
+
+`vdiAcfBlockScaffold.parentDirectory`
+
+- Workspace-relative path where new blocks are created.
+- Default: `views/blocks`
+
+Example `settings.json`:
+
+```json
+{
+  "vdiAcfBlockScaffold.parentDirectory": "views/blocks"
+}
+```
+
+## Template placeholders
+
+The following placeholders are replaced in template files:
+
+- `{{BLOCK_NAME}}` - Human-readable name (e.g. "Testimonial")
+- `{{BLOCK_SLUG}}` - Slug (e.g. "testimonial")
+
+## Template structure
+
+```plaintext
+block-template/ - Template directory copied into the new block
+├── block.json
+├── block-template.php -> {{BLOCK_SLUG}}.php
+└── block-template.css -> {{BLOCK_SLUG}}.css
+```
+
+## Notes
+
+The extension will not overwrite an existing block folder or files. If a block slug already exists, creation is aborted with an error message.