---
name: moai-domain-adb
title: "ADB Automation Domain Specialist"
version: 1.0.0
tier: 3
category: domain-specialist
color: yellow
status: active
created: 2025-12-01
maintainer: MoAI-ADK Community
description: |
  Comprehensive ADB (Android Debug Bridge) automation skill for game bot development,
  device management, computer vision integration, and Tauri-Python orchestration.
  Provides modular expertise for building intelligent Android automation workflows.
requires_skills:
  - moai-lang-unified
  - moai-foundation-core
scripts_manifest:
  - adb_device_analyzer.py
  - adb_bot_generator.py
  - adb_template_creator.py
  - adb_performance_profiler.py
  - adb_config_validator.py
  - adb_game_tester.py
  - adb_deployment_helper.py
modules:
  - adb-fundamentals
  - device-management
  - game-automation
  - computer-vision
  - tauri-integration
tags:
  - android
  - automation
  - game-bot
  - device-management
  - computer-vision
  - tauri
  - adb-cli
  - testing
---

# moai-domain-adb: ADB Automation Domain Specialist

**Tier 3 Modularized Skill** for intelligent Android automation, game bot development, and real-time device orchestration.

---

## 🎯 Quick Reference

### Core Competencies

| Domain | Capability | Module |
|--------|-----------|--------|
| **Device Control** | ADB connection, shell execution, property inspection | adb-fundamentals |
| **Device Management** | Multi-device orchestration, state tracking, lifecycle | device-management |
| **Game Automation** | Bot scripting, action sequences, timing control | game-automation |
| **Vision & Detection** | Template matching, OCR, region-based detection | computer-vision |
| **Tauri Integration** | UI-Python bridge, real-time communication, deployment | tauri-integration |

### Key Functions (Quick Access)

**Device Operations**
```python
# Check device status
adb devices --list-long

# Execute shell command
adb shell input tap 540 960

# Get device property
adb shell getprop ro.build.version.sdk

# Install APK
adb install -r game.apk
```

**Bot Control**
```python
# Start bot
adb shell am start -n com.game/.MainActivity

# Send input sequence
adb shell input tap x y && sleep 1 && adb shell input tap x2 y2

# Capture screenshot
adb shell screencap -p /sdcard/screen.png
```

**Module Selection Guide**

Use when you need to...

- **Understand ADB fundamentals**: Load `adb-fundamentals` module
  - Connection protocols, authentication, basic shell operations
  - Device discovery, property reading, system interaction

- **Manage multiple devices**: Load `device-management` module
  - Device state tracking, connection pooling, failover strategies
  - Batch operations, monitoring, lifecycle management

- **Develop game bots**: Load `game-automation` module
  - Click sequences, timing, OCR parsing, state detection
  - Custom routines, action templates, bot patterns

- **Use vision for detection**: Load `computer-vision` module
  - Template matching (OpenCV), OCR (Tesseract)
  - Region-based detection, image analysis, pattern recognition

- **Integrate with Tauri UI**: Load `tauri-integration` module
  - Real-time bot status updates, command queueing
  - UI ↔ Python communication, resource management

---

## 📚 Implementation Guide

### Architecture Overview

**moai-domain-adb** follows a 5-module progressive disclosure pattern:

```
moai-domain-adb/
├── SKILL.md                    # This file (documentation hub)
├── modules/
│   ├── adb-fundamentals.md     # Level 1: Core ADB operations
│   ├── device-management.md    # Level 2: Multi-device orchestration
│   ├── game-automation.md      # Level 3: Bot development patterns
│   ├── computer-vision.md      # Level 4: Vision-based detection
│   └── tauri-integration.md    # Level 5: UI orchestration
└── scripts/                    # IndieDevDan UV scripts
    ├── adb_device_analyzer.py  # Analyze device capabilities
    ├── adb_bot_generator.py    # Generate bot skeletons
    ├── adb_template_creator.py # Create action templates
    ├── adb_performance_profiler.py  # Profile bot performance
    ├── adb_config_validator.py # Validate configurations
    ├── adb_game_tester.py      # Test bot on devices
    └── adb_deployment_helper.py # Deploy to production
```

### Tier 3 Characteristics

