diff --git a/README.md b/README.md
index 45d49fa..3f1a5b3 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,372 @@
-# DecentSamplerSkill
-Comprehensive agent skill for making, editing, and fixing DecentSampler libraries
+# DecentSampler Skills
+
+AI-assisted creation, editing, and validation of `.dspreset` files for [DecentSampler](https://www.decentsampler.com/), a free, open-source sample instrument player by Dave Hilowitz.
+
+## What's Inside
+
+- **SKILL.md** — Complete format reference covering XML structure, UI controls, effects, oscillators (wavetable, FM6, pluck, harmonic), modulators, buses, note sequences, keyswitches, MPE, bindings, and validation rules.
+
+## Quick Start
+
+### 1. Create a Minimal Preset
+
+Save this as `My Instrument.dspreset`:
+
+```xml
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+### 2. Add Your Samples
+
+Create a `Samples/` folder next to your `.dspreset` file and place your audio files there.
+
+### 3. Open in DecentSampler
+
+Load the `.dspreset` file in DecentSampler (free VST/AU plugin or standalone app).
+
+---
+
+## File Structure
+
+A DecentSampler instrument folder:
+
+```
+MyInstrument/
+├── MyInstrument.dspreset ← Preset definition (XML)
+├── Samples/ ← Audio files (.wav, .aif)
+│ ├── C3.wav
+│ ├── C4.wav
+│ └── ...
+├── Images/ ← UI images (optional)
+│ ├── Background.jpg
+│ └── Knob.png
+└── Wavetables/ ← Wavetable files (optional)
+ └── MyWavetable.wav
+```
+
+All paths in the .dspreset file are relative to its location.
+
+---
+
+## Format Reference
+
+DecentSampler presets are XML files with this hierarchy:
+
+```
+
+ ├── Tag definitions (polyphony, volume)
+ ├── User interface (812×375 recommended)
+ │ └── Single tab with controls
+ │ ├── Rotary dials
+ │ ├──