MSCI Connector

View saved version →

---
name: benchmark
description: >-
  Use this skill for MSCI benchmark and market-reference analysis: index performance and levels, trailing/forward valuation multiples, sector/country/industry composition, factor scores, benchmark-relative weights, or return series for beta/CAPM. Trigger when the user asks how a market/region is doing, what it trades at, or where a portfolio is over/underweight, even if they do not explicitly say MSCI.
---

# Benchmark and market reference

Use the MSCI Index app to answer market and benchmark-relative questions with reproducible index identity, date, variant, and currency.

## Output

Lead with the requested number or comparison. Then give only the supporting detail needed to interpret it. Always identify the resolved index and state the as-of date, variant, and currency for performance/level analytics.

## Workflow

1. Resolve every requested index with `search_index_indexes`. Never guess an MSCI index code. For several independent indexes, resolve them in parallel when possible.
2. Discover the required datapoint or IMX metric with `search_index_datapoints`.
3. Prefer an `imx` result with `calculate_metrics` for comparable **equity index-level** returns, ratios, risk, volatility, factor exposure, and other supported analytics. For fixed income, hedged, or other non-equity indexes, use catalog datapoints instead.
4. For catalog datapoints, route from the returned flags: point-in-time with `supports_single_day=true` → `fetch_index_data`; history with `supports_range=true` → `fetch_index_timeseries`.
5. Read and obey `strict_gate`, `range_window`, and `constraints.notes` before fetching.
6. Use `daily` frequency for true maxima/minima or exact peak/trough dates. Use `monthly` for month-by-month trends or end-of-month datasets.

## Performance rules

- `GRTR` is gross total return, `NETR` net total return, `STRD` price/standard. Do not treat them as interchangeable.
- When the user does not specify a variant and asks generic performance, use gross total return only when compatible and clearly say so.
- For IMX calculations, honor the tool's anchor-date semantics. A start date is the base date, not necessarily the first observation.
- Relative IMX metrics require a benchmark. Without `benchmark_portfolio`, tracking error, information ratio, active return and active drawdown return null rather than erroring - the absolute metrics populate and the relative ones come back blank. Pass a benchmark whenever the question is relative, and never read a blank as zero active risk.
- Calendar-year return: prior year-end business-day anchor through the requested year-end; report the period total, not an annualized number.
- YTD: prior year-end business-day anchor through the requested as-of date.
- N-year return when the user says "annualized": use the N-year anchor and report the annualized result.
- If the user wants performance through the latest available date, prefer `fixed_start` over inventing an end date.

## Valuation and composition

Discover exact ids rather than composing them from memory. Typical search concepts include:

- trailing/forward P/E, P/B, ROE, payout ratio, dividend yield
- ratio/fundamental data date
- sector, country, and industry-group weights
- value, growth, quality, momentum, size, volatility, liquidity, and dividend-yield factor scores

When a ratio has a separate source/fundamental date, report it alongside the calculation date. Do not imply a stale fundamental observation is current merely because the index calculation date is recent.

For over/underweight analysis, show portfolio weight, benchmark weight, and the difference. If portfolio weights were supplied by the user, do not replace them with index constituent weights.

## Guardrails

- Never assume index composition from its name.
- Never substitute a non-MSCI benchmark silently.
- Index-level ratios are aggregates, not necessarily constituent medians. Use the formula/definition returned by discovery when interpretation matters.
- If history is unavailable from `fetch_index_timeseries`, say so; do not reconstruct it with repeated point-in-time calls.
- Preserve units exactly as returned.

View saved version →

---
name: climate
description: >-
  Use this skill for MSCI climate and regulatory sustainability metrics at index/security level, including Weighted Average Carbon Intensity (WACI), Implied Temperature Rise (ITR), carbon footprinting, Climate VaR physical/transition risk, SFDR principal adverse impact indicators, and EU Taxonomy alignment. Also use it to show how a climate or sustainability screen — PAB, CTB, SRI, or a low-carbon or screened variant — reshapes an index against its parent. Always pair metrics with available coverage fields.
---

# Climate and regulatory sustainability metrics

Report climate/sustainability metrics with coverage, units, date, and definition. Coverage is part of the result, not optional metadata.

## Output

For each metric show: metric name, value, unit, coverage, as-of/fetched date, and index/security identity. Spell out WACI on first use. Describe Climate VaR as modelled scenario impact, not realized loss.

## Workflow

1. Resolve the index with `search_index_indexes`, or the security with `search_index_securities` for security-level questions.
2. Discover the exact metric with `search_index_datapoints`; do not construct ids from naming patterns.
3. When discovery returns an equivalent `imx` metric for an **equity index-level** analytic, prefer `calculate_metrics`. Otherwise use the catalog datapoint route.
4. Discover and fetch the metric's `cov_*` or other documented coverage counterpart whenever available. Do not report a coverage-sensitive climate/SFDR metric without its coverage field if the catalog provides one.
5. For catalog data: `fetch_index_data` for point-in-time; `fetch_index_timeseries` for supported history.
6. Read `constraints.notes`, variant/currency requirements, and date availability. Sustainability data can be end-of-month; if a request snaps, report the effective fetched date.

## Interpretation

- State the exact currency/denominator basis for WACI or carbon metrics when returned by the catalog.
- Use the returned metric definition/formula to distinguish similarly named carbon metrics.
- EU Taxonomy nuclear and gas components should remain separate unless the returned methodology explicitly defines an aggregate the user requested.
- Climate VaR is model-based and scenario-dependent.
- Implied Temperature Rise is a forward-looking modelled alignment estimate in degrees Celsius, not a realised or measured temperature. Report the model basis and date returned by discovery, and never present ITR as a carbon intensity or convert between the two.

## Screened index versus parent

For "how does the PAB/CTB/SRI version differ from the parent", or "what does this screen change":

1. Resolve both the screened index and its parent with `search_index_indexes`. Do not infer the parent from the name — confirm it, or ask.
2. Report the same metric id, currency, and date for both, following the `compare` alignment contract.
3. Give the metric difference first, then the compositional reason where the data supports it — for example excluded constituents or changed sector weights from `composition`.
4. For the governing exclusion rule or threshold itself, hand off to `methodology`. Do not infer a screen's rule from the metric gap.

## Guardrails

- Never omit available coverage.
- Do not imply regulatory disclosure sign-off; the data supports disclosure but does not replace the user's reporting methodology and controls.
- Missing coverage/data is a limitation, not zero exposure.

View saved version →

---
name: compare
description: >-
  Use this skill to compare two to five MSCI indexes side by side on performance, risk, composition, valuation, or sustainability metrics. Trigger for "compare A and B", "A vs B", "what is the difference between these indexes", "how does A differ from B", "which of these is more concentrated", even if the user never says MSCI. The comparison must be aligned on one currency, one return variant, and one as-of date.
---

# Aligned index comparison

A comparison is only meaningful when every index is measured the same way. This skill exists to enforce that alignment; the underlying figures come from the same workflows used for a single index.

## Output

One row per index, one column per requested metric. Identify each index as `<name> (<msci_index_code>)`. State the alignment basis **once, above the table**: currency, return variant, and as-of date. Then give the differences that answer the question.

## Alignment contract

Before fetching, fix and then state:

1. **Currency** — one currency for all indexes.
2. **Variant** — one of `STRD` (price), `GRTR` (gross total return), `NETR` (net total return) for all indexes. These are materially different answers and are never interchangeable.
3. **As-of date** — one date, or one period with one anchor, for all indexes.

If the user specifies none of these, choose a defensible default, state it explicitly, and apply it uniformly.

## Workflow

1. Resolve every index with `search_index_indexes`, in parallel. Never guess a code.
   Pass all resolved codes in a **single** `fetch_index_data` call where the datapoints allow it. Verified live: multiple codes in one request return keyed per entity as `<name> (<code>)`, which keeps the comparison on one request, one date, and one basis by construction.
2. If any requested benchmark is not an MSCI index, say so and exclude it. Do not silently substitute a similar MSCI index.
3. Discover each requested metric once with `search_index_datapoints`, then apply the same id across all indexes so the columns are genuinely comparable.
4. Route by dimension, keeping the alignment contract intact:
   - performance, risk, valuation, factor scores → the `benchmark` workflow
   - constituents, weights, country/sector splits, concentration → the `composition` workflow
   - construction and review rules → the `methodology` workflow
   - climate and sustainability metrics with coverage → the `climate` workflow
5. Read `strict_gate` before fetching. If one index cannot be served in the chosen variant or currency, either move every index to the documented fallback id, or report that index as unalignable and exclude it from the compared columns. Never mix gates within one table.
6. Remember that end-of-month snapping applies to the whole request. If any datapoint snaps, every index in that request snaps with it. Report the requested and fetched dates.
7. For history, use `fetch_index_timeseries` over one shared date range at one frequency.