✅ **Modularized**: 5 independent modules (no cross-module imports)
✅ **Production-Ready**: 500+ line SKILL.md with comprehensive docs
✅ **Scripted**: 7 UV scripts following IndieDevDan 13 rules
✅ **Delegatable**: Works with expert-* and manager-* agents
✅ **Reusable**: Applicable to any Android automation project

### Usage Pattern

```python
# Pattern 1: Load skill for general ADB knowledge
Skill("moai-domain-adb")

# Pattern 2: Load specific module for targeted expertise
# In agent prompt: "Use moai-domain-adb:adb-fundamentals for device operations"

# Pattern 3: Reference UV script for automated tasks
# Command: uv run .claude/skills/moai-domain-adb/scripts/adb_device_analyzer.py --device emulator-5554
```

### Integration Points

**With Agents**:
- `adb-bot-runner`: Executes bots using game-automation patterns
- `adb-device-manager`: Manages devices using device-management expertise
- `adb-game-tester`: Tests bots using computer-vision and game-automation
- `adb-config-manager`: Validates configs using config-validator script
- `adb-workflow-orchestrator`: Coordinates all agents using tauri-integration patterns

**With Commands**:
- `/adb:init` → Uses adb-fundamentals + adb_device_analyzer
- `/adb:bot` → Uses game-automation + adb_bot_generator
- `/adb:test` → Uses computer-vision + adb_game_tester
- `/adb:deploy` → Uses tauri-integration + adb_deployment_helper

**With UV Scripts**:
All 7 scripts are self-contained (zero dependencies on each other), follow PEP 723, and implement dual output (human-readable + JSON).

### Progressive Disclosure Strategy

**Level 1: Getting Started**
- Read: adb-fundamentals module
- Run: `adb_device_analyzer.py` to list devices
- Understand: Basic device connection and property reading

**Level 2: Multi-Device Workflows**
- Read: device-management module
- Understand: Connection pooling, state tracking, failover
- Build: Scripts that manage 5+ devices simultaneously

**Level 3: Game Bot Development**
- Read: game-automation module
- Understand: Click sequences, timing control, OCR integration
- Build: Custom routines for game-specific tasks

**Level 4: Vision-Based Automation**
- Read: computer-vision module
- Understand: Template matching, OCR parsing, region detection
- Build: Bots that adapt to UI changes dynamically

**Level 5: Production Orchestration**
- Read: tauri-integration module
- Understand: Real-time UI updates, command queuing, resource management
- Build: Enterprise workflows with Tauri UI control

---

## 🚀 Advanced Topics

### Skill Composition Strategy

**moai-domain-adb** is designed for modular composition:

```python
# Example 1: Simple device check
# Required: adb-fundamentals
agent = Task(
    subagent_type="expert-backend",
    prompt="Use moai-domain-adb:adb-fundamentals to list ADB devices"
)

# Example 2: Multi-device bot deployment
# Required: device-management + game-automation + tauri-integration
agent = Task(
    subagent_type="adb-workflow-orchestrator",
    prompt="Deploy game bot to 3 devices"
)

# Example 3: Vision-based testing
# Required: computer-vision + game-automation
agent = Task(
    subagent_type="adb-game-tester",
    prompt="Test bot with computer vision verification"
)
```

### Performance Optimization

**Device Batching**:
- Group commands by device to reduce round-trip latency
- Use `adb_performance_profiler.py` to identify bottlenecks
- Target: Execute 100 actions in <5 seconds

**Caching Strategies**:
- Cache device properties (refreshed every 60s)
- Cache template images (refreshed on detection failure)
- Cache bot configurations (invalidated on user edit)

**Concurrency**:
- Run multi-device operations with ThreadPoolExecutor
- Limit to 5 concurrent ADB operations per host
- Use queuing for >5 devices

### Security Considerations

**Authentication**:
- ADB uses RSA key exchange; validate device certificates
- Never store unencrypted device pairing keys
- Rotate pairing keys quarterly for production devices

**Permissions**:
- Request minimal shell commands (avoid `su` unless necessary)
- Use app-specific commands instead of root access
- Audit bot actions for unintended side effects

**Data Protection**:
- Never capture sensitive data in screenshots
- Encrypt stored configurations containing API keys
- Use secure storage for game credentials

### Debugging & Troubleshooting

**Common Issues**:

| Issue | Diagnosis | Solution |
|-------|-----------|----------|
| Device not found | `adb_device_analyzer.py --check-connection` | Verify USB connection, check ADB daemon |
| Slow bot execution | `adb_performance_profiler.py --device <id>` | Reduce click delays, batch operations |
| Template matching fails | Check image DPI/resolution | Run `adb_template_creator.py --device <id>` |
| OCR accuracy poor | Preprocess image (contrast, threshold) | See computer-vision module for tips |
| Tauri communication lag | Check Python process CPU | Reduce log verbosity, optimize render loop |

**Debug Mode**:
```bash
# Enable verbose logging
export ADB_DEBUG=1
uv run .claude/skills/moai-domain-adb/scripts/adb_device_analyzer.py --verbose

# Trace ADB commands
adb logcat | grep "adb_bot_runner"
```

### Testing Strategy (TRUST 5 Framework)

**Test Coverage Target**: ≥85%

- **Unit Tests**: Individual module functions (py.test)
- **Integration Tests**: Module interactions (device mock)
- **E2E Tests**: Full workflow with real devices (optional)
- **Performance Tests**: Execution time benchmarks
- **Security Tests**: Input validation, permission checks

**Test Execution**:
```bash
# Run all tests
pytest tests/ -v --cov=.claude/skills/moai-domain-adb

# Run specific module tests
pytest tests/test_device_management.py -v

# Profile performance
pytest tests/ --benchmark-only
```

---

## 📖 Module Navigation

Each module builds upon previous knowledge but is independently usable:

- **[adb-fundamentals](./modules/adb-fundamentals.md)** (250 lines)
  - ADB architecture, connection protocols, device discovery
  - Shell execution, property reading, device interaction

- **[device-management](./modules/device-management.md)** (280 lines)
  - Multi-device orchestration, state tracking, connection pooling
  - Lifecycle management, monitoring, failover strategies

- **[game-automation](./modules/game-automation.md)** (300 lines)
  - Bot scripting patterns, click sequences, timing control
  - OCR integration, state detection, action templates

- **[computer-vision](./modules/computer-vision.md)** (270 lines)
  - Template matching (OpenCV), OCR (Tesseract)
  - Region detection, image preprocessing, pattern recognition

- **[tauri-integration](./modules/tauri-integration.md)** (240 lines)
  - Tauri-Python IPC, real-time updates, command queueing
  - Resource management, deployment strategies, monitoring

---

## 🛠️ Scripts & Tools

All scripts follow **IndieDevDan 13 Rules** (PEP 723, 9-section structure, dual output):

```bash
# Analyze device capabilities
uv run scripts/adb_device_analyzer.py --device emulator-5554 --json

# Generate bot skeleton
uv run scripts/adb_bot_generator.py --game "My Game" --output my_bot.py

# Create action template
uv run scripts/adb_template_creator.py --screenshot screen.png --region "0,0,1080,1920"

# Profile bot performance
uv run scripts/adb_performance_profiler.py --bot bot.py --iterations 100

# Validate configuration
uv run scripts/adb_config_validator.py --config config.yaml --strict

# Test bot on device
uv run scripts/adb_game_tester.py --bot bot.py --device emulator-5554

# Prepare deployment
uv run scripts/adb_deployment_helper.py --bot bot.py --target production
```

### Complete Scripts Reference (36 scripts)

All scripts are located in `scripts/` directory and organized by category. Each script supports:
- **`--device/-d`** - Specify device ID (defaults to first connected)
- **`--toon`** - Output in TOON/YAML format for automation
- **`--verbose/-v`** - Enable verbose logging
- **`--help`** - Show detailed help and usage examples

See **[scripts/README.md](./scripts/README.md)** for comprehensive documentation with 150+ usage examples.

#### 🔌 Connection (4 scripts)

**Location**: `scripts/connection/`

| Script | Purpose | Key Options | Example |
|--------|---------|-------------|---------|
| `adb_connect.py` | Connect to device via IP:port | `--device` (default: 127.0.0.1:5555) | `uv run scripts/connection/adb_connect.py` |
| `adb_disconnect.py` | Disconnect device gracefully | `--device` | `uv run scripts/connection/adb_disconnect.py` |
| `adb_restart_server.py` | Restart ADB server | `--verbose` | `uv run scripts/connection/adb_restart_server.py` |
| `adb_device_status.py` | List all devices and status | `--toon` | `uv run scripts/connection/adb_device_status.py` |

#### 📱 Screen (6 scripts)

**Location**: `scripts/screen/`

