HK-US Institutional Concentration
Build a reproducible company-level ownership panel for Hong Kong and US stocks. Treat
aggregate concentration as an entry point, not a verdict.
Mandatory research gate
Do not answer immediately when this skill is invoked. Before calculating, ranking,
or interpreting ownership, spend at least 30 seconds on substantive analysis when
the runtime permits. Never satisfy this requirement with an idle sleep.
Complete all checks below before presenting a conclusion. Record each result in
an evidence ledger; a silent assumption does not count as a completed check:
- Confirm market, universe, observation date, holder definition, and requested use.
- Verify whether each API value is a current snapshot or historically dated; apply the 45-calendar-day 13F availability lag and never backfill a current snapshot into a historical test.
- Report universe size, non-null coverage, ADR/local-share issuer deduplication, fallback identities, and source-data anomaly counts.
- Check percentage scale, HHI range, maximum-holder share, and top-20 consistency.
- Separate ownership breadth from holder dominance and evidence confidence.
- Treat
data_anomaly and insufficient_data as non-rankable states, not low-risk observations.
- If performance validation is requested, require historically dated ownership snapshots and forward returns. Otherwise explain why IC and equity curves are not identified.
- Test the classification under at least two alternative dominance thresholds
or HHI cutoffs and identify labels that change.
- Inspect the largest metric disagreements, such as high aggregate breadth but
low top-20 ownership, before ranking.
- Separate observed structure, data confidence, economic interpretation, and
unsupported return claims.
If any gate fails, state the limitation before showing rankings. Do not use a
visual report or a harness PASS to conceal incomplete historical identification.
Evidence ledger
For research or ranking requests, include a compact ledger with all rows below.
For a single-stock lookup, retain it internally and surface every failure.
| Gate |
Required evidence |
Failure action |
| Scope |
market, universe, date, holder definition |
state assumptions |
| Semantics |
endpoint, units, snapshot/report date |
stop historical claim |
| Coverage |
returned, missing, duplicates, ranking depth |
downgrade confidence |
| Structure |
breadth, top-20, largest holder, HHI, gap |
do not use one label |
| Anomalies |
invalid percentages and HHI |
mark non-rankable |
| Sensitivity |
two threshold alternatives |
label instability |
| Interpretation |
evidence vs hypothesis vs prediction |
revise conclusion |
Workflow
- Normalize symbols: keep Hong Kong symbols as
NNNN.HK; keep US tickers uppercase.
- Read references/api-map.md before changing API calls or field mappings. Read references/methodology.md before issuer deduplication or point-in-time use. Read references/runtime.md when installing the SDK or configuring credentials.
- Run
scripts/build_panel.py. Use --mode mock for deterministic offline verification and --mode api for PandaAI data.
- Treat the API aggregate concentration value as breadth. Separately compute top-holder dominance and holder HHI from ranking rows.
- Classify the observed structure as
broad_institutional, dominant_holder, or fragmented_or_mixed; do not collapse these states into a single good/bad score.
- Deduplicate mapped ADR/local listings at issuer level, retain the primary/local listing, and write exclusions. Report
data_confidence from metric coverage. Preserve raw extracts and never silently convert missing values to zero.
- Treat US 13F holdings as available only 45 calendar days after period end; use
availability_date for historical joins.
- Run
scripts/harness.py --output-dir <dir> and require PASS before delivery.
Commands
python scripts/build_panel.py --mode mock --market both --output-dir outputs
python scripts/harness.py --output-dir outputs
For live data, set the official PANDA_DATA_USERNAME and PANDA_DATA_PASSWORD variables outside the skill and run:
python scripts/build_panel.py --mode api --market both --symbols 0700.HK,AAPL --start-date 20250101 --end-date 20251231 --output-dir outputs_live
For the complete HK and US universe exposed by PandaData:
python scripts/build_panel.py --mode api --market both --full-universe --output-dir outputs_full
Full-universe mode skips the much larger dated shareholder-report extract by default;
add --include-shareholder-reports only when that detail is required.
Outputs
institutional_concentration_panel.csv: one row per market and symbol, including structure and evidence-confidence labels.
investor_ranking.csv: normalized ranked-holder detail.
shareholder_reports.csv: dated shareholder-report detail when requested.
issuer_dedup_exclusions.csv: ADR/local listings removed after issuer-level resolution.
raw_*.csv: unmodified API extracts.
quality_report.json: row counts, coverage, duplicates, and warnings.
harness_report.json: delivery acceptance result.
Interpretation
Read the result in layers:
concentration_pct describes overall institutional participation.
top20_concentration_pct, largest_holder_pct, and holder_hhi describe how that participation is distributed.
ownership_structure summarizes the combination; data_confidence says how much evidence supports it.
A high aggregate percentage with low HHI indicates broad institutional ownership;
high HHI or a very large top holder indicates dominance risk. Compare stocks within
the same market and observation date. These are ownership diagnostics, not return
forecasts, and the thresholds are transparent screening rules rather than universal
economic laws.
Completion gate
Do not call the task complete unless harness.py passes, universe and anomaly
counts are reported, every structure label is traceable to visible metrics, the
observation-date limitation is explicit, and any return claim uses genuinely
dated ownership snapshots with the 13F availability lag.
1---2name: skill-hk-us-institutional-concentration3description: Build, compare, and validate institutional ownership structure panels for Hong Kong and US equities with PandaAI investor concentration, ranking, and shareholder-report APIs. Use for ownership breadth, top-holder dominance, HHI, controlling-holder risk, evidence confidence, or within-market institutional ownership screening.4metadata:5 source: https://skillmd.com/skills/quantskills/skill-hk-us-institutional-concentration6---78# HK-US Institutional Concentration910Build a reproducible company-level ownership panel for Hong Kong and US stocks. Treat11aggregate concentration as an entry point, not a verdict.1213## Mandatory research gate1415Do not answer immediately when this skill is invoked. Before calculating, ranking,16or interpreting ownership, spend at least 30 seconds on substantive analysis when17the runtime permits. Never satisfy this requirement with an idle sleep.1819Complete all checks below before presenting a conclusion. Record each result in20an evidence ledger; a silent assumption does not count as a completed check:21221. Confirm market, universe, observation date, holder definition, and requested use.232. Verify whether each API value is a current snapshot or historically dated; apply the 45-calendar-day 13F availability lag and never backfill a current snapshot into a historical test.243. Report universe size, non-null coverage, ADR/local-share issuer deduplication, fallback identities, and source-data anomaly counts.254. Check percentage scale, HHI range, maximum-holder share, and top-20 consistency.265. Separate ownership breadth from holder dominance and evidence confidence.276. Treat `data_anomaly` and `insufficient_data` as non-rankable states, not low-risk observations.287. If performance validation is requested, require historically dated ownership snapshots and forward returns. Otherwise explain why IC and equity curves are not identified.298. Test the classification under at least two alternative dominance thresholds30 or HHI cutoffs and identify labels that change.319. Inspect the largest metric disagreements, such as high aggregate breadth but32 low top-20 ownership, before ranking.3310. Separate observed structure, data confidence, economic interpretation, and34 unsupported return claims.3536If any gate fails, state the limitation before showing rankings. Do not use a37visual report or a harness `PASS` to conceal incomplete historical identification.3839### Evidence ledger4041For research or ranking requests, include a compact ledger with all rows below.42For a single-stock lookup, retain it internally and surface every failure.4344| Gate | Required evidence | Failure action |45|---|---|---|46| Scope | market, universe, date, holder definition | state assumptions |47| Semantics | endpoint, units, snapshot/report date | stop historical claim |48| Coverage | returned, missing, duplicates, ranking depth | downgrade confidence |49| Structure | breadth, top-20, largest holder, HHI, gap | do not use one label |50| Anomalies | invalid percentages and HHI | mark non-rankable |51| Sensitivity | two threshold alternatives | label instability |52| Interpretation | evidence vs hypothesis vs prediction | revise conclusion |5354## Workflow55561. Normalize symbols: keep Hong Kong symbols as `NNNN.HK`; keep US tickers uppercase.572. Read [references/api-map.md](references/api-map.md) before changing API calls or field mappings. Read [references/methodology.md](references/methodology.md) before issuer deduplication or point-in-time use. Read [references/runtime.md](references/runtime.md) when installing the SDK or configuring credentials.583. Run `scripts/build_panel.py`. Use `--mode mock` for deterministic offline verification and `--mode api` for PandaAI data.594. Treat the API aggregate concentration value as breadth. Separately compute top-holder dominance and holder HHI from ranking rows.605. Classify the observed structure as `broad_institutional`, `dominant_holder`, or `fragmented_or_mixed`; do not collapse these states into a single good/bad score.616. Deduplicate mapped ADR/local listings at issuer level, retain the primary/local listing, and write exclusions. Report `data_confidence` from metric coverage. Preserve raw extracts and never silently convert missing values to zero.627. Treat US 13F holdings as available only 45 calendar days after period end; use `availability_date` for historical joins.638. Run `scripts/harness.py --output-dir <dir>` and require `PASS` before delivery.6465## Commands6667```bash68python scripts/build_panel.py --mode mock --market both --output-dir outputs69python scripts/harness.py --output-dir outputs70```7172For live data, set the official `PANDA_DATA_USERNAME` and `PANDA_DATA_PASSWORD` variables outside the skill and run:7374```bash75python scripts/build_panel.py --mode api --market both --symbols 0700.HK,AAPL --start-date 20250101 --end-date 20251231 --output-dir outputs_live76```7778For the complete HK and US universe exposed by PandaData:7980```bash81python scripts/build_panel.py --mode api --market both --full-universe --output-dir outputs_full82```8384Full-universe mode skips the much larger dated shareholder-report extract by default;85add `--include-shareholder-reports` only when that detail is required.8687## Outputs8889- `institutional_concentration_panel.csv`: one row per market and symbol, including structure and evidence-confidence labels.90- `investor_ranking.csv`: normalized ranked-holder detail.91- `shareholder_reports.csv`: dated shareholder-report detail when requested.92- `issuer_dedup_exclusions.csv`: ADR/local listings removed after issuer-level resolution.93- `raw_*.csv`: unmodified API extracts.94- `quality_report.json`: row counts, coverage, duplicates, and warnings.95- `harness_report.json`: delivery acceptance result.9697## Interpretation9899Read the result in layers:1001011. `concentration_pct` describes overall institutional participation.1022. `top20_concentration_pct`, `largest_holder_pct`, and `holder_hhi` describe how that participation is distributed.1033. `ownership_structure` summarizes the combination; `data_confidence` says how much evidence supports it.104105A high aggregate percentage with low HHI indicates broad institutional ownership;106high HHI or a very large top holder indicates dominance risk. Compare stocks within107the same market and observation date. These are ownership diagnostics, not return108forecasts, and the thresholds are transparent screening rules rather than universal109economic laws.110111## Completion gate112113Do not call the task complete unless `harness.py` passes, universe and anomaly114counts are reported, every structure label is traceable to visible metrics, the115observation-date limitation is explicit, and any return claim uses genuinely116dated ownership snapshots with the 13F availability lag.