## Interpretation

- If one index is the parent of another, or one is a screened or capped version of the other, say so. That relationship usually explains most of the difference.
- IMI, Standard, Small Cap, and All Cap are different universes, not variants of one index.
- Differences in constituent count or country coverage often explain a return gap better than any single metric.
- Comparing an aggregate index-level ratio across indexes is valid only if the same definition was returned for each.

## Guardrails

- Never compare gross against net, or one currency against another, within a table.
- Never compare figures from different as-of dates without labelling every date in the row.
- Do not exceed five indexes without confirming scope; beyond that, ask which metrics matter.
- If a metric is unavailable for one index, leave the cell explicitly unavailable rather than substituting a near-equivalent id.
- A difference in a returned metric is not an explanation. If the user asks why, hand off to `benchmark` for drivers or `methodology` for the governing rule.

View saved version →

---
name: composition
description: >-
  Use this skill for what sits inside an MSCI index: constituents and holdings, constituent weights, top-N holdings, country/region/sector/industry breakdowns, constituent counts, index concentration, and whether a given security is a member of a named index. Trigger for "top 10 holdings", "sector breakdown", "country weights", "how many stocks are in it", "how much of X is Y", "which index holds this stock", even if the user never says MSCI.
---

# Index composition and constituents

Use the MSCI Index app to describe an index's internal structure at a stated date. Composition is a point-in-time snapshot: it answers what is in the index and at what weight, not how the index performed and not why the rule exists.

## Output

Lead with the requested rows or figure. Identify the index as `<name> (<msci_index_code>)` and state the fetched date. When a list is paginated, state how many rows are shown versus available. Never present a partial page as the full index.

## Workflow

1. Resolve the index with `search_index_indexes`. Never guess an MSCI index code. Resolve several independent indexes in parallel.
2. Discover the exact datapoints with `search_index_datapoints`. Do not compose ids from naming patterns. Typical search concepts:
   - constituents and constituent weights
   - constituent identifiers (ISIN, ticker, security code)
   - country, region, sector, and industry-group weights
   - number of securities / constituent count
   - adjusted and unadjusted market capitalisation
3. Prefer a **native breakdown datapoint** when discovery returns one. Sector, country, and industry-group weights are published, not derived — expect families such as `equity_index.sector_weight.*` (sector name, GICS closing weight, number of securities), `equity_index.country_weight.*`, and `equity_index.industry_group_weight.*`. Confirm the exact ids through discovery. Only aggregate constituent rows client-side when the catalog has no published breakdown, and say the figure was derived by aggregation.
4. These breakdowns are **list-cardinality but range-capable**. They paginate under `fetch_index_data`, and `fetch_index_timeseries` does serve them, returning `list_tables`. Respect the returned `range_window`: daily frequency is capped at roughly 30 days, so use `frequency=monthly` for longer histories rather than looping point-in-time calls.
5. Route on the returned flags: `supports_single_day=true` → `fetch_index_data`; `supports_range=true` with a date range → `fetch_index_timeseries`.
6. For top/bottom holdings, pass `order_by` (typically `closing_weight`) with `order_direction`, plus `page` and `page_size`. Do not sort a single page client-side and call it the top N of the index.
7. When requesting parallel list datapoints from the same dataset, keep rows aligned by the shared `msci_security_code` so weights stay paired with their own identifiers.
8. Read `strict_gate`, `range_window`, and `constraints.notes` before fetching.

## Membership questions

For "which index holds this security" or "is this stock in the index":

1. Resolve the security with `search_index_securities`. Do not infer a country filter from suffixes such as `(US)`, `ADR`, `CDI`, or `ADS`.
2. For a **named** index, confirm membership from that index's constituent list or from the documented membership/eligibility flag, and state which basis was used.
3. For an **open-ended** "which indexes hold this", there is no exhaustive reverse lookup across every MSCI index. There is a **bounded** one: the `security.index_inclusion_monitor.weight_in_*` family covers the major standard families (World, ACWI, ACWI IMI, EM, EM IMI, World IMI, EM Small Cap and siblings) and returns a per-family weight for a resolved security code. Use it for the major families, then say plainly that the answer covers those families and the indexes checked, not every MSCI index.
4. Inclusion-monitor data is published only for the latest applicable monitor (T+6). A requested date is pinned to that monitor date and the response says so — report the pinned date, not the date you asked for. Any value from this family carries a mandatory disclaimer in `constraints.notes`; reproduce it verbatim.

## Concentration

- Derive top-N concentration from returned weights, state N, and state the date.
- Say whether the weights are closing weights or another documented basis.
- Do not describe concentration as a risk measure. It is a weight statistic.

## Interpretation

- Never assume composition from an index name. An index containing "World" or "Asia" does not imply a country list.
- Index-level aggregates are not constituent medians.
- Weights are point-in-time and move with prices, corporate events, and reviews.
- Preserve units exactly as returned; if market cap arrives in USD millions, label it or convert with an explicit label.

## Handoff

- Performance, returns, valuation multiples, and factor scores → `benchmark`.
- Why a constituent qualifies, or the rule behind a weight cap → `methodology`.
- What changed at a review, or a proforma constituent list → `index-changes`.
- Comparing composition across several indexes → `compare`.

## Guardrails

- Never double-convert a weight. Check the datapoint description for the decimal-versus-percentage statement before formatting, and align with `benchmark`: weights format as percentages unless the description states the value is already a decimal fraction.
- Never guess an index code, a datapoint id, or a constituent list.
- Do not claim a complete constituent list when only one page was fetched, or when entitlements may have filtered the result.
- If a requested date snaps, report both the requested and fetched date.
- Absence of a security from a returned page is not proof it is not in the index.

View saved version →

---
name: dashboard-changes
description: >-
  Use this skill to build a live, MSCI-branded HTML dashboard summarizing an MSCI index's last N index reviews (rebalances) via the IndexAI Insights MCP: constituent counts before/after, additions, deletions, FIF changes, official index turnover, addition/deletion turnover, and significant constituent weight changes. Trigger for "last N reviews", "what changed at rebalance", "index turnover", "additions and deletions", "which stocks were added/removed", even if the user never says MSCI. This is a read-only historical review SUMMARY, not a proforma trade/order list. Produces a rendered, refreshable .html artifact via the bundled assemble.py — never a text-only answer.
---

# Index Changes Dashboard

Build a self-contained, MSCI-branded HTML dashboard of an index's last *N* reviews — a review-summary of read-only facts + simple arithmetic, explicitly NOT a proforma trade/order list or an estimate of post-event weights. See `references/recipes.md` §4 and `references/metric-audit.md` §4 for the full deterministic build and validation rules — follow that build **exactly and in order**; this is the most procedural of the seven dashboards.

## Output

KPI row (index, reviews analyzed, last review effective date, latest turnover) → Review summary table (one row per review: effective date, N pre/post, additions, deletions, index turnover %, addition/deletion TO %, FIF changes) → per-review significant weight-changes tab (cutoff default 1pp, adjustable, expandable to the full list) → index information table. Present with `present_files`, stating index, N, currency/variant used for turnover.

## Workflow

1. Resolve the index code via `search_index_indexes` — never hardcode a code.
2. Resolve *N* review effective dates recursively: `equity_index.master_description.last_rebalancing_date` at the latest resolved business date → R1; repeat at `date = R1 − 1 business day` → R2; continue until *N* dates are collected.
3. Per effective date T (T₋₁ = the business day before T), make these as **separate** `fetch_index_data` calls: PRE composition at T₋₁ (`closing_weight`, `identifiers.security_name`, `description.msci_security_code`, `page_size:2000`) plus `nb_of_securities` at T₋₁ = N(Pre-review); REVIEW changes at T with `rebalance_target:"previous"` (`review_change_counts.*`, `additions.msci_security_code`, `deletions.msci_security_code`, `proforma_constituents.initial_weight`); POST count `nb_of_securities` at T = N(Post-review); a **second** call resolving added/deleted names via `security.description.security_name` (never mix index and security codes in one call); official turnover via `fetch_index_timeseries(..., equity_index.performance.total_index_turnover)` at start=end=T.
4. Compute: normalize weights (PRE is percent as-is, PROFORMA `initial_weight` is decimal → ×100); assert N(Post-review) = N(Pre-review) − Deletions + Additions (flag if not); weight-change table over the union of PRE/POST securities (`Δw = w_post − w_pre`, missing side = 0); Addition TO% = Σ post weight over additions; Deletion TO% = Σ pre weight over deletions; Index turnover% = official `total_index_turnover` × 100 (never recompute — the `Σ|Δw|/2` proxy is a cross-check only); significant weight changes = union rows with `|Δw| ≥` the cutoff (default 1pp), sorted by `|Δw|` desc, tagged added/deleted/reweighted.
5. Validate every build: assert `rebalanceDate == T` on each review-change call; assert the N(Post) identity per review; pre/post weights each sum to ≈100 (±1); one-way turnover ≥ Addition TO — flag any violation on the dashboard face.
6. Add one grounded interpretive callout per major section (standing rule 10).