| Script | Purpose | Key Options | Example |
|--------|---------|-------------|---------|
| `adb_screenshot.py` | Capture screenshot | `--output FILE` | `uv run scripts/screen/adb_screenshot.py --output capture.png` |
| `adb_tap.py` | Tap at coordinates | `--x X --y Y --count N` | `uv run scripts/screen/adb_tap.py --x 500 --y 1000` |
| `adb_swipe.py` | Swipe gesture | `--preset {up,down,left,right}` or `--start X,Y --end X,Y` | `uv run scripts/screen/adb_swipe.py --preset up` |
| `adb_keyevent.py` | Send key event | `--key {back,home,menu,power,volume_up}` | `uv run scripts/screen/adb_keyevent.py --key back` |
| `adb_text_input.py` | Type text | `--text TEXT` | `uv run scripts/screen/adb_text_input.py --text "Hello"` |
| `adb_screenrecord.py` | Record screen video | `--output FILE --duration SECONDS` | `uv run scripts/screen/adb_screenrecord.py --duration 60` |

#### 📦 App (5 scripts)

**Location**: `scripts/app/`

| Script | Purpose | Key Options | Example |
|--------|---------|-------------|---------|
| `adb_app_list.py` | List installed apps | `--filter TEXT`, `--system`, `--all` | `uv run scripts/app/adb_app_list.py --filter afk` |
| `adb_app_start.py` | Start app by package | `-p PACKAGE`, `--wait` | `uv run scripts/app/adb_app_start.py -p com.afk.journey` |
| `adb_app_stop.py` | Force stop app | `-p PACKAGE` | `uv run scripts/app/adb_app_stop.py -p com.afk.journey` |
| `adb_app_install.py` | Install APK | `--apk FILE` | `uv run scripts/app/adb_app_install.py --apk game.apk` |
| `adb_app_uninstall.py` | Uninstall app | `-p PACKAGE`, `--keep-data` | `uv run scripts/app/adb_app_uninstall.py -p com.example` |

#### ℹ️ Info (4 scripts)

**Location**: `scripts/info/`

| Script | Purpose | Key Options | Example |
|--------|---------|-------------|---------|
| `adb_device_info.py` | Device specifications | `--toon` | `uv run scripts/info/adb_device_info.py` |
| `adb_display_info.py` | Display resolution/DPI | `--toon` | `uv run scripts/info/adb_display_info.py` |
| `adb_running_app.py` | Current foreground app | `--toon` | `uv run scripts/info/adb_running_app.py` |
| `adb_battery_info.py` | Battery status | `--toon` | `uv run scripts/info/adb_battery_info.py` |

#### ⚡ Performance (3 scripts)

**Location**: `scripts/performance/`

| Script | Purpose | Key Options | Example |
|--------|---------|-------------|---------|
| `adb_cpu_monitor.py` | Real-time CPU monitoring | `--duration SECONDS`, `--package PKG` | `uv run scripts/performance/adb_cpu_monitor.py --duration 60` |
| `adb_memory_monitor.py` | Memory usage monitoring | `--duration SECONDS`, `--package PKG` | `uv run scripts/performance/adb_memory_monitor.py --duration 60` |
| `adb_logcat_filter.py` | Filter logcat logs | `--tag TAG`, `--priority {V,D,I,W,E,F}`, `--follow` | `uv run scripts/performance/adb_logcat_filter.py --tag MyApp --priority E` |

#### 🤖 Automation (4 scripts)

**Location**: `scripts/automation/`

| Script | Purpose | Key Options | Example |
|--------|---------|-------------|---------|
| `adb_game_loop.py` | Execute repeating sequence | `-s FILE`, `-l LOOPS`, `--infinite` | `uv run scripts/automation/adb_game_loop.py -s daily.json -l 10` |
| `adb_wait_for_app.py` | Wait for app to start | `--package PKG`, `--timeout SECONDS` | `uv run scripts/automation/adb_wait_for_app.py -p com.afk.journey` |
| `adb_click_sequence.py` | Execute sequence once | `-s FILE` | `uv run scripts/automation/adb_click_sequence.py -s tutorial.json` |
| `adb_screenshot_compare.py` | Compare screenshots | `-b BEFORE -a AFTER`, `--threshold FLOAT` | `uv run scripts/automation/adb_screenshot_compare.py -b ref.png -a test.png` |

