diff --git a/docs/skills/astrbot-dev-guide.md b/docs/skills/astrbot-dev-guide.md
new file mode 100644
index 000000000..37bc24f18
--- /dev/null
+++ b/docs/skills/astrbot-dev-guide.md
@@ -0,0 +1,159 @@
+---
+name: astrbot-dev-guide
+description: Guide for AI assistants developing AstrBot - project conventions, code style, and common patterns
+---
+
+# AstrBot Developer Guide
+
+This skill provides guidance for AI assistants working on AstrBot development.
+
+## Project Overview
+
+AstrBot is an open-source, all-in-one Agentic chat assistant supporting multiple IM platforms (QQ, Telegram, Discord, Lark, DingTalk, Slack, etc.) and LLM providers.
+
+- **Main entry**: `astrbot/__main__.py` or CLI `astrbot run`
+- **CLI commands**: `astrbot/cli/commands/`
+- **Core modules**: `astrbot/core/`
+- **Platform adapters**: `astrbot/core/platform/sources/`
+- **Star plugins**: `astrbot/builtin_stars/`
+- **Dashboard**: `dashboard/` (Vue.js)
+
+## Quick Start Commands
+
+```bash
+# Install
+uv tool install -e . --force
+
+# Initialize
+astrbot init
+
+# Run
+astrbot run
+
+# Backend only (no WebUI)
+astrbot run --backend-only
+
+# Frontend
+cd dashboard && bun dev
+
+# Tests
+uv sync --group dev && uv run pytest --cov=astrbot tests/
+```
+
+## Code Style Rules
+
+### Type Hints (Required)
+Use Python 3.12+ syntax:
+- `list[str]` not `List[str]`
+- `int | None` not `Optional[int]`
+- Avoid `Any` when possible
+
+### Path Handling
+Always use `pathlib.Path`:
+```python
+from pathlib import Path
+from astrbot.core.utils.astrbot_path import get_astrbot_data_path
+```
+
+### Formatting
+Run before every commit:
+```bash
+ruff format .
+ruff check .
+```
+
+### Comments
+Write all comments in English.
+
+## Environment Variables
+
+When adding new environment variables:
+
+1. Prefix with `ASTRBOT_` (e.g., `ASTRBOT_ENABLE_FEATURE`)
+2. Add to `.env.example` with description
+3. Update `astrbot/cli/commands/cmd_run.py`:
+   - Add to module docstring under "Environment Variables Used in Project"
+   - Add to `keys_to_print` list for debug output
+
+## Core Paths Utility
+
+```python
+from astrbot.core.utils.astrbot_path import (
+    get_astrbot_root,       # AstrBot root directory
+    get_astrbot_data_path,  # Data directory
+    get_astrbot_config_path, # Config directory
+    get_astrbot_plugin_path, # Plugin directory
+    get_astrbot_temp_path,   # Temp directory
+    get_astrbot_skills_path, # Skills directory
+)
+```
+
+## Architecture Patterns
+
+### Adding a Platform Adapter
+
+1. Create in `astrbot/core/platform/sources/`
+2. Extend `Platform` base class
+3. Use `@register_platform_adapter` decorator
+4. Implement: `run()`, `convert_message()`, `meta()`
+
+### Adding a CLI Command
+
+1. Create in `astrbot/cli/commands/`
+2. Use `@click.command()`
+3. Update `astrbot/cli/__main__.py` to add command
+
+### Adding a Star Handler
+
+1. Create in `astrbot/builtin_stars/` or as plugin
+2. Extend `Star` class
+3. Use decorators: `@star.on_command()`, `@star.on_schedule()`, etc.
+
+## Testing
+
+- Test location: `tests/` directory
+- Framework: `pytest` with `pytest-asyncio`
+- Run: `uv run pytest --cov=astrbot tests/`
+
+## Git Conventions
+
+### Commit Messages (Conventional Commits)
+```
+feat: add new feature
+fix: resolve bug
+docs: update documentation
+refactor: restructure code
+test: add tests
+chore: maintenance
+```
+
+### PR Guidelines
+- Title: conventional commit format in English
+- Target branch: `dev`
+- Keep changes atomic and focused
+
+## Important Guidelines
+
+1. **No report files** - Do not add `xxx_SUMMARY.md`
+2. **Componentization** - Keep WebUI code clean, avoid duplication
+3. **Backward compatibility** - Add deprecation warnings when changing APIs
+4. **CLI help** - Run `astrbot help --all` to see all commands
+
+## Directory Structure
+
+```
+astrbot/
+├── __main__.py          # Main entry point
+├── __init__.py          # Package init, exports
+├── cli/                 # CLI commands
+│   └── commands/        # Individual commands
+├── core/                # Core functionality
+│   ├── agent/           # Agent execution
+│   ├── platform/        # Platform adapters
+│   ├── pipeline/        # Message processing
+│   ├── star/            # Plugin system
+│   └── config/          # Configuration
+├── builtin_stars/       # Built-in plugins
+├── dashboard/           # Vue.js frontend
+└── utils/              # Utilities
+```