## Labels & conventions

Use "Effective date" for a review's date and "Last review effective date" for the most recent one — do not mix in other phrasing. Use Pre-review/Post-review (not MSCI's own report labels "Current"/"Proforma", which are announcement-time labels that mislead in a historical view — note the mapping if asked). State plainly that the shown turnover is MSCI's official **one-way** figure; the printed review report shows **two-way** (= 2× one-way); double it if the user wants that figure, or show both.

## Interpretation

- Reason for deletion (security-level, from IRCR content) is **deferred** — not captured by IndexAI Insights today. Show the column marked "coming with the IRCR dataset"; never fabricate a reason.
- FIF-changes count is kept but its usefulness is an open question — surface it, be ready to see it dropped later.
- Historical reviews are immutable; on refresh, only re-check whether a *newer* review has occurred (via `last_rebalancing_date`) and banner if so — do not re-pull all per-review data on every refresh.

## Handoff

- What's currently inside the index (holdings, weights) as of today → `dashboard-composition`.
- Returns or risk analytics → `dashboard-performance-risk`.
- Why a specific addition/deletion happened on eligibility grounds → `dashboard-methodology`.
- Comparing review activity across indexes → `dashboard-comparator`.

## Guardrails

- This is a review SUMMARY, never a proforma trade/order list — estimated post-event weights and trade lists are out of scope regardless of how the user phrases the ask.
- Never recompute the N(Post) identity or index turnover from your own arithmetic when an official field exists — use the official field, cross-check only.
- Every dashboard must build through `assets/assemble.py`. This package bundles everything needed to do so: `assets/{dashboard-shell.html, assemble.py, disclaimer-footer.html, disclaimer-notice.txt, refresh-snippet.html, logos/}` and `references/{brand.md, recipes.md, metric-audit.md, mcp-queries.md}`. Full build mechanics, the shared shell/brand/disclaimer stack, and the as-of/range control are documented in `references/recipes.md`'s "Shared conventions" section (self-contained in this package) — apply them exactly as written; do not re-derive or simplify them.

Referenced files: 11

View saved version →

---
name: dashboard-climate
description: >-
  Use this skill to build a live, MSCI-branded HTML dashboard of an MSCI index's sustainability and climate metrics via the IndexAI Insights MCP: WACI (weighted average carbon intensity), Implied Temperature Rise, Climate VaR, Low Carbon Transition score, and EU BMR alignment (climate-aligned flag, investable-universe overlap, sustainable-investment screening weight) — framed as index vs parent wherever a parent variant is resolved. Trigger for "carbon intensity", "WACI", "implied temperature rise", "climate VaR", "EU BMR", "Paris aligned", "how does this ESG index differ from its parent", even if the user never says MSCI. Produces a rendered, refreshable .html artifact via the bundled assemble.py — never a text-only answer.
---

# Sustainability & Climate Index Dashboard

Build a self-contained, MSCI-branded HTML dashboard showing how climate/ESG index construction reshapes an index relative to its parent. See `references/recipes.md` §3 and `references/metric-audit.md` §3 for the exact field list; these are EOM-published values (2nd business day snap) — never intraday-refreshed.

## Output

KPI row (WACI, ITR, aggregate Climate VaR) → index-vs-parent comparison table (when a parent is resolved) → EU BMR alignment panel → Low Carbon Transition score (native IMX chart callout, not a plain scalar) → coverage footnotes under every metric with a paired `cov_*` field → standard disclaimer footer. Present with `present_files`, stating index(es), as-of month, and that this is an EOM snapshot.

## Workflow

1. Resolve the index code, and its parent/standard-index variant if the user wants an explicit vs-parent view, via `search_index_indexes` — confirm with the user if ambiguous.
2. **In-shell (MCP-direct), pulled for each index code separately** — this pairing matters: pull `equity_index.esg_metrics_additional.wtd_avg_carbon_intensity_by_sales_scope_1_2_3` + its coverage field for both the index and the comparison index individually. The FIMD-namespace `waci_index`/`waci_parent` pair only applies to factor indexes in a vetted FIMD list and returns null for a standard index-vs-parent ask — do not use it for that. Also pull `equity_index.esg_metrics.implied_temperature_rise` + `cov_implied_temperature_rise`, `equity_index.esg_metrics.total_var` + its physical/policy coverage fields, and the EU BMR fields (`climate_aligned`, `benchmark_investable_overlap`, `eu_sust_invst_scrn_wt_sm`).
3. **Native IMX chart:** the index-level Low Carbon Transition score (`index_esg_low_carbon_transition_score_last`) has no plain catalog scalar — call `calculate_metrics` and present it as a native interactive chart, the same handling as risk analytics in `dashboard-performance-risk`, never re-plotted numbers.
4. Render every in-shell metric **paired with its coverage field** where one exists (standing rule 8) — a headline climate number with low coverage is misleading shown alone.
5. Validate (`references/metric-audit.md` § Validation): WACI/ITR/Climate VaR non-negative where the field's definition requires it; every `cov_*`-paired value shows its coverage; ITR is never converted to/from a carbon-intensity number.
6. Add one grounded interpretive callout per major section (standing rule 10) — e.g. quantify how much a Paris-aligned screen cuts carbon intensity or brings modelled temperature alignment under the Paris ceiling, citing the exact numbers shown.

## Interpretation

- ITR is a forward-looking modelled alignment estimate in °C — never state or imply it converts to/from a carbon-intensity figure.
- If the connector doesn't return a parent-index field for a given index, drop the vs-parent framing rather than fabricating a comparison — show the single-index view only.
- A null EU BMR overlap for an index means it isn't a regulated EU BMR disclosure benchmark — that's the correct answer, not missing data; say so rather than leaving a blank cell unexplained.

## Handoff

- Composition, holdings, or sector/country weights → `dashboard-composition`.
- Returns, factor tilts, or risk analytics → `dashboard-performance-risk`.
- What changed at the last N reviews → `dashboard-changes`.
- Eligibility or the rule behind a construction choice → `dashboard-methodology`.
- Comparing climate metrics across more than 2 indexes at once → `dashboard-comparator`.

## Guardrails

- Do not compute WACI, ITR, or Climate VaR yourself from underlying company data — these are MCP-direct/EOM-published values only.
- Every dashboard must build through `assets/assemble.py`. This package bundles everything needed to do so: `assets/{dashboard-shell.html, assemble.py, disclaimer-footer.html, disclaimer-notice.txt, refresh-snippet.html, logos/}` and `references/{brand.md, recipes.md, metric-audit.md, mcp-queries.md}`. Full build mechanics, the shared shell/brand/disclaimer stack, and the as-of/range control are documented in `references/recipes.md`'s "Shared conventions" section (self-contained in this package) — apply them exactly as written; do not re-derive or simplify them.

Referenced files: 11

View saved version →

---
name: dashboard-comparator
description: >-
  Use this skill to build a live, MSCI-branded HTML dashboard aligning 2-5 MSCI indexes side by side on composition and/or performance/risk via the IndexAI Insights MCP, all on one shared currency, variant and as-of date. Trigger for "compare these indexes", "side by side", "which of these has more X", when 3 or more indexes are named, or when 2 indexes are named alongside an explicit request for an aligned comparison table rather than an index-vs-parent framing, even if the user never says MSCI. Produces a rendered, refreshable .html artifact via the bundled assemble.py — never a text-only answer. This dashboard owns no new metrics; it is an alignment contract over composition and performance/risk.
---

# Index Comparator Dashboard

Build a self-contained, MSCI-branded HTML dashboard comparing 2-5 indexes side by side. This is a **compare mode**, not a new metric set — it reuses the composition pulls (`dashboard-composition`) and the performance/risk pulls (`dashboard-performance-risk`), rendered as aligned columns rather than a single dashboard's own view. If the user's question is really about one index, or a single index vs its parent variant, route to the single-index dashboards instead of forcing a one/two-index "comparison." See `references/recipes.md` §6 and `references/metric-audit.md` §6.

## Output

Header strip confirming the shared currency/variant/as-of date across all indexes → composition comparison table (weights/sector/country side by side) → performance comparison table (multi-period returns side by side) → risk analytics panel (native IMX charts, one per index or one relative-to-baseline) → standard disclaimer footer. Present with `present_files`, listing every index name/code included.