#### 🛠️ Utils (3 scripts)

**Location**: `scripts/utils/`

| Script | Purpose | Key Options | Example |
|--------|---------|-------------|---------|
| `adb_shell.py` | Execute shell commands | `-c COMMAND`, `--timeout SECONDS` | `uv run scripts/utils/adb_shell.py -c "ls /sdcard"` |
| `adb_push.py` | Push file to device | `-l LOCAL -r REMOTE` | `uv run scripts/utils/adb_push.py -l file.txt -r /sdcard/` |
| `adb_pull.py` | Pull file from device | `-r REMOTE -l LOCAL` | `uv run scripts/utils/adb_pull.py -r /sdcard/screenshot.png -l .` |

#### 🔧 Monitoring (7 scripts)

**Location**: `scripts/` (root level)

| Script | Purpose | Key Options | Example |
|--------|---------|-------------|---------|
| `adb_bot_generator.py` | Generate bot scripts | `--template NAME`, `--output FILE` | `uv run scripts/adb_bot_generator.py --template daily_quests` |
| `adb_config_validator.py` | Validate configs | `--config FILE`, `--strict` | `uv run scripts/adb_config_validator.py --config config.json` |
| `adb_deployment_helper.py` | Deploy to devices | `--apk FILE`, `--all`, `--devices IDS` | `uv run scripts/adb_deployment_helper.py --apk game.apk --all` |
| `adb_device_analyzer.py` | Analyze capabilities | `--aspects LIST`, `--output FILE` | `uv run scripts/adb_device_analyzer.py --aspects performance,battery` |
| `adb_game_tester.py` | Test game automation | `--test-suite FILE`, `--screenshots` | `uv run scripts/adb_game_tester.py --test-suite tests.json` |
| `adb_performance_profiler.py` | Profile performance | `--package PKG`, `--duration SECONDS` | `uv run scripts/adb_performance_profiler.py -p com.afk.journey` |
| `adb_template_creator.py` | Create templates | `--name NAME`, `--category CAT` | `uv run scripts/adb_template_creator.py --name my_automation` |

### JSON Sequence Format (Automation Scripts)

For `adb_game_loop.py` and `adb_click_sequence.py`, use JSON format:

```json
{
  "name": "Daily Quest Automation",
  "steps": [
    {"action": "tap", "x": 500, "y": 1000, "delay": 2},
    {"action": "swipe", "start": [500, 1500], "end": [500, 500], "duration": 300},
    {"action": "wait", "duration": 3},
    {"action": "screenshot", "output": "/tmp/check.png"},
    {"action": "keyevent", "key": "back"},
    {"action": "text_input", "text": "Hello World"}
  ]
}
```

**Supported Actions**: tap, swipe, wait, screenshot, keyevent, text_input

### Common Utilities

All scripts use shared utilities from `scripts/common/`:

- **`adb_utils.py`** - ADB device operations and connection management
- **`cli_utils.py`** - Click decorators, Rich formatters, output helpers
- **`error_handlers.py`** - Standardized error handling and exit codes (0, 2, 3, 4)
- **`path_utils.py`** - Project root detection and path resolution

### Exit Codes

All scripts use standardized exit codes:
- **0** - Success
- **2** - Device offline or not found
- **3** - ADB command failed or execution error
- **4** - Invalid argument or configuration

### Output Formats

**Text Output** (default): Rich-formatted console output with colors and tables
**TOON Output** (`--toon`): YAML/structured format for automation and parsing

---

## 📞 Support & References

**Quick Links**:
- **Modules**: See individual module files in `modules/`
- **Scripts**: See individual scripts in `scripts/` with `--help`
- **Examples**: See integration patterns in adb-* agents
- **Tests**: See test suite in `tests/`

**Context7 References**:
- [Android ADB Protocol](https://developer.android.com/tools/adb) (Android Developers)
- [Python ADB Library](https://github.com/google/adb_home) (Google GitHub)
- [OpenCV Documentation](https://docs.opencv.org) (OpenCV Docs)
- [Tesseract OCR](https://github.com/UB-Mannheim/tesseract/wiki) (GitHub)

---

**Version**: 1.0.0
**Status**: ✅ Production Ready (Phase 1 Foundation)
**Last Updated**: 2025-12-01
**Next Phase**: Create 5 core modules + 7 UV scripts