pokemon-champions-meta git:20260916.a23f773A

Immutable. This exact content is served forever at /api/v1/blob/47a236a1a0c5f000.

---
name: pokemon-champions-meta
description: Offline-first Pokémon Champions metagame cache and query API for current and historical seasons/rules in single and double formats. Use when the request is about metagame popularity, distribution, common sets, partners, format comparison, update reports, or current/historical environment summaries; do not trigger merely because an item/ability/nature is mentioned without usage or environment context. Chinese examples include "现在环境哪些常见", "X使用率/排名多少", "X常见配置", "X常带什么道具/常用什么性格/招式", "X常见队友", "单双打环境差异", "这期有什么变化". English examples include "usage/ranking for X", "what does X commonly run", "common items/moves/natures for X", "popular partners", "single vs double meta comparison", "latest meta changes". Japanese examples include "環境で多いポケモン", "Xの採用率/順位", "Xのよくある型", "よく採用される技/持ち物/性格", "相方", "シングルとダブルの違い", "今期の変化".
---

# Pokémon Champions Meta

Query the bundled Pokémon Champions metagame snapshot for rankings, common configurations, partners,
format comparisons, and factual changes between snapshots. This skill answers "what is popular and
how is it used?"; canonical battle facts remain the responsibility of `$pokemon-champions-dex`.

## Workflow

1. Use the current season/rule unless the user explicitly requests a historical context.
2. Use `ranking` for the environment overview and `detail` for one Pokémon's panels.
3. Use `search` for reverse lookup across panel entries and `compare` for single-vs-double facts.
4. Use `ko` for the knock-out axis — whom a Pokémon knocks out and who knocks it out.
5. Use `report` for snapshot changes. Use `export-excel` only when the user requests workbooks.
6. Keep usage marginals factual: common moves/items/partners are not a guaranteed joint set.

## Commands

Query cached rankings:

```bash
# Uses the current season/rule by default.
python scripts/meta_query.py ranking --format single --limit 20
python scripts/meta_query.py ranking --format double --limit 20
python scripts/meta_query.py ranking --format double --season M-4 --rule M-B --limit 20
```

Query Pokémon details:

```bash
python scripts/meta_query.py detail --format single --pokemon 雷丘
python scripts/meta_query.py detail --format double --pokemon garchomp
```

Reverse-search panel entries or compare formats:

```bash
python scripts/meta_query.py search --format double --panel moves --name 地震
python scripts/meta_query.py search --format both --panel moves --type ground --category physical --min-usage 20
python scripts/meta_query.py search --format single --panel moves --where '{"and":[{"type":"Fire"},{"or":[{"category":"Special"},{"usage":">=20"}]}]}'
python scripts/meta_query.py compare --pokemon 雷丘
python scripts/meta_query.py report --format both
```

Query the KO axis (a separate data family with its own upstream snapshot):

```bash
python scripts/meta_query.py ko --format double --pokemon 大狃拉
python scripts/meta_query.py ko --format single --pokemon Salamence --panel koed_by
python scripts/meta_query.py ko --format single            # coverage only: what this snapshot has
```

`ko_targets` (alias `beats`) is whom the Pokémon knocks out; `koed_by` (alias `counters`) is who
knocks it out. Both are an **ordering only** — the source publishes no percentage, so none is shown.
Both are **species-level**: opponents are keyed by national dex number with no form, and a species
that appears twice in one list is flagged rather than de-duplicated. `ko_moves` / `koed_by_moves` are
a reserved tier: while `coverage.move_share` is `absent` they are `null`, meaning NOT COLLECTED — not
"no KO moves". Never present a KO list as a matchup win rate; it counts knock-outs, not games.

Names resolve through the sibling dex in Chinese, English, or Japanese. Fuzzy corrections are always
disclosed: structured detail/compare results carry resolution metadata, while `search` reports a
correction on stderr without contaminating JSON stdout.

Use JSON for downstream processing:

```bash
python scripts/meta_query.py detail --format double --pokemon garchomp --output json
```

## Contract And Output

Treat the executable schema as the authority for commands, flags, fields, boolean query grammar, and
errors:

```bash
python scripts/meta_query.py schema
```

Canonical JSON is language-independent. Human-readable output language precedence is `--lang`, then
`POKEMON_CHAMPIONS_LANG`, then `en`. Read `references/api.md` for detailed command usage and
`references/schema.md` only when the bundled cache layout matters.

## Excel Export

`export-excel` always writes three standalone single-language workbooks (`zh`, `ja`, `en`) to the
chosen output directory, independently of `--lang`:

```bash
python scripts/meta_query.py export-excel --season M-4 --rule M-B
```

This is the only command requiring `openpyxl`; install `requirements.txt` when export is needed. All
query commands use the Python standard library.

## Boundaries

- The shipped snapshot is read-only and queried offline; its date and season/rule stamp define freshness.
- Do not infer legality or learnsets from usage data.
- Do not combine move, item, ability, nature, partner, or spread marginals into an asserted joint set.
- A change report records factual differences between snapshots, not an interpretation of the metagame.
- KO facts come from a different upstream snapshot than the usage data; quote each one's own
  `updated_at` and never treat a KO ordering as a win rate, a counter verdict, or a damage result.