## Workflow

1. Resolve all 2-5 index codes via `search_index_indexes` — never guess.
2. **Mandatory alignment contract** — confirm with the user if unspecified rather than guessing per index: one currency, one variant (STRD/GRTR/NETR), one as-of date (and, for performance, one range) across every selected index. A silent mismatch (one index in NETR, another in GRTR) produces a wrong comparison, not just an incomplete one.
3. For composition: reuse the constituents/sector/country pulls, once per index, at the shared date.
4. For performance/risk: reuse the in-shell returns/factor-tilt pulls per index; for risk analytics, call `calculate_metrics` per index (or with one index as `benchmark_portfolio` for an explicit active view against a chosen baseline).
5. Render side by side — columns per index, never a blended average — so a reader sees each index's own numbers next to the others'. A null value for one index/period is shown "n/a" in that index's column — never drop the index from the table because one field is missing.
6. Add one grounded interpretive callout per major section (standing rule 10).

## Interpretation

- This dashboard is a compare mode over the other analyst dashboards, not an independent data source — every number in it must trace back to the same fields those dashboards use.
- Never let one index's missing field cause the whole comparison row to be dropped; show "n/a" and keep every other index's data intact.

## Handoff

- A single index's own detail, in full → `dashboard-composition`.
- A single index's own performance/risk detail, in full → `dashboard-performance-risk`.
- Climate/ESG comparison specifically (index vs parent framing) → `dashboard-climate`.
- What changed at a review, for one index → `dashboard-changes`.
- Eligibility or methodology rules → `dashboard-methodology`.

## Guardrails

- Confirm the alignment contract (currency/variant/date) before pulling any data, not after rendering a mismatched table.
- Every dashboard must build through `assets/assemble.py`. This package bundles everything needed to do so: `assets/{dashboard-shell.html, assemble.py, disclaimer-footer.html, disclaimer-notice.txt, refresh-snippet.html, logos/}` and `references/{brand.md, recipes.md, metric-audit.md, mcp-queries.md}`. Full build mechanics, the shared shell/brand/disclaimer stack, and the as-of/range control are documented in `references/recipes.md`'s "Shared conventions" section (self-contained in this package) — apply them exactly as written; do not re-derive or simplify them.

Referenced files: 11

View saved version →

---
name: dashboard-composition
description: >-
  Use this skill to build a live, MSCI-branded HTML dashboard showing what sits inside one or more MSCI indexes via the IndexAI Insights MCP: constituents and top holdings, constituent weights, country/region/sector breakdowns, concentration, and — on a second tab — a single security's identifiers, weight, FIF/NOS and whether it's a member of each selected index. Trigger for "top 10 holdings", "sector breakdown", "country weights", "how many stocks are in it", "which index holds this stock", "compare index composition", even if the user never says MSCI. Produces a rendered, refreshable .html artifact via the bundled assemble.py — never a text-only answer.
---

# Index Composition Dashboard

Build a self-contained, MSCI-branded HTML dashboard describing one or more indexes' internal structure at a stated date, plus (on a second tab) one security's cross-index membership. This is a dashboard-building skill: every response ends in a rendered `.html` artifact assembled through `assets/assemble.py`, never hand-authored HTML, and never a prose-only answer. Composition is a point-in-time snapshot — it answers what is in the index and at what weight, not how it performed (→ `dashboard-performance-risk`) and not why a rule exists (→ `dashboard-methodology`).

## Output

One dashboard, two top-level tabs — an **Index** tab and a **Security** tab — sharing one resolved as-of date and the same selected set of indexes. Identify each index as `<name> (<msci_index_code>)` and state the fetched date in the header. Present the file with `present_files`; state the dashboard type, index name(s)/code(s), currency, variant, as-of date/range, and that the control re-pulls live in claude.ai. Full field list and exact units: `references/metric-audit.md` §1. Full layout/build detail: `references/recipes.md` §1.

## Workflow

