feat: SL/TP risk formulas, project docs, symbol specs
SKILL.md Section 5 rewritten with PointValue-based formulas:
- Direction A: SL points → SL price
- Direction B: Risk% + lots → SL price (with currency conversion)
- Direction C: SL price + risk% → lot size
- FindFXRate helper for profit_currency ≠ account_currency
- OrderCalcProfit verification pattern
Section 8 expanded with 6 SL/TP pitfalls (PointValue vs TICK_VALUE,
TickSize ≠ Point, currency conversion, NormalizeDouble rounding,
lot step quantization, STOPS_LEVEL check).
Section 9 EA skeleton now includes inline PointValue, FindFXRate,
CalcSLFromRisk, CalcLotsFromSL functions.
New files:
- LICENSE (MIT)
- README.md
- docs-dev/symbol-spec.md (symbol spec workflow)
- skills/mql5/references/symbol-spec/specs-{XAUUSD,USDJPY}.csv
- skills/mql5/scripts/verify_sl_tp_formulas.py (Python verification)
Updated: pyproject.toml, AGENTS.md, .gitignore, docs-dev/skill-design.md
This commit is contained in:
ZhijuCen
+57
-70
@@ -9,106 +9,93 @@ conforming to the [AgentSkills.io Specification](https://agentskills.io/specific
|
||||
---
|
||||
name: mql5
|
||||
description: >
|
||||
MQL5 development skill for MetaTrader 5. Covers Expert Advisors, Indicators,
|
||||
Scripts, and Services. Focus on positions, orders, indicators, ticks, and bars.
|
||||
Includes programming book and API reference documentation.
|
||||
MQL5 development skill for MetaTrader 5 Expert Advisors, Indicators, Scripts,
|
||||
and Services. Focus on positions, orders, indicators, ticks, bars, risk
|
||||
management, backtesting, and multi-instance MT5 operations. Includes
|
||||
programming book and API reference documentation.
|
||||
version: "0.1"
|
||||
license: MIT
|
||||
compatibility: >
|
||||
Target: MetaTrader 5 platform. Language: MQL5 (C++-like syntax).
|
||||
File extensions: *.mq5 (source), *.mqh (headers).
|
||||
References: mql5.com/en/book (programming), mql5.com/en/docs (API).
|
||||
Run time: Windows native, Linux via Wine, macOS via Wine.
|
||||
metadata:
|
||||
project-version: "0.1.0"
|
||||
sources:
|
||||
book: sitemaps/sitemap_book_en.xml (581 URLs)
|
||||
docs: sitemaps/sitemap_docs_en.xml (4135 URLs)
|
||||
focus-areas:
|
||||
- positions
|
||||
- orders
|
||||
- indicators
|
||||
- ticks
|
||||
- bars
|
||||
- risk-management
|
||||
- backtesting
|
||||
---
|
||||
```
|
||||
|
||||
## Body Content Structure
|
||||
|
||||
The body should be structured as follows:
|
||||
### 1. MQL5 Fundamentals
|
||||
- Language and file types (.mq5, .mqh, .ex5)
|
||||
- Program types: EA, Indicator, Script, Service
|
||||
- MQL5 directory structure (Windows, Linux/Wine)
|
||||
- Multi-instance MT5 operations
|
||||
|
||||
### 1. Overview
|
||||
### 2. Trading Operations
|
||||
- Core concepts: Order, Deal, Position
|
||||
- CTrade class usage patterns
|
||||
- Position queries (Hedging vs Netting)
|
||||
- Order execution pattern with error handling
|
||||
|
||||
Brief description of MQL5 and MetaTrader 5:
|
||||
- MQL5 is the programming language for MetaTrader 5
|
||||
- Syntax similar to C++
|
||||
- File types: `.mq5` (source), `.mqh` (headers)
|
||||
- Program types: Expert Advisors, Indicators, Scripts, Services
|
||||
### 3. Indicators and Multi-Timeframe
|
||||
- Built-in indicator handles (iMA, iRSI, iMACD, iBands)
|
||||
- Reading indicator values via CopyBuffer
|
||||
- Multi-timeframe analysis pattern
|
||||
- New bar detection
|
||||
|
||||
### 2. Quick Reference — Key Operations
|
||||
### 4. Ticks and Bars
|
||||
- Timeseries access (MqlRates, ArraySetAsSeries)
|
||||
- Tick data (MqlTick, SymbolInfoTick)
|
||||
- Key functions table
|
||||
|
||||
Focus areas with concise API patterns:
|
||||
### 5. Risk Management and Lot Sizing
|
||||
- **PointValue concept**: profit-currency per 1-point move for 1 lot
|
||||
- Forex/CFD: `point × ContractSize`
|
||||
- Futures: `point × TickValue / TickSize`
|
||||
- **Direction A**: SL distance points → SL price
|
||||
- **Direction B**: Risk% + fixed lots → SL price (with currency conversion)
|
||||
- **Direction C**: SL price + risk% → lot size
|
||||
- **Profit verification**: OrderCalcProfit + manual formula
|
||||
- Risk-to-Reward ratio
|
||||
- Position sizing rules (7 rules)
|
||||
|
||||
#### Positions
|
||||
- `CTrade` class for position management
|
||||
- `PositionGetSymbol()`, `PositionSelect()`, `PositionGetDouble()`
|
||||
- `CTrade::PositionOpen()`, `CTrade::PositionClose()`
|
||||
### 6. Backtesting and Optimization
|
||||
- Strategy Tester concepts
|
||||
- OnTester custom optimization criterion
|
||||
- Key statistics table
|
||||
- Backtesting workflow
|
||||
|
||||
#### Orders
|
||||
- `CTrade::OrderSend()` for pending orders
|
||||
- `ORDER_TYPE_BUY_LIMIT`, `ORDER_TYPE_SELL_LIMIT`, etc.
|
||||
- `OrderGetTicket()`, `OrderSelect()`
|
||||
### 7. Event Handlers Reference
|
||||
- Handler table (OnInit through OnTesterPass)
|
||||
|
||||
#### Indicators
|
||||
- `iMA()`, `iRSI()`, `iMACD()`, `iBands()` — built-in indicators
|
||||
- `CopyBuffer()` to read indicator values
|
||||
- `IndicatorCreate()` for custom indicators
|
||||
### 8. Common Pitfalls
|
||||
- **General** (10 items): ResultRetcode, MagicNumber, NormalizeDouble, etc.
|
||||
- **SL/TP and Risk Calculation** (6 items): PointValue vs TICK_VALUE,
|
||||
TickSize vs Point, currency conversion, NormalizeDouble rounding,
|
||||
lot step quantization, STOPS_LEVEL check
|
||||
|
||||
#### Ticks
|
||||
- `SymbolInfoTick()` — current tick data
|
||||
- `MqlTick` structure: `bid`, `ask`, `last`, `volume`, `time`
|
||||
- `OnTick()` handler for Expert Advisors
|
||||
### 9. Quick Reference — EA Skeleton
|
||||
- Complete EA template with inline risk functions:
|
||||
- `PointValue()`, `FindFXRate()`, `CalcSLFromRisk()`, `CalcLotsFromSL()`
|
||||
- OnTick example with SL calculation and loss verification
|
||||
|
||||
#### Bars
|
||||
- `Bars()`, `BarsCalculated()` — bar count
|
||||
- `CopyOpen()`, `CopyHigh()`, `CopyLow()`, `CopyClose()`, `CopyVolume()`
|
||||
- `CopyRates()`, `CopyTime()`
|
||||
- `CTerminalInfo`, `CSymbolInfo` for symbol/bar info
|
||||
|
||||
### 3. Program Types
|
||||
|
||||
| Type | Purpose | Key Handler |
|
||||
|------|---------|-------------|
|
||||
| Expert Advisor | Automated trading | `OnTick()`, `OnInit()`, `OnDeinit()` |
|
||||
| Indicator | Technical analysis | `OnCalculate()` |
|
||||
| Script | One-shot execution | `OnStart()` |
|
||||
| Service | Background task | `OnStart()`, `OnTimer()` |
|
||||
|
||||
### 4. Common Patterns
|
||||
|
||||
- Trade execution with error handling
|
||||
- Indicator buffer management
|
||||
- Timer-based operations
|
||||
- Chart object manipulation
|
||||
- File I/O for logging/data
|
||||
|
||||
### 5. References
|
||||
|
||||
Point to the extracted documentation:
|
||||
- `references/book/` — Programming book (learning path)
|
||||
- `references/docs/` — API reference (function/type lookup)
|
||||
|
||||
### 6. Pitfalls & Best Practices
|
||||
|
||||
- `RefreshRates()` before trading operations
|
||||
- `NormalizeDouble()` for price comparisons
|
||||
- Check `Retcode()` after trade operations
|
||||
- Use `CTrade` class over raw `OrderSend()`
|
||||
- Handle `OnTimer()` for periodic operations
|
||||
- Test with Strategy Tester before live deployment
|
||||
### 10. References
|
||||
- In-skill references (book/, docs/, symbol-spec/, scripts/)
|
||||
- External links (MQL5 Reference, MQL5 Book, Strategy Tester Guide)
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
- The SKILL.md should be concise (< 1024 chars for description, body can be longer)
|
||||
- Body is loaded as context by AI agents — prioritize actionable patterns
|
||||
- Reference files provide depth; SKILL.md provides the "what to do"
|
||||
- Risk formulas verified against real symbol specs (XAUUSD, USDJPY)
|
||||
via `scripts/verify_sl_tp_formulas.py`
|
||||
- Version 0.1: initial content, will expand as extraction completes
|
||||
|
||||
@@ -0,0 +1,83 @@
|
||||
# Symbol Specification Workflow
|
||||
|
||||
Broker-specific symbol specifications stored as CSV files, used by the
|
||||
SL/TP risk formula verification script.
|
||||
|
||||
## Location
|
||||
|
||||
```
|
||||
skills/mql5/references/symbol-spec/
|
||||
├── specs-XAUUSD.csv
|
||||
├── specs-USDJPY.csv
|
||||
└── ...
|
||||
```
|
||||
|
||||
## CSV Format
|
||||
|
||||
Each file is a two-column CSV (`Property,Value`) exported from the MT5
|
||||
Symbol Properties dialog. Key fields:
|
||||
|
||||
| Field | Example (XAUUSD) | Example (USDJPY) | Used By |
|
||||
|-------|-------------------|-------------------|---------|
|
||||
| Digits | 2 | 3 | NormalizeDouble, Point |
|
||||
| Contract size | 100 | 100000 | PointValue, profit formula |
|
||||
| Calculation | CFD Leverage | Forex | Formula selection |
|
||||
| Tick size | 0.01 | 0.001 | Futures formula |
|
||||
| Tick value | 1.0 | 0.618839 | Futures formula |
|
||||
| Stops level | 0 | 0 | Min SL distance check |
|
||||
| Profit currency | USD | JPY | Currency conversion |
|
||||
| Minimal volume | 0.01 | 0.01 | Lot normalization |
|
||||
| Maximal volume | 80.00 | 80.00 | Lot normalization |
|
||||
| Volume step | 0.01 | 0.01 | Lot normalization |
|
||||
|
||||
## How to Export from MT5
|
||||
|
||||
1. In MT5: Tools → Symbols (or press Ctrl+U)
|
||||
2. Select the symbol → Properties tab
|
||||
3. Right-click → "Copy" or manually record values
|
||||
4. Create `specs-{SYMBOL}.csv` with the `Property,Value` format
|
||||
|
||||
## How to Add a New Symbol
|
||||
|
||||
1. Export specs from MT5 (see above)
|
||||
2. Save as `skills/mql5/references/symbol-spec/specs-{SYMBOL}.csv`
|
||||
3. Add the symbol to `verify_sl_tp_formulas.py`:
|
||||
```python
|
||||
specs = {
|
||||
"XAUUSD": SymbolSpec.from_csv(SPEC_DIR / "specs-XAUUSD.csv"),
|
||||
"USDJPY": SymbolSpec.from_csv(SPEC_DIR / "specs-USDJPY.csv"),
|
||||
"EURUSD": SymbolSpec.from_csv(SPEC_DIR / "specs-EURUSD.csv"), # new
|
||||
}
|
||||
bids = {"XAUUSD": 4121.28, "USDJPY": 161.561, "EURUSD": 1.0850}
|
||||
fx_rates = {"XAUUSD": 1.0, "USDJPY": 161.561, "EURUSD": 1.0}
|
||||
```
|
||||
4. Run `python skills/mql5/scripts/verify_sl_tp_formulas.py` to verify
|
||||
|
||||
## Key Distinctions by Calc Mode
|
||||
|
||||
### Forex (SYMBOL_CALC_MODE_FOREX)
|
||||
- Profit = `(close - open) × ContractSize × Lots`
|
||||
- PointValue = `point × ContractSize`
|
||||
- Example: USDJPY — ContractSize=100000, PointValue=100 JPY/pt/lot
|
||||
|
||||
### CFD Leverage (SYMBOL_CALC_MODE_CFDLEVERAGE)
|
||||
- Profit = `(close - open) × ContractSize × Lots`
|
||||
- PointValue = `point × ContractSize`
|
||||
- Example: XAUUSD — ContractSize=100, PointValue=1.0 USD/pt/lot
|
||||
|
||||
### Futures (SYMBOL_CALC_MODE_FUTURES)
|
||||
- Profit = `(close - open) × TickValue / TickSize × Lots`
|
||||
- PointValue = `point × TickValue / TickSize`
|
||||
- Uses broker-supplied TickValue instead of ContractSize
|
||||
|
||||
## Currency Conversion
|
||||
|
||||
When `SYMBOL_CURRENCY_PROFIT ≠ ACCOUNT_CURRENCY`:
|
||||
|
||||
```
|
||||
risk_profcy = risk_account_cy × fx_rate
|
||||
```
|
||||
|
||||
The verification script uses the `FindFXRate` helper to locate a Forex pair
|
||||
in Market Watch that converts between the two currencies. In MQL5 code,
|
||||
this is implemented in `SKILL.md` Section 5 (Direction B/C).
|
||||
Reference in New Issue
Block a user