opencode-skills-collection 4.0.74 → 4.0.75

package/bundled-skills/radar-satellite-analysis/SKILL.md

@@ -0,0 +1,314 @@
+---
+name: radar-satellite-analysis
+description: "Interpret weather radar and satellite observations by validating product metadata and geometry, deriving storm and cloud structures, tracking evolution, and quantifying uncertainty."
+category: analysis
+risk: safe
+source: self
+source_type: self
+date_added: "2026-09-25"
+author: ShianMike
+tags: [weather, radar, satellite, nexrad, goes, nowcasting, storm-analysis, remote-sensing, uncertainty]
+tools: [claude, cursor, gemini, codex]
+---
+
+# Radar and Satellite Analysis
+
+## Overview
+
+Analyze radar and satellite weather products as remote-sensing observations,
+not as ground truth. Validate scan time, geometry, calibration, quality flags,
+and coverage before interpreting a feature. Then separate what the instrument
+directly measures from what a meteorological inference suggests.
+
+This skill consumes already retrieved and decoded products. Use it after
+`noaa-radar-satellite-fetching` or an equivalent source-specific skill. It does
+not discover buckets, download files, repair outages, or make a product
+scientifically suitable by naming it radar or satellite data.
+
+## When to Use This Skill
+
+- Interpret NEXRAD reflectivity, velocity, spectrum width, or multi-moment
+  volumes.
+- Track storm growth, decay, splits, mergers, rotation, anvils, or cloud-top
+  evolution over time.
+- Analyze GOES visible, infrared, water-vapor, or derived cloud and convection
+  products.
+- Combine radar structure with satellite cloud-top evidence while preserving
+  each sensor's limitations.
+- Produce a short-term precipitation or severe-weather nowcast from a sequence
+  of observations.
+- Explain why a radar or satellite feature is—or is not—supported by the data.
+
+Do not infer a surface hail size, wind speed, rainfall rate, or lightning count
+from a single proxy without stating the retrieval assumptions. Do not use a
+single still image to claim a storm's future track or intensity.
+
+## Define the Remote-Sensing Analysis Contract
+
+Before interpreting pixels, beams, or profiles, record:
+
+- event, target phenomenon, region, and UTC interval;
+- radar site, product level, scan/volume interval, elevation angles, moments,
+  and resolution—or satellite platform, product, sector, channel, scan mode,
+  and resolution;
+- the measurement height or viewing geometry;
+- the quality masks, calibration or scaling, and missing-data policy;
+- the temporal cadence and the allowed lag between radar, satellite,
+  observations, and model guidance;
+- the feature definition and the expected output: structure, motion,
+  intensity proxy, nowcast, or uncertainty map;
+- the criteria for a confident, tentative, or inconclusive interpretation.
+
+Keep observation time, scan start/end time, file creation time, retrieval time,
+and analysis time separate. A file created quickly after a scan is not a newer
+measurement.
+
+## Validate the Products Before Interpretation
+
+### Common checks
+
+1. Confirm the radar site or physical satellite, product identity, sector,
+   channel or moment, and expected dimensions from the decoded metadata.
+2. Verify the time interval, scan start and end, coordinate reference system,
+   and geolocation. For GOES fixed grids, use the product's geostationary
+   projection metadata rather than treating scan `x` and `y` as latitude and
+   longitude.
+3. Apply the product's documented scale, offset, fill values, calibration, and
+   quality flags before computing statistics or thresholds.
+4. Inspect missing scans, partial volumes, data gaps, saturated or invalid
+   values, and spatial coverage. Do not smooth over a gap without labeling it.
+5. Record the resolution, footprint, and observation uncertainty. A high pixel
+   count is not a high spatial resolution if the beam or channel is coarse.
+
+### Radar-specific checks
+
+- Confirm site, volume start/end time, sweep count, moments, and elevation
+  angles. Level II, Level III, and real-time chunk products are not
+  interchangeable encodings.
+- Account for range-dependent beam width, beam height above the radar, terrain
+  blockage, range folding, attenuation, clutter, anomalous propagation, and
+  velocity dealiasing where relevant.
+- Determine whether a feature is sampled by one low-level sweep, several
+  elevation angles, or a full vertical column. Do not compare a low-level echo
+  top with a satellite cloud top as if they were the same physical surface.
+- Keep base reflectivity, column-integrated liquid, echo top, and derived
+  products distinct. Their thresholds and physical meanings are not
+  interchangeable.
+
+### Satellite-specific checks
+
+- Confirm platform, instrument, product short name, channel or RGB product,
+  sector, scan mode, and scan interval from file attributes.
+- Apply channel-specific calibration and quality flags. Brightness
+  temperature, reflectance, cloud-top temperature, and land-surface
+  temperature are different quantities.
+- Treat cloud-top parallax as a viewing-geometry problem. A high cloud can be
+  displaced from its surface footprint, especially near the edge of a sector.
+- Distinguish visible, infrared, water-vapor, and derived RGB products. Their
+  interpretation depends on reflectance, emission, atmospheric absorption, and
+  daylight or scan mode.
+
+## Analyze Radar Structure
+
+### Reflectivity and precipitation proxies
+
+Use reflectivity to describe the location and organization of precipitation
+echoes, then qualify the interpretation with beam height, range, attenuation,
+and sampling. Look for features such as:
+
+- high-reflectivity cores and their relationship to weaker surrounding echo;
+- echo overhangs, weak-echo regions, bounded weak-echo regions, and vertical
+  development;
+- bow, hook, line, multicell, or training structures when the geometry supports
+  that description;
+- echo-top or vertically integrated liquid patterns that are relevant to the
+  stated question.
+
+Do not call a reflectivity threshold hail, tornado, or destructive wind. Those
+are conditional interpretations requiring velocity, cloud-top, lightning,
+surface, or model context. Convert reflectivity to rain rate only with an
+explicit relation, sample assumptions, and uncertainty bounds; a reflectivity
+lookup is not a universal precipitation truth.
+
+### Velocity and rotation
+
+Analyze radial velocity as a radar-relative measurement. State whether the
+field is gate-to-gate shear, environmental shear, storm-relative radial flow, or
+a derived couplet. Consider dealiasing, range folding, noise, side lobes,
+velocity folding artifacts, and the fact that a velocity signature can have
+multiple meteorological explanations.
+
+For rotation or mesocyclone interpretation, use the appropriate temporal,
+azimuthal, and vertical support and compare the result with neighboring scans.
+A single couplet is a candidate feature, not a confirmed tornado. Do not use
+radial velocity as a direct measurement of the environmental wind vector
+without accounting for viewing geometry.
+
+### Three-dimensional organization
+
+When a volume supports it, align elevation angles and analyze vertical
+structure: low-level inflow, mid-level rotation, updraft organization, echo
+top, overhang, and bounded weak-echo regions. Account for increasing beam
+volume and decreasing resolution with height. A feature that appears vertically
+stacked may be a sampling or attenuation artifact; check adjacent sites or
+scans before asserting a continuous structure.
+
+## Analyze Satellite Cloud and Storm Structure
+
+Use satellite data to describe cloud-top and environmental context, not to
+replace radar precipitation structure. Depending on the product, examine:
+
+- cloud-top temperature, brightness-temperature gradients, and overshooting
+  top candidates;
+- anvil extent, spreading direction, and relationship to upper-level outflow;
+- deep-convective cloud shields and mesoscale convective systems;
+- visible-texture changes, cloud-top lowering or warming, and inferred growth or
+  decay only with a time sequence;
+- water-vapor patterns, upper-level moisture, and potential convective
+  environments when the product and resolution support those claims.
+
+An infrared cold cloud top is not, by itself, proof of severe weather, hail,
+or a particular updraft strength. A very cold top can reflect a high cloud
+whose emission and viewing geometry differ from a nearby lower cloud. State the
+proxy, the threshold, and the alternative explanation.
+
+## Track Evolution and Motion
+
+For a time sequence, use a consistent feature-identification and tracking
+method. Track cell or cloud-system centers, echoes or anvils, growth and decay,
+merges and splits, and changes in shape or intensity proxy. Distinguish motion
+from the steering flow and from apparent motion caused by parallax, changing
+scan geometry, or inconsistent feature definitions.
+
+Estimate motion over multiple scans and report the method, time interval,
+position uncertainty, and whether the feature was occluded or lost. A single
+displacement between scans is not a reliable nowcast. If a forecast window is
+short, say so and show the persistence or extrapolation assumption.
+
+## Combine Radar and Satellite Carefully
+
+Align the products in time and space before joining them. Radar can provide
+precipitation structure, radial motion, and vertical echoes; satellite can
+provide broad cloud shield, cloud-top context, anvils, and environmental
+patterns. Their footprints, resolution, viewing geometry, and quality are not
+identical.
+
+Use a joint interpretation only when the evidence is complementary. For
+example, a radar core beneath a rapidly developing cold cloud top can support a
+convective-growth diagnosis, but it still does not establish surface hail or a
+confirmed tornado. Preserve each source's quality mask and contribution in the
+final result instead of collapsing them into an opaque score.
+
+For multi-radar mosaics, resolve overlapping beams using a documented rule.
+Never average dBZ values or velocity fields across sites without a physical and
+quality-aware rule. A mosaic should show coverage and the selected source for
+each pixel or cell.
+
+## Quantify Uncertainty and Avoid Overclaiming
+
+Remote-sensing interpretation has several uncertainty sources: beam geometry,
+attenuation, parallax, threshold choice, temporal resolution, feature tracking,
+instrument calibration, cloud microphysics, and incomplete coverage. When the
+task is operational or safety-relevant, report the strongest alternative
+interpretation and the observations that would distinguish it.
+
+Use a bounded nowcast horizon and show how the result changes with alternate
+motion, persistence, growth, or decay assumptions. Do not turn a qualitative
+feature label into a precise probability without a calibration method. If the
+images are too sparse, ambiguous, or poorly geolocated, report that the
+feature is unconfirmed rather than filling the gap with narrative certainty.
+
+## Examples
+
+When asked whether a storm intensified over an hour, align successive radar
+volumes and satellite scans, verify time and geolocation, and track one
+consistent feature definition. Report measured reflectivity and cloud-top
+changes separately from inferred intensification, include data gaps and
+uncertainty, and do not infer surface hail from a cold cloud top alone.
+
+For a suspected velocity couplet, inspect neighboring scans and available
+elevation angles, confirm radial-velocity convention and dealiasing quality,
+and call it a possible rotation signature unless the evidence supports a
+stronger conclusion.
+
+## Output Contract
+
+Return a traceable analysis with:
+
+1. the radar site or satellite platform, product, channel/moment, scan interval,
+   region, and time range;
+2. the preprocessing, calibration, geolocation, quality masking, and temporal
+   alignment steps;
+3. the observed feature locations, structure, motion, and evolution with the
+   supporting pixels or beams identified;
+4. a clear separation between direct measurements, derived indices, and
+   meteorological interpretation;
+5. uncertainty, alternative explanations, and coverage limitations;
+6. figures or maps that preserve timestamps, color scales, units, and source;
+7. provenance for the raw or materialized products and every derived artifact.
+
+Avoid a report that says only "severe storm," "heavy rain," or "rapidly
+developing convection" without a location, time, measured proxy, and evidence
+beneath the label.
+
+## Verification Checklist
+
+- Radar site or satellite platform and product metadata are confirmed.
+- Scan start/end time, retrieval time, and analysis time are distinct.
+- Geolocation, projection, scale/offset, calibration, and quality flags are
+  applied.
+- Beam height, beam width, range, terrain, attenuation, and radar artifacts are
+  considered where relevant.
+- Satellite channel meaning, scan mode, daylight dependence, and parallax are
+  considered.
+- Radar and satellite claims remain separate unless their alignment and
+  complementary evidence are explicit.
+- Feature tracking uses multiple scans and reports its motion assumptions.
+- Derived products include units, thresholds, coverage, and uncertainty.
+
+## Security & Safety Notes
+
+- Use only public or authorized radar and satellite products.
+- Do not expose AWS credentials, signed URLs, private bucket names, tokens, or
+  restricted provider metadata in reports or logs.
+- Treat filenames, metadata, and product attributes as untrusted input; validate
+  them before constructing paths or visualizations.
+- Bound scan counts, image sizes, decoding concurrency, and generated artifact
+  resolution.
+- Preserve NOAA, NEXRAD, GOES, and other provider attribution and license terms.
+
+## Common Pitfalls
+
+- **The file creation time was used as measurement time:** A delayed or
+  reprocessed product was placed at the wrong point in a storm timeline. Parse
+  scan start and end time.
+- **A cold cloud top became a hail claim:** An infrared proxy was treated as a
+  direct hail measurement. State the proxy and supporting evidence.
+- **Radar and satellite features did not line up:** Scan intervals, parallax,
+  geolocation, or beam height were ignored. Align the observations first.
+- **A reflectivity pixel became a rain rate:** A threshold or lookup relation
+  was used without its assumptions and uncertainty. Keep the measured quantity
+  separate from the estimate.
+- **A storm “rapidly intensified” from two frames:** A gap, feature mismatch, or
+  inconsistent threshold was mistaken for growth. Use a longer sequence and
+  tracking evidence.
+- **Radar mosaics hid artifacts:** Values were averaged across sites or a blocked
+  beam was treated as a complete field. Retain quality and source information.
+
+## Limitations
+
+- Radar and satellite products are remote-sensing observations with sampling,
+  calibration, attenuation, parallax, and coverage limitations.
+- A single product cannot uniquely identify every convective or microphysical
+  process.
+- Historical gaps, instrument outages, scan strategy changes, and provider
+  product changes cannot be repaired by interpretation alone.
+- This skill does not retrieve products, perform numerical model comparison, or
+  replace official warning and emergency-management guidance.
+
+## Additional Resources
+
+- [NOAA Radar Operations Center interface documents](https://www.roc.noaa.gov/wsr88d/BuildInfo/Files.aspx)
+- [NOAA NEXRAD on the AWS Registry of Open Data](https://registry.opendata.aws/noaa-nexrad/)
+- [NOAA GOES on the AWS Registry of Open Data](https://registry.opendata.aws/noaa-goes/)
+- [NOAA GOES-R documents](https://www.ospo.noaa.gov/resources/documents/goes-r.html)

package/bundled-skills/traderspy-market-briefing/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: traderspy-market-briefing
+description: "Crypto market briefing from live TraderSpy data: majors, funding, open interest, top-trader lean, fresh AI signals and screener movers. Use for \"what's happening in crypto\" or a recap."
+category: finance
+risk: safe
+source: "https://github.com/target1m/traderspy-mcp/tree/069aae5a84640d671f92705a2e3bc0b62efca1e0/skills/market-briefing"
+source_repo: target1m/traderspy-mcp
+source_type: official
+date_added: "2026-09-25"
+author: target1m
+tags: [traderspy, crypto, market-briefing, derivatives, mcp]
+tools: [claude, cursor, gemini]
+license: MIT
+license_source: "https://github.com/target1m/traderspy-mcp/blob/069aae5a84640d671f92705a2e3bc0b62efca1e0/LICENSE"
+---
+
+# TraderSpy Market Briefing
+
+A briefing is a fixed set of questions answered with fresh numbers, in an order a trader can scan
+in thirty seconds: where are the majors, how is the market positioned, what is the signal engine
+seeing, what stands out on the screener. The value is in the selection and the brevity, not in the
+volume of data — every tool call costs the user quota, so the playbook below is deliberately
+tight.
+
+## When to Use
+
+- Use when the user asks "what's happening in crypto", for a market update or a morning brief, "how's the market today", "anything interesting right now", an overview or a weekly recap.
+- Use when a conversation opens with a vague question about the crypto market, even a casual one.
+- Do not use for a deep dive on one coin (`@traderspy-technical-analysis`), one trader (`@traderspy-smart-money`) or one signal (`@traderspy-trading-signals`).
+
+## The playbook (6 calls, all read-only)
+
+1. **Majors** — `get_price` with `["BTCUSDT","ETHUSDT","SOLUSDT"]` plus any coins the user has
+   mentioned in the conversation (≤ 20 per call). Price, 24h change, 24h range.
+2. **Positioning** — `get_derivatives` with `["BTC","ETH","SOL"]` (add up to two of the user's
+   coins). Funding label and annualized rate, open-interest change and regime, top-trader long
+   share, taker flow. The `notes[]` are written to be quoted.
+3. **Movers** — `screen_symbols` with no conditions, `sortBy: "change24h"`, `limit: 50`, `universe:
+   50`, `interval: "4h"`. One call returns all 50 most-traded pairs sorted by 24h change: the top
+   five are the gainers, the last five the losers.
+4. **What is stretched** — `screen_symbols` with `[{"metric":"rsi","op":"lt","value":30}]` on 4h,
+   `limit: 5`. If it returns nothing, flip to `rsi gt 70` — one of the two usually has names.
+5. **Signal engine** — `get_signal_stats` with `period: "24h"` (or `7d` for a weekly recap).
+6. **Freshest ideas** — `get_signals` with `limit: 5`.
+
+Smart-money lean is already in step 2 (`positioning.topTraderLongPct`); add `get_positions`
+(`status: open`, `limit: 20`) only when the user asks who specifically is positioned how.
+
+**Quota-aware variants.** If the user is on a free key or asks for "just the headline", run steps
+1, 2 and 5 only (three calls) and say what you skipped. For a weekly recap use `7d` in step 5 and
+`interval: "1d"` in steps 3–4.
+
+If any call fails or returns empty, keep the section with a one-line "unavailable right now" note
+rather than dropping it silently — a briefing with a hole is more honest than one that quietly
+narrowed.
+
+## Reading the pieces
+
+- **Funding**: near the 0.01%/8h baseline is neutral; clearly positive means longs pay shorts (a
+  crowded long is a risk, not a signal); negative means shorts pay. Quote the annualized figure —
+  it is the number people feel.
+- **Open interest regime** (`openInterest.regime`): `new_longs` (OI up, price up), `short_covering`
+  (OI down, price up), `new_shorts` (OI up, price down), `long_liquidation` (OI down, price down),
+  `flat`. This is the one line that explains WHY the majors moved.
+- **Top-trader long share**: the tool labels `long_heavy` at a long/short ratio ≥ 1.5 (≈ 60%+
+  long) and `short_heavy` at ≤ 0.67 (≈ 40% or less); in between call it balanced. Top-trader
+  positioning is the more informative one; the all-account ratio shows the crowd.
+- **Signal stats**: `winRate` is hits ÷ (hits + stops) on signals created in the window; say
+  `total` and `pending` next to it, and treat a 24h window with fewer than ~10 resolved signals as
+  a small sample.
+- **Movers** are the most-traded pairs by 24h volume sorted by change — a liquid-names list, not
+  an all-market list. Say so if a small cap the user follows is missing.
+
+## The briefing format
+
+ALWAYS use this structure, in this order, with real numbers from the calls — no placeholders:
+
+**Crypto brief — <date, UTC time of the calls>**
+
+1. **Headline** — one sentence: the majors' direction and the single most notable positioning fact.
+2. **Majors** — a table: Symbol · Price · 24h % · 24h range.
+3. **Positioning** — per major, one line: funding (label, annualized), OI regime, top-trader long %,
+   and one quoted `note`.
+4. **Movers** — top 5 gainers and top 5 losers among the most-traded pairs (symbol, price, 24h %).
+5. **Stretched** — the oversold or overbought names with their RSI, or "none on the 4h" if empty.
+6. **Signal engine** — `total` signals in the window, hit rate with the resolved count, then the
+   five freshest signals as one line each: coin, side, timeframe, preset, status.
+7. **What to watch** — two or three bullets derived from the data above (a funding extreme, an OI
+   regime worth confirming, a stretched name that is also in a signal). Facts and their
+   implications, not instructions.
+8. One plain sentence: crypto derivatives are high-risk; this is market information for the user's
+   own research, not financial advice.
+
+Keep it under ~350 words. Numbers beat adjectives: "BTC −2.1% to 77,300, funding neutral, OI −2.7%
+with price flat" is a briefing; "BTC looks weak" is not.
+
+## Conduct
+
+- A briefing reports the market; it does not tell the user what to do in it. "What to watch" names
+  facts and what would confirm or invalidate them — never "buy the dip" or "short this".
+- Hit rates and past moves describe their sample; do not extend them into predictions.
+- Nothing in this connector trades — no order, close, transfer or withdrawal tool exists, by
+  design. If asked to act on the briefing, say so plainly; the decision and the trade stay with the
+  user.
+- Every number comes from a tool result made in this conversation; state the time of the calls so
+  the user knows how fresh the brief is, and never reuse figures from an earlier brief as if they
+  were current.
+
+## Examples
+
+```text
+Give me a crypto market briefing.
+Give me a crypto morning brief: what moved, where funding is stretched, and what the AI signals fired overnight.
+Just the headline: where are BTC, ETH and SOL, and how is the market positioned?
+Weekly recap of the crypto market.
+```
+
+## Limitations
+
+- Needs the hosted TraderSpy MCP server connected in the client (`https://mcp.traderspy.app/mcp`, Streamable HTTP), authorized with OAuth or a personal key from https://traderspy.app/mcp. A free TraderSpy account is enough. Without the server the skill has no data to work from.
+- Tool calls are metered per day: 300 on the free tier, 5,000 on premium.
+- Every tool is read-only. Nothing here places, closes or modifies an order, and there is no withdrawal or transfer tool.
+- The output is market data and analysis for the user's own research, not investment advice.
+- A full briefing uses six tool calls; the headline variant uses three.
+- The movers and stretched lists cover the most-traded pairs by 24h volume, not every listed coin.
+
+## Related Skills
+
+- `@traderspy-technical-analysis` - one coin in depth
+- `@traderspy-market-screener` - the full screener and backtests behind the movers list
+- `@traderspy-trading-signals` - one signal in detail
+- `@traderspy-smart-money` - who specifically is positioned how

package/bundled-skills/traderspy-market-screener/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: traderspy-market-screener
+description: "Scan the most-traded crypto futures pairs for up to 3 technical conditions in one TraderSpy call, compare coins, and backtest what followed a condition. Use for \"which coins are oversold\"."
+category: finance
+risk: safe
+source: "https://github.com/target1m/traderspy-mcp/tree/069aae5a84640d671f92705a2e3bc0b62efca1e0/skills/market-screener"
+source_repo: target1m/traderspy-mcp
+source_type: official
+date_added: "2026-09-25"
+author: target1m
+tags: [traderspy, crypto, screener, backtesting, mcp]
+tools: [claude, cursor, gemini]
+license: MIT
+license_source: "https://github.com/target1m/traderspy-mcp/blob/069aae5a84640d671f92705a2e3bc0b62efca1e0/LICENSE"
+---
+
+# TraderSpy Market Screener
+
+Two tools, one vocabulary. `screen_symbols` evaluates up to three AND-ed conditions across the
+most-traded pairs (or a list you give it) on one timeframe, in ONE quota unit. `backtest_condition`
+takes the same conditions, one symbol and one timeframe, and reports what price did after every
+past occurrence — with the unconditional baseline so the edge is separated from the tape's drift.
+
+Together they answer the two questions traders actually ask: "what fits this pattern right now?"
+and "has this pattern meant anything before?"
+
+## When to Use
+
+- Use when the user wants to find, filter, rank or compare several coins by technical conditions: "which coins are oversold on the 4h", "what is above its 200 EMA with rising volume", "show me Bollinger squeezes", "find me setups".
+- Use for side-by-side comparison tables such as "compare BTC, ETH and SOL".
+- Use when the user asks what happened after a condition in the past: "how did ETH do after RSI dropped below 30", "is a golden cross on BTC daily actually bullish".
+- Never answer these by calling `get_technical_indicators` coin by coin. For a deep read of one coin use `@traderspy-technical-analysis`.
+
+## The condition vocabulary
+
+A condition is `{ metric, op, value, period?, period2? }`. `op` is `lt` / `gt` (latest value) or
+`crossAbove` / `crossBelow` (a one-bar event: the previous bar was on the other side).
+
+| Metric | Default period | Unit / meaning |
+| --- | --- | --- |
+| `rsi` | 14 | 0–100 |
+| `stochastic` | 14, %D 3 | slow %K, 0–100 |
+| `cci` | 20 | Commodity Channel Index (±100 typical bands) |
+| `mfi` | 14 | 0–100, volume-weighted RSI |
+| `williamsR` | 14 | −100…0 (−80 oversold, −20 overbought) |
+| `adx` | 14 | trend strength; > 25 strong, < 20 absent |
+| `roc` | 12 | rate of change, % |
+| `macdHistogram` | 12, 26 (signal 9) | histogram in price units; `crossAbove 0` = bullish MACD cross |
+| `atrPct` | 14 | ATR as % of price — volatility |
+| `volumeRatio` | 20 | bar volume ÷ average of the previous N bars |
+| `bbPercentB` | 20 (2σ) | 0 = lower band, 1 = upper band; < 0 or > 1 = outside |
+| `bbWidthPct` | 20 | band width as % of the middle — small = squeeze |
+| `priceVsEma` | 50 | % distance of close from EMA(period); > 0 above |
+| `emaSpread` | 50, 200 | % of EMA(period) over EMA(period2); `crossAbove 0` = golden cross |
+| `supertrend` | 10 (×3) | +1 up-trend, −1 down-trend |
+| `changePct` | 24 | % change of close over the last N BARS (on 1h, 24 = one day) |
+| `price` | — | close |
+
+Periods clamp to 2–200. Conditions are AND-ed; there is no OR — run two scans for an OR and merge.
+Unknown metrics are rejected, so stick to the table (the full recipe list is in
+`references/condition-cookbook.md`).
+
+## Screening (`screen_symbols`)
+
+Arguments: `interval` (default 4h), `conditions` (≤ 3), `universe` (5–100 most-traded by 24h
+volume, default 50) OR `symbols` (≤ 100, explicit), `limit` (≤ 50 rows), `sortBy` volume /
+change24h / metric, `sortOrder`.
+
+Choose the timeframe from the user's horizon: intraday → `1h` (or `15m`), swing → `4h`, position →
+`1d`. Widen `universe` to 100 when the user wants small caps or the first scan matched little.
+
+Every result row carries the metric values under their labels (`values["RSI(14)"]`), plus `price`,
+`change24hPct`, `volume24hUsd`, `bias`, `trend`, `rsi14`, `adx14`, `atrPct`, `volumeRatio`,
+`squeeze`. When `matched` > `returned`, say so and offer to raise `limit`.
+
+**Comparison mode**: `symbols` with no `conditions` returns every listed symbol as a table — this is
+how you answer "compare BTC, ETH and SOL" or "how do my five coins look on the daily".
+
+**Translate intent to conditions before calling**, and say what you translated it to:
+
+- "oversold" → `rsi lt 30` (or 35 for a wider net); "deeply oversold" add `bbPercentB lt 0`
+- "overbought" → `rsi gt 70`
+- "in an uptrend" → `priceVsEma gt 0 period 200` + `supertrend gt 0`
+- "with rising volume" → `volumeRatio gt 1.5`
+- "squeezing" → `bbWidthPct lt 4` on 4h (lower on 1h) — then sort by metric ascending
+- "dumped today" → `changePct lt -5 period 24` on 1h, or `period 6` on 4h
+- "golden cross" → `emaSpread crossAbove 0 period 50 period2 200` on 1d
+
+## Backtesting (`backtest_condition`)
+
+Arguments: `symbol`, `interval`, `conditions` (same vocabulary), `horizons` in bars (≤ 4; defaults
+≈ 4h / 1d / 3d: 1h → [4, 24, 72], 4h → [6, 18, 42], 1d → [1, 3, 7]).
+
+The study runs over the whole stored tape — up to 1000 candles, so roughly 41 days on 1h, 166
+days on 4h, 3 years on 1d. An "occurrence" is the FIRST bar of each run where the condition held
+(ten consecutive oversold bars are one episode). For each horizon you get `samples`,
+`avgReturnPct`, `medianReturnPct`, `winRatePct`, `avgMaxUpPct` / `avgMaxDownPct` (average best and
+worst excursion, wick-accurate), `bestPct` / `worstPct`, `baselineAvgReturnPct` (every bar on the
+same tape) and `edgePct` = average − baseline. Also `activeNow`, `currentValues`, `lastOccurrence`,
+and `recent[]` with the last five episodes and their realised returns.
+
+How to read it honestly:
+
+- **Edge and sample size travel together.** `edgePct +1.8 on 27 samples` is a statement;
+  `+6 on 4 samples` is an anecdote, and the tool says so in `warnings`. Never quote the edge alone.
+- **Median vs average**: a positive average with a negative median means a few big winners carried
+  it. Say which.
+- **Excursions are the risk picture**: `avgMaxDownPct −5.1` on a "bullish" setup means the average
+  episode went 5% against you before the horizon ended. That belongs next to the win rate.
+- **Horizons that disagree** (positive at 1d, negative at 3d) usually mean a bounce that fades —
+  report the shape, do not pick the flattering horizon.
+- Recent episodes newer than a horizon are excluded from that horizon (`null` in `recent`), never
+  counted as zero.
+- Coverage limits what the study can see: 41 days of 1h data contains one market regime. A 1d
+  study is the only one that spans cycles.
+
+## Workflows
+
+**"What's oversold right now?"** → one `screen_symbols`. Present the table, then (optional, one more
+call) `backtest_condition` the same condition on the top match so the answer carries "and here is
+what that has meant on this coin before".
+
+**"Find me setups" / "watchlist"** → decide the archetype with the user in one line (mean-reversion
+vs trend-continuation vs breakout), run one scan per archetype (2–3 calls), and present each list
+with the conditions it was built from. Do not promise an outcome for any row.
+
+**"Is X actually bullish?"** → one `backtest_condition` on the coin and timeframe in question;
+if the user names no coin, BTC on 1d is the most meaningful default and say why (longest tape).
+
+**"Compare A, B, C"** → `screen_symbols` with `symbols`, no conditions, on the timeframe they care
+about. Add `get_derivatives` (technical-analysis) only if the question includes funding or
+positioning.
+
+## Presenting
+
+Screen: state the conditions in words and in the tool's labels, the timeframe, and the universe
+("50 most-traded pairs"), then one row per symbol:
+
+| Symbol | Price | 24h % | <metric labels…> | Bias | Trend | ADX | ATR% |
+
+Backtest: one header line (symbol, timeframe, condition, occurrences, coverage), a horizon table —
+
+| Horizon | Samples | Avg % | Median % | Win % | Avg best % | Avg worst % | Baseline % | Edge % |
+
+— then the last episodes and whether the condition is active now. Close with the sample-size
+caveat in your own words.
+
+## Conduct
+
+- A screen is a list of things that are true about the chart right now; a backtest is a sample of
+  what followed in the past. Neither is a recommendation. Present the evidence, note what would
+  invalidate the setup, and leave the trade — and the sizing — to the user.
+- Never turn "70% win rate on 12 samples" into a forecast; historical stats describe their sample.
+- Nothing in this connector trades — no order, close, transfer or withdrawal tool exists by design.
+  If asked to execute, say so plainly; the decision and the trade stay with the user.
+- Quote only what the tools returned; when a symbol is missing from the universe say it was not
+  scanned rather than implying it failed the filter.
+- When a specific trade idea is under discussion, end with one plain sentence that crypto
+  derivatives are high-risk and this is market information, not financial advice.
+
+## Examples
+
+```text
+Which coins are oversold on the 4h?
+Run the screener: RSI under 30 and ADX above 25 on the 4h, top 100 by volume.
+Compare BTC, ETH and SOL on the daily.
+Historically, what happened on SOLUSDT 4h after RSI crossed above 30? Compare it against the baseline over the same tape.
+```
+
+## Limitations
+
+- Needs the hosted TraderSpy MCP server connected in the client (`https://mcp.traderspy.app/mcp`, Streamable HTTP), authorized with OAuth or a personal key from https://traderspy.app/mcp. A free TraderSpy account is enough. Without the server the skill has no data to work from.
+- Tool calls are metered per day: 300 on the free tier, 5,000 on premium.
+- Every tool is read-only. Nothing here places, closes or modifies an order, and there is no withdrawal or transfer tool.
+- The output is market data and analysis for the user's own research, not investment advice.
+- Conditions are AND-ed, at most three per scan, from the fixed metric list above. An OR needs two scans.
+- A scan covers up to the 100 most-traded pairs or an explicit list of up to 100 symbols. A backtest sees at most 1000 stored candles, about 41 days on 1h.
+
+## Related Skills
+
+- `@traderspy-technical-analysis` (called `technical-analysis` in the text above, its upstream ID) - one coin in depth, and `get_derivatives` for funding and positioning
+- `@traderspy-market-briefing` - a market overview that includes a movers scan