1. Resolve every index with `search_index_indexes` — never guess an MSCI index code; confirm name + code (and variant/currency) when more than one plausible match returns. For the Security tab, resolve the security with standard MSCI search (case-insensitive token/substring — "space" must return every match, not one row; no hard cap).
2. Resolve the as-of business date from the echoed `fetched_date` of a cheap probe call — never today's calendar date (`references/mcp-queries.md` §0b).
3. Pull, once per index: multi-period returns (`equity_index.performance.period_returns.{period,returns}`); constituents + identifiers + sector + country weights (`equity_index.constituents.closing_weight`, `.identifiers.{security_name,isin,RIC,ISO_country_symbol}`, `equity_index.sector_weight.{sector_name,gics_closing_weight}`, `equity_index.country_weight.{country_name,cty_closing_weight}`, large `page_size` — a small page truncates the breakdown too); `equity_index.description.nb_of_securities`. This one constituents pull feeds both tabs.
4. Add the in-scope factsheet extension (valuation/fundamentals, factor, ESG/climate) **only where `search_index_datapoints` confirms the catalog exposes it** for this index — omit anything not exposed, never compute a proxy. Methodology-sensitive risk metrics stay out of this tab (→ `dashboard-performance-risk`).
5. Build the artifact via `assets/assemble.py` (see this package's README section below) — never hand-author the header, footer, brand CSS or disclaimers; that chrome is shared and inherited automatically.
6. Validate before rendering (`references/metric-audit.md` § Validation): weight in [0,100]; top weight flagged if >~40%; sector Σ≈100 (±1); country Σ≈100 (±1.5); null return periods show "n/a", never zero.
7. Add one grounded interpretive callout per major section (standing rule 10) — every claim must trace to a value shown elsewhere on the same dashboard.

## Index tab

Performance (KPI cards YTD/1Y/3Y CAGR/5Y CAGR + full multi-period table + historical level chart) → Rankings (YTD/1Y, indexes null for a period omitted, not ranked zero) → Weights & concentration (top-10 constituents, sector weights, the **full** country breakdown sorted desc and scrollable — never a hard top-12 cap — cumulative top-10 weight, and a one-line concentration read; never compute effective-number-of-stocks, it isn't an MCP field) → in-scope factsheet metrics, each labelled with its `datapoint_id`.

## Security tab

Security header (name, ISIN, RIC, country, sector, MSCI security code) → detail KPIs (weight, FIF to 3dp, NOS where present, each labelled with source + as-of date) → cross-index membership table: Index · In index? · Weight (%) · Sector · Country, right-aligned numeric columns, tabular numerals, **"not a constituent" shown, never a dropped row** → licensed/thematic fields only when the connector actually returns them for this user, hidden entirely otherwise.

## Interpretation

- Never assume composition from an index's name — "World" or "Asia" in the name doesn't imply a specific country list; resolve and show the real breakdown.
- Weights are point-in-time and move with prices, corporate events, and reviews.
- A flat "not a constituent" result is a completely correct answer when the two selected indexes have disjoint country universes (e.g. World vs EM never overlap) — but it's the least informative pairing for demonstrating the Security tab's value, since no security could ever show a meaningful two-sided weight comparison there. When the goal is to show *how much a position's weight shifts* between two benchmarks (not just whether it's included), pick indexes that genuinely overlap (e.g. a global index and a regional/country subset of it).
- "Search which of ALL standard + custom indexes a security is in, over a date range" is a **deferred capability**, not supported by current IndexAI Insights (needs security↔index mapping) — say it's planned, never brute-force it by scanning indexes. The supported view is membership across the selected indexes only.

## Handoff

- Returns, factor tilts, or risk analytics for an index → `dashboard-performance-risk`.
- Carbon intensity, temperature alignment, or climate/ESG index-vs-parent → `dashboard-climate`.
- What changed at the last N reviews (additions/deletions/turnover) → `dashboard-changes`.
- Why a security is/isn't eligible, or the rule behind a weight cap → `dashboard-methodology`.
- Comparing composition across more than 2 indexes at once, all aligned → `dashboard-comparator`.
- A factor index's methodology input (Quality/Momentum/Dividend score beside weight) → `dashboard-fimd`.

## Guardrails

- Facts only — MCP-direct fields + simple arithmetic (sum, count, sort, min/max, average, %, % change, top-minus-bottom spread). Nothing else, no forward estimates, no dollar exposure unless AUM is supplied.
- When required inputs (which indexes, which security) are missing, ask the user to clarify before building rather than guessing.
- Render the full scope every time — a table the recipe says shows everything must actually show everything (page/scroll, don't silently sample).
- Every dashboard must build through `assets/assemble.py`. This package bundles everything needed to do so: `assets/{dashboard-shell.html, assemble.py, disclaimer-footer.html, disclaimer-notice.txt, refresh-snippet.html, logos/}` and `references/{brand.md, recipes.md, metric-audit.md, mcp-queries.md}`. Full build mechanics, the shared shell/brand/disclaimer stack, and the as-of/range control are documented in `references/recipes.md`'s "Shared conventions" section (self-contained in this package) — apply them exactly as written; do not re-derive or simplify them.

Referenced files: 11

View saved version →

---
name: dashboard-fimd
description: >-
  Use this skill (licensed) to build a live, MSCI-branded HTML dashboard showing a factor index's methodology input via the IndexAI Insights MCP — the composite factor score (Quality/Momentum/Dividend) that drives selection and weighting, shown beside each holding's actual index weight. Trigger for "factor score behind the index", "FIMD", "quality score vs weight", "why is this holding weighted the way it is", "factor methodology input", for an index in the vetted FIMD list, even if the user never says MSCI. Produces a rendered .html artifact via the bundled assemble.py — renders only when the connector actually returns FIMD data for the entitled user, never fabricated.
---

# Factor Index Methodology Data (FIMD) Dashboard

Build a self-contained, MSCI-branded HTML dashboard showing, for a factor index's holdings, the **factor score** that the methodology uses to select and weight names, **beside each holding's index weight** — so a reader sees *why the weight is what it is*. FIMD is built on the `equity.sustainability_factor.input.security.*` namespace (per-security methodology inputs) and is **separately licensed** — render only when the connector actually returns data for the live probe; never fabricate values. See `references/recipes.md` §7 and `references/metric-audit.md` §7 for the exact mechanics.

## Output

Title the dashboard in plain words with the acronym in parentheses, e.g. *"Factor Index Methodology Data — the factor score behind index selection & weighting (FIMD)."* Layout, in order: availability strip → "rules that matter" panel (2-3 cited rules) → KPI row (parent-universe size, constituent count, factor-score headline, largest-holding weight) → "methodology inputs shown" chips → the Index holdings table (exactly four columns: Security · MSCI code · Weight % · Factor, factor column highlighted, sorted by weight desc, showing **every** constituent, not a top-N sample except the stated top-100 fallback for an unusually large parent) → a grounded commentary callout → index info (name+code, view, resolved calc date, rebalance effective date).

## Workflow

1. **Eligibility — code list + live probe.** The index must be in `data/fimd-indexes.txt` (the vetted FIMD eligibility list, 289 codes); if not, route to `dashboard-composition` or `dashboard-changes`. Then live-probe `fetch_index_data(codes:["<code>"], datapoints:["equity.sustainability_factor.input.security.msci_security_code"], date:"<as-of>")` — rows in `list_tables` (`pagination.total_rows`>0) means eligible; empty/error means tell the user it isn't available for that index/date (and, in Rebalance view, that Month-end may have data).
2. **Pick the view (default = Rebalance).** Control is a Month-end / Rebalance (T-9) toggle + a month picker (no range selector). Rebalance (T-9) resolves `next_rebalancing_date` if non-null else `last_rebalancing_date`, passes it as `date`, and the server resolves the T-9 pro-forma calc date; if the probe returns "No Data" (upcoming review not yet published), say so and offer Month-end. Month-end uses bare ids and auto-snaps to the 2nd business day.
3. **Which factor to show (methodology-driven, never assumed).** Read the methodology stack (`search_index_methodology_stack`) to confirm the composite factor the index uses. Infer the family from the index name as a starting point — Quality → `quality_score`; Momentum → `momentum_score`/`composite_momentum_score`; High Dividend Yield → `composite_dividend_score` — then discover the exact id with `search_index_datapoints` at build time and confirm it populates. Label the Factor column for the family (e.g. "Quality Score"). Never surface the descriptor inputs (ROE, Debt/Equity, Earnings Variability, momentum z-scores) as table columns — the single composite score sits beside weight; descriptors belong only in the rules panel.
4. **Build the holdings×weight×factor join.** Pull the index's constituents by weight (`equity_index.constituents.closing_weight` + `identifiers.security_name` + `description.msci_security_code`, `order_by:closing_weight desc`, `page_size:2000`); pull the FIMD factor map for the parent universe (`msci_security_code` + the single composite score id, matching bare/`.rebalancing` form); **join by `msci_security_code`** client-side; render descending by weight. The methodology input is index-scoped — it cannot be fetched by security code (returns "No Data available for the given input index …") — so the join must read the index map, a single call at load.
5. Render **all** constituents for a small-to-medium parent (standing rule 9 — a table claiming to show holdings in full must actually contain all of them); only for an unusually large parent, default to the top 100 by weight, page the rest, and say so on the dashboard face.
6. Show 2-3 cited "rules that matter" from the methodology stack (e.g. for Quality: score = average z of ROE, Debt/Equity, Earnings Variability, winsorized 5th/95th pct; Debt/Equity and Earnings Variability enter with a negative z; selection ranks the parent by score and weights market-cap-based among the selected names).
7. Add a grounded commentary callout (standing rule 10) — e.g. whether the highest-weighted holding also carries a high factor score, or whether weight and score diverge.
8. Validate (`references/metric-audit.md` § Validation): availability probe returns rows before rendering; weights sum to a plausible total (≤100); the composite score is within a plausible range (z-composite roughly [−5,5], flag outside); Rebalance-view calc date matches the server T-9 (else "No Data" → offer Month-end); Month-end `note` confirms the 2nd-business-day snap.

## Interpretation

- A blank Factor cell for a holding means unrated/not-mapped — show "n/a", never zero-fill.
- Weight is market-cap-based **among the factor-selected names**, not the whole parent universe — note this so weight-vs-score reads correctly.

## Handoff

- General composition/holdings of the same index without the factor join → `dashboard-composition`.
- Returns or risk analytics for the same index → `dashboard-performance-risk`.
- What changed at the index's last rebalance → `dashboard-changes`.
- The eligibility rule behind why a name is/isn't in the factor-selected set → `dashboard-methodology`.

## Guardrails

- Licensed data — render only when the connector actually returns it for this entitled user; never fabricate a factor score or weight.
- Every dashboard must build through `assets/assemble.py`. This package bundles everything needed to do so: `assets/{dashboard-shell.html, assemble.py, disclaimer-footer.html, disclaimer-notice.txt, refresh-snippet.html, logos/}`, `data/fimd-indexes.txt` (the eligibility list), and `references/{brand.md, recipes.md, metric-audit.md, mcp-queries.md}`. Full build mechanics, the shared shell/brand/disclaimer stack, and the as-of/range control are documented in `references/recipes.md`'s "Shared conventions" section (self-contained in this package) — apply them exactly as written; do not re-derive or simplify them.

Referenced files: 12

View saved version →

---
name: dashboard-methodology
description: >-
  Use this skill to build a live, MSCI-branded HTML dashboard combining a live eligibility screen for a named security against a reference MSCI index/Inclusion Module with 2-3 cited construction rules (capping, buffer zones, country classification) pulled from the actual methodology document via the IndexAI Insights MCP — never from memory. Trigger for "why isn't this stock in the index", "is this eligible for MSCI EM", "capping rule", "buffer zone", "country classification rule", "what would it take to be included", even if the user never says MSCI. Produces a rendered .html artifact via the bundled assemble.py, plus the mandatory Index Inclusion Module disclaimer — never a text-only answer, never a from-memory methodology claim.
---

# Index Methodology Dashboard

Build a self-contained, MSCI-branded HTML dashboard combining a live quantitative eligibility screen with cited rule text — two sources that answer two different questions and must never be blended: the screen answers "does it pass today's checks", the cited methodology text answers "why does the rule exist and where do capping/buffer bands kick in." See `references/recipes.md` §5 and `references/metric-audit.md` §5 for the exact fields and the mandatory disclaimer text.

## Output

Eligibility strip (pass/fail + every component flag, colour-coded) → "why" panel narrating each failing flag with its own input values/cutoffs → "rules that matter" panel (2-3 cited capping/buffer/country-classification rules, methodology name shown) → buffer/migration caveat stated plainly → standard disclaimer footer **plus** the Index Inclusion Module disclaimer block. If the user asks a pure eligibility question, you may omit the rules panel; if a pure rules question with no security, omit the eligibility strip.

## Workflow

1. Resolve the security's MSCI code via `search_index_securities`; resolve the reference index/Inclusion Module entity (e.g. `IIM GLOBAL`, `IIM AMERICAS`, `IIM EMEA`, `IIM APAC`) with an optional country filter.
2. Pull `security.index_inclusion_monitor.index_eligible_fg` and **every** component flag (`size_segment_fg`, `minimum_free_float_market_capitalization_fg`, `minimum_foreign_inclusion_factor_flag`, `foreign_room_flag`, `atvr_12m_fg`, `atvr_3m_fg`, `fot_12m_fg`, `fot_3m_fg`, `china_a_share_with_connect_line`).
3. If `index_eligible_fg` is FALSE or blank, read every component flag and attribute the result to **all** flags that fail or are "Not Met" — never just the first one found. Never recompute the roll-up yourself; read the field directly (FALSE beats blank in its own precedence logic, which is easy to get subtly wrong by re-deriving).
4. For a rules question, call `search_index_methodology_stack(indexCode, query)` and cite the methodology name + returned snippet. If nothing returns, prefix the answer with the tool's own mandated "⚠️ Note: ... not the official MSCI methodology document" fallback — never answer from training data unlabeled.
5. Attach the mandatory Index Inclusion Module disclaimer verbatim via `assemble()`'s `extra_disclaimers` parameter whenever step 2/3 data is shown — this is carried in the datapoint's own `constraints.notes`, not injected automatically by the fetch tool, and must never be paraphrased, trimmed, or merged with the standard footer.
6. Add one grounded interpretive callout per major section (standing rule 10).

## Caveats to always state alongside the eligibility flag

- Size-segment cutoffs shown are interim daily-maintenance cutoffs, not the final Index Review cutoffs.
- Free float, foreign room, and liquidity reflect the latest data as of the prior month-end, not the actual review price-cutoff date.
- **Buffer/migration rules (size-migration 2/3 and 1.5x, Small Cap entry) are NOT reflected in this snapshot** — those live only in the cited methodology text, never in `index_eligible_fg`.
- AUM figures elsewhere in the Inclusion Module are indicative only, not actual fund flows.

## Interpretation

- `index_eligible_fg` is a reference indicator, not a final index-inclusion decision.
- Never conflate the eligibility screen's pass/fail with the methodology text's explanation — state both, in their own panels, never merged into one claim.

## Handoff

- What's currently inside the index (holdings, weights) → `dashboard-composition`.
- Returns or risk analytics → `dashboard-performance-risk`.
- What changed at a past review (the actual addition/deletion event) → `dashboard-changes`.
- Comparing eligibility context across indexes → `dashboard-comparator`.

## Guardrails

- Never cite a rule from memory unlabeled — always via `search_index_methodology_stack`, with the methodology name shown, or the mandated fallback note.
- Every dashboard must build through `assets/assemble.py`. This package bundles everything needed to do so: `assets/{dashboard-shell.html, assemble.py, disclaimer-footer.html, disclaimer-notice.txt, refresh-snippet.html, logos/}` and `references/{brand.md, recipes.md, metric-audit.md, mcp-queries.md}`. Full build mechanics, the shared shell/brand/disclaimer stack, and the as-of/range control are documented in `references/recipes.md`'s "Shared conventions" section (self-contained in this package) — apply them exactly as written; do not re-derive or simplify them.

Referenced files: 11

View saved version →

---
name: dashboard-performance-risk
description: >-
  Use this skill to build a live, MSCI-branded HTML dashboard of an MSCI index's returns, factor (FaCS) tilts, and dividend yield via the IndexAI Insights MCP, plus MSCI's own computed IMX risk analytics (tracking error, Sharpe/information ratio, VaR/CVaR, drawdown, active-risk attribution) called out as a native interactive chart. Trigger for "how has X performed", "tracking error vs Y", "Sharpe ratio", "factor tilts", "VaR", "drawdown", "risk attribution" for an index, even if the user never says MSCI. Produces a rendered, refreshable .html artifact via the bundled assemble.py — never a text-only answer, and never a hand-derived risk number.
---

# Index Performance & Risk Dashboard

Build a self-contained, MSCI-branded HTML dashboard of an index's returns and factor drivers, with MSCI's own IMX risk analytics surfaced as a native interactive chart. Two distinct sources feed this dashboard and must stay visually and mechanically separate: MCP-direct catalog fields render **inside** the shell; IMX-computed risk analytics render as their **own interactive chart**, never re-plotted into the shell's SVG renderer. See `references/recipes.md` §2 and `references/metric-audit.md` §2 for the exact field/mnemonic list.

## Output

One dashboard: KPI row (YTD, 1Y, 3Y CAGR, latest tracking error if a benchmark is set) → multi-period returns table → historical level chart → factor-tilt panel → "Risk analytics" panel (native IMX chart callout) → standard disclaimer footer. Equity indexes only — for fixed income/hedged indexes, state plainly that IMX risk analytics aren't available and show only the in-shell returns/factor fields. Present the file with `present_files`, stating index/benchmark, currency, variant, as-of date/range.

## Workflow

1. Resolve the index (required) and, if the user wants relative metrics, a benchmark index — both via `search_index_indexes`, never guessed. Resolve the as-of business date from a probe call's `fetched_date`, never today's calendar date.
2. **In-shell part** (through `assets/assemble.py` like every dashboard): `fetch_index_data` for `equity_index.performance.period_returns.{period,returns}` and `equity_index.facs_ratios.*`; `fetch_index_timeseries` for the historical level chart and, where `supports_range=true`, factor-tilt history. Render KPI cards, the multi-period table, and a factor-tilt panel — all MCP-direct, inline SVG, no external chart lib.
3. **Native IMX part** (NOT built through the shell's chart renderer): call `calculate_metrics` with the mnemonics in `references/metric-audit.md` §2 — `key_metrics`, `key_risk_metrics`, `index_tracking_error`, `index_sharpe_ratio`, `index_information_ratio`, both risk-attribution breakdowns, both risk-contributor grids — passing the benchmark as `benchmark_portfolio` when a relative view is wanted. Present the result as its own interactive chart in the conversation; the dashboard body only labels and describes this panel, it does not re-render the numbers.
4. Attempt **every** category in that mnemonic list, not an arbitrary subset (standing rule 9) — a category genuinely needing a benchmark the user didn't supply is labelled "requires a benchmark", never omitted from the panel or shown as zero; a category that errors is labelled with the error, never silently dropped.
5. Validate: in-shell returns/factor fields follow the same return/unit checks as the Composition dashboard; relative IMX metrics are never rendered as 0 or blank when `benchmark_portfolio` is absent.
6. Add one grounded interpretive callout per major section (standing rule 10).

## Interpretation

- Never recompute Sharpe/tracking error/etc. yourself from the in-shell returns, even as a fallback — that's exactly the ad hoc-methodology shortcut the metric rule exists to prevent. MSCI computes these itself as IMX analytics; if IMX is genuinely unavailable on the connection, say so rather than approximating.
- Label FaCS tilts as relative to MSCI ACWI IMI (per their own field description), never as absolute levels.
- Momentum-style factor strategies can reverse sharply when leadership rotates — a strong multi-year tilt number doesn't guarantee a positive short-horizon return; state both where relevant.

## Handoff

- What's inside the index (holdings, sector/country weights, cross-index membership) → `dashboard-composition`.
- Carbon intensity, temperature alignment, climate VaR, or a Low Carbon Transition score → `dashboard-climate`.
- What changed at the last N reviews → `dashboard-changes`.
- Eligibility or the rule behind a factor/weight → `dashboard-methodology`.
- Comparing performance/risk across more than 2 indexes at once → `dashboard-comparator`.
- The factor methodology input behind selection/weighting (Quality/Momentum/Dividend score) → `dashboard-fimd`.

## Guardrails

- MCP-direct fields + simple arithmetic only for the in-shell part; methodology-sensitive analytics (tracking error, Sharpe, Sortino, alpha, beta, information ratio, correlation, rolling volatility, max drawdown) are never derived by this skill's own arithmetic — only ever shown via the native IMX chart.
- A relative metric requested without a benchmark is stated as requiring one, never shown blank or as zero.
- Every dashboard must build through `assets/assemble.py`. This package bundles everything needed to do so: `assets/{dashboard-shell.html, assemble.py, disclaimer-footer.html, disclaimer-notice.txt, refresh-snippet.html, logos/}` and `references/{brand.md, recipes.md, metric-audit.md, mcp-queries.md}`. Full build mechanics, the shared shell/brand/disclaimer stack, and the as-of/range control are documented in `references/recipes.md`'s "Shared conventions" section (self-contained in this package) — apply them exactly as written; do not re-derive or simplify them.

Referenced files: 11

View saved version →

---
name: eligibility
description: >-
  Use this skill to explain whether/why a security passes or fails MSCI index eligibility screens, including free float, foreign inclusion factor/foreign room, liquidity (ATVR/frequency of trading), market-cap and size-segment cutoffs, or current GIMI/index eligibility. Trigger for "why isn't this stock in the index?", "what would it take to qualify?", or "which size segment does it fit?".
---

# MSCI index eligibility screen

Compare MSCI-measured security values with MSCI inclusion-monitor cutoffs and flags. Passing quantitative screens is necessary but not proof of a future index addition.

## Output

Present one row per relevant screen: test, measured value, cutoff/bound if available, and pass/fail/flag. Then identify the binding screen or, if every test passes, the narrowest margin. Include calculation date and the exact mandatory inclusion disclaimer from `constraints.notes`.

## Workflow

1. Resolve the security with `search_index_securities`.
2. Use `search_index_datapoints` to discover the relevant inclusion-monitor fields. Search only the families needed for the question:
   - free float / rounded free float
   - foreign inclusion factor / investability factor
   - foreign room and lower/upper bounds
   - ATVR and frequency-of-trading liquidity
   - full/float-adjusted market cap
   - standard/IMI/large/mid/small cutoffs and assignment flags
   - overall eligibility/current membership flags
3. Read `constraints.notes` on every selected datapoint. Follow the monitor publication-date rule and reproduce the mandatory disclaimer exactly.
4. Fetch with `fetch_index_data` on the required date.
5. For China A-share questions, also discover and include any Stock Connect/access fields needed to interpret eligibility.
6. If the user asks for the rule itself rather than the measured value, use the methodology workflow or methodology-stack search instead of inventing the rule from raw datapoints.

## Interpretation

- Treat `_fg`/flag fields as authoritative reported indicators, not percentages.
- Treat `_pct` and `_musd` fields according to their documented units.
- If an overall eligibility flag conflicts with a manual reading of components, report both and note the discrepancy. Do not override the MSCI flag with your own arithmetic.
- Cutoffs are point-in-time and can move with market conditions, so date every result.

## Guardrails

- Never say a security "will be added" merely because it passes screens.
- Missing data is not a pass.
- Foreign room/FIF interactions may require methodology text; do not infer the governing rule from raw values alone.
- Reproduce the Index Inclusion disclaimer from `constraints.notes` verbatim.

View saved version →

---
name: esg-screen
description: >-
  Use this skill to screen securities/holdings against MSCI ESG ratings, controversies, and business-involvement restrictions such as weapons, tobacco, gambling, alcohol, adult entertainment, thermal coal, arctic drilling, or other mandate exclusions. Trigger when the user gives holdings plus ESG restrictions or asks whether names breach a stated threshold.
---

# ESG and business-involvement screening

Turn mandate language into explicit, auditable tests using MSCI fields. A definitive exclusion requires a defined rule: involvement flag, revenue percentage threshold, rating threshold, controversy threshold, or another stated criterion.

## Output

Group breaches first. For every holding, show identity, measured value/status, threshold or rule applied, pass/fail/unscreened, and evaluation date. State whether current or rebalancing values were used.

## Workflow

1. Parse each restriction into a test. Distinguish involvement flags from revenue-percentage thresholds; they are not interchangeable.
2. If a numeric threshold is essential but omitted, do not invent one. You may still return the measured exposure/status and label the pass/fail conclusion as undetermined until a threshold is specified.
3. Discover exact fields with `search_index_datapoints`. Do not compose ids from memory. When both current and `.rebalancing` variants exist, use current values for "today/current portfolio" questions and rebalancing values only for a review/rebalance construction question.
4. Resolve securities with `search_index_securities`; resolve an index with `search_index_indexes` when the user asks about index-level ESG metrics.
5. Read `constraints.notes`, `strict_gate`, and date availability before fetching.
6. Use `fetch_index_data` for point-in-time screening. If the selected data snaps to another date, state the requested and fetched date.
7. For rebalancing-aware fields, resolve the documented rebalance date rather than guessing one.

## Interpretation

- Missing value = unscreened/unknown, never an automatic pass.
- An involvement flag is categorical; a revenue field is quantitative.
- If the user asks for an ESG rating, include the underlying score when the catalog/tool definition makes that relationship relevant.

## Guardrails

- Never report an exclusion without naming the rule/threshold applied.
- Do not describe the output as a legal/compliance opinion. It is a data screen against the rule supplied by the user.
- Date the assessment; involvement and controversy data can be restated.
- Preserve units and threshold direction exactly.

View saved version →

---
name: index-aum
description: >-
  Use this skill when the user asks how much AUM is benchmarked to an MSCI index, the ETF/non-ETF split, which linked exchange-traded products track the index, who provides them, or passive ownership linked to an MSCI security.
---

# AUM benchmarked to an MSCI index

Use the MSCI Index app to report benchmark-linked AUM, distinct from index market capitalization and distinct from fund flows.

## Output

Lead with total benchmarked AUM, then ETF/non-ETF split and their own as-of dates. If the user asks for linked products, include provider and show how many rows are displayed versus available.

## Workflow

1. Resolve the index with `search_index_indexes` using a concise name such as `EAFE`, `World`, `EM`, or `ACWI`.
2. Discover the AUM aggregate datapoints with `search_index_datapoints`; do not hardcode ids without discovery. Search concepts should include total AUM, ETF AUM/as-of date, and non-ETF AUM/as-of date.
3. Read `constraints.notes` and fetch supported point-in-time data with `fetch_index_data`.
4. For linked products, discover the list-cardinality linked-ETP datapoint. Use `fetch_index_data` with pagination, ordering, and supported filters such as provider/management style/taxonomy only when documented by the tool contract.
5. For security-level benchmark-linked AUM, resolve the security with `search_index_securities` and discover the constituent/security AUM fields before fetching.

## Presentation

- Identify the index as `<name> (<msci_index_code>)`.
- State AUM units exactly; if returned in millions of USD, convert to billions only with an explicit conversion label.
- ETF and non-ETF as-of dates may differ. Put each date beside its figure rather than assigning one common date to the total unless the returned dates actually agree.
- If useful, show ETF and non-ETF as percentages of the summed split, but do not imply those percentages are fund flows.

## Guardrails

- Benchmarked AUM is not index market capitalization.
- AUM level is not period fund flow. If the user wants inclusion/rebalance flow sizing, use the `index-flows` workflow.
- Product coverage reflects the connected MSCI product dataset; absence from the returned list is not proof a product does not exist.
- Respect entitlements and pagination. Do not claim complete coverage when only one page was fetched.

View saved version →

---
name: index-changes
description: >-
  Use this skill for what changed in an MSCI index at a review or corporate event: additions and deletions, proforma constituents, FIF/number-of-shares changes, index turnover, and corporate actions. Trigger for "what changed in the May review", "which companies were added or removed", "when was this stock deleted", "index turnover for this rebalance", "upcoming index changes", even if the user never says MSCI.
---

# MSCI index changes and review outcomes

Report what an index review or corporate event actually changed. Review **outcomes** live in the change datasets; review **rules** live in methodology. Do not answer one from the other.

## Output

Lead with the change list or figure. Identify the index as `<name> (<msci_index_code>)`, state the rebalance date used and how it was resolved, and distinguish announcement date from effective date whenever both are returned.

## Workflow

1. Resolve the index with `search_index_indexes`.
2. Discover the change datapoints with `search_index_datapoints`. Typical concepts: additions, deletions, proforma constituents, FIF changes, number-of-shares changes, corporate events, turnover.
3. **Resolve the rebalance date in two steps. Never pass today, a guessed month-end, or a first-of-month date to a rebalancing-aware datapoint.**
   - Fetch `master_description` rebalancing fields — last rebalancing date, next rebalancing date, and future-days where available — using a probe date: the user's explicit date, or the month-end of the month the user named, or the latest business date if unspecified.
   - Prefer the returned next rebalancing date when it is not null or empty. Otherwise fall back to the returned last rebalancing date.
   - Pass that returned value as `date`. Do not construct it.
4. Set `rebalance_target` deliberately:
   - `previous` — the most recent completed review. Pass the returned last rebalancing date as `date`.
   - `upcoming` — the current announcement window. `date` is ignored; the server uses its own reference date. If the date falls outside MSCI's live review window the change datapoints come back empty with an `outsideRebalWindow.message` — relay it verbatim rather than reporting "no changes".
   - `proforma_start_date` — returns the earliest calc date at which proforma data exists, as `{ start_proforma_date, rebalanceDate }`. The `datapoints` array must contain at least one proforma-constituent id, and must not carry `master_description` ids.
     This mode alone rejects a forward `date` — passing a future next-rebalancing date fails with `Calculation Date(calc_date) can not be in future`. Pass the latest business date and let the server resolve the proforma window. The step 3 preference for the next rebalancing date applies to the change datasets, not here.
5. Read `constraints.notes` on every selected datapoint before fetching, including required `info_points` and any mandatory disclaimer.
6. Fetch with `fetch_index_data`. Use `order_by` / `order_direction` and pagination for long add/delete lists, and state rows shown versus available.
7. **Resolve the security names — required.** Additions and deletions return bare `msci_security_code` values with no names, so a raw answer is a list of numbers. Make a **second** `fetch_index_data` whose `codes` are those security codes, batched, with `security.description.security_name` (and country where useful), reusing the same date. Do not mix index codes and security codes in one call. Never present unresolved codes as the answer.
8. **Turnover.** `equity_index.performance.total_index_turnover` is range-only (`supports_single_day=false`), so it must go through `fetch_index_timeseries`, not `fetch_index_data`. Set `start_date` and `end_date` both to the review effective date to isolate that review — over a wider window the value is a single aggregate summed across the range, with a blank date cell, which is expected. The value returns as a **fraction**, so multiply by 100 to present a percentage. It is MSCI's **one-way** turnover; MSCI's printed review report shows **two-way**, which is twice that figure — state which convention you are showing. If no published turnover field is available and you derive one from add/delete weights, say it was derived and give the basis.

## Historical change questions

For "when was this security added or deleted", resolve the security with `search_index_securities`, then work from the change datasets across the relevant review dates. Do not infer an effective date from a price or weight series.

## Interpretation

- Announcement date and effective date are different facts. Report whichever the data returns, labelled.
- Proforma data is pre-announcement and estimated. It can be discarded and re-announced if constraints are breached between announcement and effective date.
- A change list reflects the index and review requested. Do not generalise it to a parent, child, or sibling index.
- Corporate-event driven changes are not review changes; keep them distinguishable when both appear.

## Handoff

- Why the rule produced the change, or review frequency → `methodology`.
- Passive flow, days-to-trade, or estimated demand from a change → `index-flows`.
- Current holdings and weights outside a review context → `composition`.
- Whether a security clears the screens → `eligibility`.

## Guardrails

- Never invent or arithmetically derive a rebalance date. Use the value the app returns.
- No returned changes is not the same as no changes. Report it as unavailable or outside the returned window.
- Proforma is an estimate, not an announcement, and not a prediction that a security will be added or deleted.
- Reproduce any mandatory disclaimer from `constraints.notes` verbatim.
- Do not present a single page of a long add/delete list as the complete review outcome.

View saved version →

---
name: index-flows
description: >-
  Use this skill to quantify MSCI index-inclusion or deletion impact for a security: estimated passive AUM to buy/sell, estimated/current index weight and AUM, and execution scale such as days-to-trade. Trigger for rebalance-flow sizing, inclusion-monitor questions, or "what happens if this stock enters/leaves MSCI World/ACWI/EM/IMI/Small Cap".
---

# Index inclusion flow impact

Use MSCI's inclusion-monitor and AUM datasets to size estimated benchmark-driven demand or supply. Treat monitor outputs as estimates, not official index-change announcements.

## Output

Lead with estimated flow, implied weight, and execution scale for the requested index family. Include calculation/pro-forma dates and the security identity. Reproduce any mandatory Index Inclusion disclaimer supplied in datapoint `constraints.notes` exactly as returned.

## Workflow

1. Resolve the company/ticker/ISIN with `search_index_securities`. Do not infer a country filter from suffixes such as `(US)`, `ADR`, `CDI`, or `ADS`.
2. Search `search_index_datapoints` for the relevant inclusion-monitor fields rather than guessing ids. Typical concepts are estimated AUM, estimated weight, current AUM/weight, and total family index AUM for the requested family only.
3. Read every selected datapoint's `constraints.notes` before fetching. Follow the documented publication-calendar rule, required `info_points`, rebalance targeting, and mandatory disclaimer. Do not default to today's date if the notes specify another calculation date.
4. Fetch supported point-in-time monitor fields with `fetch_index_data` using the resolved `msci_security_code`.
5. For execution/tradability metrics such as days-to-trade or average traded value, discover the exact fields and follow their documented pro-forma date inputs. Pass `info_points` only when `constraints.notes` explicitly defines the required keys.
6. If the relevant data is rebalancing-aware, resolve the required rebalance date using the documented last/next-rebalancing workflow; never invent the review date.

## Presentation

For each requested index family, show the useful subset of:

- estimated AUM impact
- estimated weight
- current AUM/current weight
- total AUM benchmarked to the family
- days-to-trade / volume basis, when available

State units exactly. If AUM is returned in USD millions, label it as such or convert explicitly to billions.

## Guardrails

- Mandatory Index Inclusion disclaimer: reproduce the exact text from `constraints.notes`; do not paraphrase it.
- Monitor estimates are not announcements and do not mean a security will be added/deleted.
- Days-to-trade is an execution-scale indicator based on the dataset's volume assumptions, not a recommended trading schedule.
- Do not turn estimated flows into a buy/sell recommendation.
- No returned monitor data is not the same as zero flow. Report it as unavailable/outside the returned monitor universe unless the tool says otherwise.

View saved version →

---
name: methodology
description: >-
  Use this skill for questions about how an MSCI index is constructed, screened, reviewed/rebalanced, weighted, capped, buffered, migrated between size segments, or otherwise governed by MSCI methodology. Use official methodology search rather than memory.
---

# MSCI methodology, grounded in official documents

Answer rule questions from the methodology snippets returned by the MSCI Index app.

## Output

Give the direct rule/explanation, identify the methodology document/layer when returned, and include a short governing excerpt when useful. Keep quotations focused; explain the rule in your own words around them.

## Workflow

### Index-specific question

1. Resolve the index with `search_index_indexes`.
2. Call `search_index_methodology_stack` with the resolved index code and a concise substantive query. Prefer the stack because an index can inherit rules from several methodology layers.
3. If the first hits are weak, retry with the MSCI term of art suggested by the retrieved text or user intent.

### Named methodology document

1. Use `list_index_methodologies` for the relevant effective date.
2. Select the document code matching the user's named methodology.
3. Call `search_index_methodology` with a concise search term.

### Historical rule question

Use the historical `asOfDate` relevant to the rebalance/event instead of assuming today's methodology.

## Source discipline

- When official methodology `hits`/`results` contain text, answer **only** from those retrieved snippets. Do not blend training-memory rules into the answer.
- If official methodology search returns no usable text, say the official corpus did not return a matching passage. If you provide a general-knowledge fallback, label it clearly as not sourced from the official MSCI methodology.
- If the snippets do not settle the exact question, say what they do establish and where the gap remains.

## Handoff to data workflows

Methodology answers the rule; data tools answer whether a security/index meets it. For example, "what is the liquidity screen?" is methodology; "does Company X pass it?" is eligibility.

## Guardrails

- Never state an MSCI rule as authoritative without retrieved official support when methodology text is available.
- Do not generalize one index family's rule to another without confirming the governing document stack.
- Do not use a description/rebalancing-calendar datapoint as a substitute for the methodology when the user asks the review frequency or construction rule.

View saved version →

---
name: thematic
description: >-
  Use this skill to score or rank securities by MSCI thematic relevance, test whether holdings actually express a requested investment theme, or compare thematic exposure across names. Trigger for themes such as cybersecurity, robotics, digital health, fintech, future mobility, genomic innovation, space exploration, smart cities, defense/security, or related MSCI-published themes.
---

# MSCI thematic exposure scoring

Use published MSCI thematic relevance data to test thematic exposure claims at security level.

## Output

State the MSCI theme selected, explain any mapping from the user's wording, rank securities by score, and state the score's meaning and date. Never describe a relevance score as revenue percentage.

## Workflow

1. Search `search_index_datapoints` for the user's theme and inspect the available published thematic fields. Do not rely on a static remembered theme list when the live catalog can confirm availability.
2. If the user's language can map to more than one plausible MSCI theme, choose the closest supported field only when the mapping is defensible and state the choice. If no suitable theme exists, say so rather than silently proxying it.
3. Resolve each company/ticker/ISIN with `search_index_securities`. Resolve independent holdings in parallel when useful.
4. Fetch the selected security-level thematic field with `fetch_index_data`, obeying `constraints.notes` and date availability.
5. If the user asks for portfolio thematic exposure, combine the relevance scores with the user-supplied portfolio weights when available. If weights come from another MSCI index dataset, clearly identify that source and date.

## Presentation

- Rank descending unless the user requests another ordering.
- Identify each security as `<name> (<msci_security_code>)` when showing codes.
- State the selected theme and fetched date.
- Explain that a high relevance score reflects MSCI's thematic framework, not expected return, quality, or a recommendation.

## Guardrails

- Relevance score is not revenue percentage.
- Do not invent unsupported themes.
- Date every score; scores can change or be restated.
- If aggregating to portfolio level, show or describe the weighting method.