diff --git a/README.md b/README.md
new file mode 100644
index 0000000..edeafe3
--- /dev/null
+++ b/README.md
@@ -0,0 +1,169 @@
+# Tasmota Skill for OpenClaw
+
+Automated discovery and control of Tasmota smart home devices on local networks.
+
+## Features
+
+- **Network Discovery** - Scan your network to find all Tasmota devices
+- **Device Control** - Power on/off, brightness adjustment, RGB color control
+- **Status Monitoring** - Check power states, firmware versions, hardware info
+- **Inventory Management** - Track devices in CSV format for batch operations
+
+## Quick Start
+
+```bash
+# Scan network for Tasmota devices
+python3 scripts/tasmota-discovery.py
+
+# Check device status
+python3 scripts/tasmota-control.py <IP_ADDRESS> status 0
+
+# Control device
+python3 scripts/tasmota-control.py <IP_ADDRESS> power on
+python3 scripts/tasmota-control.py <IP_ADDRESS> brightness 75
+python3 scripts/tasmota-control.py <IP_ADDRESS> color FF0000
+```
+
+## Requirements
+
+- Python 3.x
+- Tasmota devices on same network with HTTP server enabled
+- Network access to device ports (80)
+
+## Device Support
+
+Works with ESP8266 and ESP32 devices running Tasmota firmware across versions 9.4+.
+
+**Device types:**
+- Smart bulbs and lights
+- Smart sockets and switches
+- Dimmers
+- RGB controllers
+- Other Tasmota-compatible hardware
+
+## Installation
+
+Install this skill via OpenClaw's skill management, or clone this repository to your workspace.
+
+```bash
+git clone http://git.theta42.com/nova/tasmota-skill.git
+```
+
+## Usage Examples
+
+### Network Scan
+
+```bash
+python3 scripts/tasmota-discovery.py
+```
+
+Output:
+```
+🔍 Scanning network for Tasmota devices...
+✅ Found 26 Tasmota device(s):
+
+🔌 Device 1:
+   IP: 192.168.1.116:80
+   Title: Office Hall Light
+   Version: 13.1.0
+   Hardware: ESP8266EX
+```
+
+### Device Control
+
+```bash
+# Power
+python3 scripts/tasmota-control.py 192.168.1.116 power on
+python3 scripts/tasmota-control.py 192.168.1.116 power off
+python3 scripts/tasmota-control.py 192.168.1.116 power toggle
+
+# Brightness (0-100)
+python3 scripts/tasmota-control.py 192.168.1.127 brightness 50
+
+# Color (hex RGB)
+python3 scripts/tasmota-control.py 192.168.1.127 color FF0000  # Red
+python3 scripts/tasmota-control.py 192.168.1.127 color 00FF00  # Green
+```
+
+### Status Queries
+
+```bash
+# Basic device status
+python3 scripts/tasmota-control.py 192.168.1.116 status 0
+
+# All statuses
+python3 scripts/tasmota-control.py 192.168.1.116 status all
+```
+
+**Status codes:**
+- `0` - Device info (power state, dimmer, etc.)
+- `1` - Parameters (uptime, MAC)
+- `2` - Firmware version
+- `4` - Network configuration
+- `5` - MQTT settings
+- `9` - Time and timezone
+
+### Bulk Operations
+
+```bash
+# Check all devices
+python3 scripts/tasmota-status.py
+```
+
+## Scripts
+
+- `tasmota-discovery.py` - Network scanner
+- `tasmota-control.py` - Device controller
+- `tasmota-status.py` - Bulk status checker
+
+## Troubleshooting
+
+### Device Not Found
+
+- Verify device is on same subnet
+- Check HTTP server is enabled (Webserver 2 in Tasmota config)
+- Ensure device is powered on and connected to WiFi
+
+### Timeout Errors
+
+- Device may be in power save mode
+- Network latency or packet loss
+- Try: `curl http://<IP>/cm?cmnd=Status%200`
+
+### Unknown Power State
+
+Some devices (BLE gateways, sensors) don't have power control capability. Check the device's StatusSTS for supported features.
+
+## API Reference
+
+### Command Format
+
+```
+http://<IP>/cm?cmnd=<COMMAND>
+```
+
+### Common Commands
+
+| Command | Description |
+|---------|-------------|
+| `Power` | Toggle power |
+| `Power ON` | Turn on |
+| `Power OFF` | Turn off |
+| `Status 0` | Device status |
+| `Status 4` | Network status |
+| `Dimmer <0-100>` | Set brightness |
+| `Color <hex>` | Set RGB color |
+
+## Contributing
+
+Contributions welcome! Please submit issues or pull requests to the repository.
+
+## License
+
+See license.txt in this repository.
+
+## Links
+
+- Repository: http://git.theta42.com/nova/tasmota-skill
+- Tasmota Firmware: https://tasmota.github.io
+- OpenClaw Skills: https://clawhub.com
\ No newline at end of file