diff --git a/README.md b/README.md
index ad47064..2b392fe 100644
--- a/README.md
+++ b/README.md
@@ -1,23 +1,141 @@
-# Skip
+# Skip VSCode Extension
 
-Skip language support.
+A comprehensive Visual Studio Code extension providing language support for the Skip programming language.
+
+## Overview
+
+This extension brings Skip language support to VS Code, including syntax highlighting, code formatting, symbol navigation, and intelligent go-to-definition functionality. Skip is a modern programming language developed by SkipLabs.
 
 ## Features
 
-- Basic language support for Skip.
+### 🎨 Syntax Highlighting
+- Syntax highlighting for `.sk` files
+- Support for Skip language constructs including modules, classes, functions, traits, and types
+- Proper highlighting of comments, strings, and operators
+
+### 🔧 Code Formatting
+- Automatic code formatting using the `skfmt` tool
+- Format on save support
+- Consistent code style across your Skip projects
+
+### 🔍 Symbol Navigation
+- Outline view showing all symbols in your Skip files
+- Navigate between classes, functions, modules, and other declarations
+- Hierarchical symbol organization (modules containing classes/functions)
+
+### 🎯 Go to Definition
+- Jump to symbol definitions across your entire project
+- Cross-file navigation support
+- Intelligent search that excludes build artifacts and test files when appropriate
+
+### 📝 Language Features
+- Comment toggling with `//` and `/* */` block comments
+- Auto-closing brackets, quotes, and parentheses
+- Proper indentation and bracket matching
+
+## Installation
+
+### From VS Code Marketplace
+1. Open VS Code
+2. Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
+3. Search for "SkipLang"
+4. Click Install
+
+### From VSIX
+1. Download the latest `.vsix` file from the releases
+2. Run `code --install-extension skip-x.x.x.vsix`
 
 ## Requirements
 
-Latest version of `skfmt`.
+### Essential
+- **skfmt**: The Skip formatter tool must be installed and available in your PATH
+  - Install from: [Skip Tools](https://github.com/skiplabs/skip)
+  - Verify installation: `skfmt --version`
+
+### Recommended
+- VS Code 1.89.0 or higher
+- Skip language tools and compiler
+
+## Getting Started
+
+1. Install the extension and ensure `skfmt` is in your PATH
+2. Open a `.sk` file or create a new one
+3. The extension will automatically activate and provide language support
+4. Use Ctrl+Shift+P / Cmd+Shift+P to access formatting commands
+
+## Development
+
+### Prerequisites
+- Node.js 18.x or higher
+- npm or yarn
+
+### Setup
+```bash
+# Clone the repository
+git clone https://github.com/SkipLabs/vscode-skip.git
+cd vscode-skip
+
+# Install dependencies
+npm install
+
+# Compile TypeScript
+npm run compile
+
+# Run tests
+npm run test
+```
+
+### Available Scripts
+- `npm run compile` - Compile TypeScript to JavaScript
+- `npm run watch` - Watch mode for development
+- `npm run lint` - Run ESLint
+- `npm run fmt` - Format code with Prettier
+- `npm run test` - Run all tests
+- `npm run vscode:prepublish` - Prepare for publishing
+
+### Contributing
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Run tests and linting (`npm run test && npm run lint`)
+5. Commit your changes (`git commit -m 'Add amazing feature'`)
+6. Push to the branch (`git push origin feature/amazing-feature`)
+7. Open a Pull Request
+
+## Troubleshooting
+
+### Common Issues
+
+**Extension not activating**
+- Ensure you're working with `.sk` files
+- Check that VS Code version is 1.89.0 or higher
+
+**Formatting not working**
+- Verify `skfmt` is installed: `skfmt --version`
+- Check that `skfmt` is in your system PATH
+- Look for error messages in the VS Code output panel
+
+**Go to definition not working**
+- Ensure your project contains `.sk` files
+- Check that files are not in excluded directories (`target/`, `tests/`)
+- Try reloading the window (Ctrl+Shift+P → "Developer: Reload Window")
+
+**Symbol outline not showing**
+- Verify the file contains valid Skip syntax
+- Check for syntax errors that might prevent parsing
+
+### Getting Help
+- Report issues on [GitHub Issues](https://github.com/SkipLabs/vscode-skip/issues)
+- Check the [Skip Language Documentation](https://github.com/skiplabs/skip)
 
-## Extension Settings
+## License
 
-None.
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
 
-## Known Issues
+## Changelog
 
-None.
+See [CHANGELOG.md](CHANGELOG.md) for a detailed history of changes.
 
-## Release Notes
+---
 
-Unreleased.
+**Enjoy coding in Skip!** 🚀