home / skills / terrylica / cc-skills / python-workspace

python-workspace skill

safe

This skill translates MQL5 indicators to Python with autonomous validation and self-correction for seamless MT5 workflows.

npx playbooks add skill terrylica/cc-skills --skill python-workspace

Review the files below or copy the command above to add this skill to your agents.

Files (5)

SKILL.md

3.8 KB

---
name: python-workspace
description: Python workspace for MQL5 integration. TRIGGERS - MetaTrader 5 Python, mt5 package, MQL5-Python setup.
---

# MQL5-Python Translation Workspace Skill

Seamless MQL5 indicator translation to Python with autonomous validation and self-correction.

---

## When to Use This Skill

Use this skill when the user wants to:

- Export market data or indicator values from MetaTrader 5
- Translate MQL5 indicators to Python implementations
- Validate Python indicator accuracy against MQL5 reference
- Understand MQL5-Python workflow capabilities and limitations
- Troubleshoot common translation issues

**Activation Phrases**: "MQL5", "MetaTrader", "indicator translation", "Python validation", "export data", "mql5-crossover workspace"

---

## Core Mission

**Main Theme**: Make MQL5-Python translation **as seamless as possible** through:

1. **Autonomous workflows** (headless export, CLI compilation, automated validation)
1. **Validation-driven iteration** (>=0.999 correlation gates all work)
1. **Self-correction** (documented failures prevent future mistakes)
1. **Clear boundaries** (what works vs what doesn't, with alternatives)

**Project Root**: `/Users/terryli/Library/Application Support/CrossOver/Bottles/MetaTrader 5/drive_c`

---

## Workspace Capabilities Matrix

### WHAT THIS WORKSPACE CAN DO

#### 1. Automated Headless Market Data Export (v3.0.0)

**Status**: PRODUCTION (0.999920 correlation validated)

**What It Does**:

- Fetches OHLCV data + built-in indicators (RSI, SMA) from any symbol/timeframe
- True headless via Wine Python + MetaTrader5 API
- No GUI initialization required (cold start supported)
- Execution time: 6-8 seconds for 5000 bars

**Command Example**:

```bash
CX_BOTTLE="MetaTrader 5" \
WINEPREFIX="$HOME/Library/Application Support/CrossOver/Bottles/MetaTrader 5" \
wine "C:\\Program Files\\Python312\\python.exe" \
  "C:\\users\\crossover\\export_aligned.py" \
  --symbol EURUSD --period M1 --bars 5000
```

**Use When**: User needs automated market data exports without GUI interaction

**Limitations**: Cannot access custom indicator buffers (API restriction)

**Reference**: `/docs/guides/WINE_PYTHON_EXECUTION.md`

---

## Reference Documentation

For detailed information, see:

- [Capabilities Detailed](./references/capabilities-detailed.md) - In-depth capability documentation
- [Complete Workflows](./references/workflows-complete.md) - End-to-end user workflows
- [Troubleshooting & Errors](./references/troubleshooting-errors.md) - Requirements, assumptions, error patterns
- [Validation Metrics](./references/validation-metrics.md) - Success metrics and version history

---

## Troubleshooting

| Issue                        | Cause                        | Solution                                             |
| ---------------------------- | ---------------------------- | ---------------------------------------------------- |
| Wine Python not found        | CrossOver/Wine not installed | Install CrossOver, verify bottle path                |
| MT5 API connection failed    | MetaTrader not running       | Launch MetaTrader 5 before running export            |
| Correlation below 0.999      | Indicator mismatch           | Verify warmup periods, check calculation alignment   |
| Custom indicator not working | API restriction              | Use CSV export from MT5, not Python API              |
| UnicodeDecodeError           | Windows path encoding        | Use raw strings for Windows paths in Wine            |
| Symbol not found             | Wrong symbol format          | Use exact MT5 symbol name (e.g., EURUSD not EUR/USD) |
| Timeout on export            | Too many bars requested      | Reduce bar count, default 5000 is safe               |
| Permission denied            | Wine prefix incorrect        | Set WINEPREFIX to correct CrossOver bottle path      |

Overview

This skill provides a Python workspace for integrating with MetaTrader 5 (MQL5) to export market data, translate MQL5 indicators into Python, and validate translations automatically. It focuses on headless execution using Wine/CrossOver, automated validation with strict correlation gates, and self-correcting workflows. The goal is reliable, reproducible indicator translations and data exports for downstream analysis and backtesting.

How this skill works

The workspace runs Wine-hosted Python to call the MetaTrader5 API and export OHLCV plus selected built-in indicators without launching the MT5 GUI. Translation tools convert MQL5 indicator logic into Python, then automated validation compares outputs to the MQL5 reference using correlation thresholds (>= 0.999). Failures are recorded with diagnostics to enable iterative self-correction and reproducible reruns.

When to use it

You need automated, headless exports of MT5 market data or built-in indicator values.
You want to convert an MQL5 indicator to Python and validate numeric equivalence.
You need reproducible exports for backtesting or drift detection without GUI interaction.
You’re troubleshooting translation mismatches between MQL5 and Python implementations.
You must run exports from macOS or Linux using CrossOver/Wine to host MT5.

Best practices

Set WINEPREFIX to the correct CrossOver bottle and verify MT5 is installed and runnable before export.
Use default warmup and bar-count settings (e.g., 5000 bars) to reduce timeout and correlation issues.
Validate translations with the provided >=0.999 correlation gate; investigate warmup and buffer alignment if below threshold.
Record failures and diagnostics so the self-correction routine can learn and avoid repeat mistakes.
If a custom indicator buffer is required, export CSV from MT5 as a fallback because the Python API cannot access custom buffers.

Example use cases

Headless nightly export of EURUSD M1 OHLCV plus RSI and SMA into a data lake for model training.
Translate a published MQL5 indicator to Python, validate the implementation, and integrate into a backtesting framework.
Automated CI step that compiles and validates translated indicators before deployment to production strategies.
Troubleshoot low-correlation translations by generating diagnostic exports and comparing warmup alignment with the MQL5 reference.

FAQ

Can this workspace access custom MQL5 indicator buffers?

No. The MT5 Python API cannot read custom indicator buffers. Use MT5 CSV export as a fallback for custom buffers.

What causes low correlation between MQL5 and Python outputs?

Common causes are mismatched warmup periods, different calculation alignment, or symbol/timeframe mismatches. Check warmup, bar alignment, and exact MT5 symbol name.