---

name: installation-discovery description: "Route Earth2Studio installation, optional dependency selection, environment validation, and task-driven discovery of model families, data sources, lexicons, examples, and output backends without running inference or downloading data." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

Installation and discovery

Use this sub-skill when a user needs to prepare an Earth2Studio environment or narrow a weather/climate task to a small, defensible set of model, data-source, lexicon, example, and output-backend candidates. The verified source snapshot is 0.18.0a0; treat package metadata and the user's installed version as the authority when they differ from this snapshot.

Boundaries

• Give commands and validation steps; do not run package managers, install packages, fetch remote data, download checkpoints, run inference, or serve a workflow.
• Do not present the catalog as exhaustive. Optional model/data packages, credentials, licenses, remote availability, and GPU compatibility remain candidate-specific.
• Do not infer compatibility from a model name alone. Check the model's input_coords() requirements against a source lexicon and then check grid, time, region, access, and hardware constraints.
• Route serving requests elsewhere. This sub-skill may identify an output backend for a later workflow, but it does not configure Earth2StudioClient, RemoteEarth2Workflow, or a server.

Read the detailed installation reference, model and data overview, and troubleshooting guide as needed. Use the safe, offline environment checker for a local preflight.

1. Normalize the request

Collect only the facts needed for routing:

1. Install target: released package, approved source revision, or an existing project; package manager (uv, pip, or Conda-managed Python).
2. Runtime: Python version, operating system/build tools, PyTorch version, CUDA runtime/driver, GPU model/VRAM/count, and whether CPU-only inspection is intended.
3. Task: prognostic forecast, diagnostic/downscaling/derived product, data assimilation (beta), observations/data preparation, or a combination; region, forecast horizon, variables/levels, deterministic versus ensemble, and latency/storage needs.
4. Access constraints: network/credential policy, checkpoint/data licensing, cache location and disk budget, and whether remote availability may be inspected later by the user.

If Python or CUDA facts are missing, ask for them rather than promising that an extra will work. Run only read-only checks supplied by the user, for example:

python --version
python -c "import torch; print(torch.__version__, torch.version.cuda, torch.cuda.is_available())"
python scripts/check_environment.py --json

Use uv run instead of bare python when the project is managed by uv. The checker itself is standard-library-only and is safe from an arbitrary cwd.

2. Route installation

1. Prefer a fresh Python 3.13 environment. The package declares >=3.11,<3.15; Python 3.10 and Python 3.15 are unsupported for this snapshot. PyTorch must be installed for the selected CUDA/CPU target before GPU-sensitive extras.
2. Start with the smallest useful dependency set. The base package supplies core APIs and IO interfaces, not most model or data-source dependencies. Select one model family plus data, perturbation, statistics, or utils only when the task needs it. Do not install all merely to avoid deciding: it is broad, expensive, and does not make every model combination semantically compatible.
3. Give, but do not execute, an appropriate command. Released-package forms are uv add "earth2studio[<extra>,...]" or pip install "earth2studio[<extra>,...]". With Conda, create/activate the Python 3.13 environment and use standard Python tooling for Earth2Studio; do not mix a second dependency resolver without a reason. Approved source revisions use the same extra syntax with the project's VCS requirement.
4. Resolve known build-sensitive extras in isolation. AIFS variants use flash-attn; Atlas and some StormCast variants use natten; FCN3/SFNO and perturbation use torch-harmonics; some packages are configured for no-build-isolation. Build tools and Python headers may be required.
5. Explain targeted prerequisites before the command: GraphCast/GenCast use WeatherNext and require Python >=3.12; FengWu/FuXi/Pangu use ONNX Runtime GPU; CUDA data-assimilation extras use CUDA-13 CuPy and, for most variants, cuDF. Avoid combining mutually conflicting uv extras; see the reference.
6. Ask the user to run the command, then validate without downloading assets:

python -c "import earth2studio; print(earth2studio.__version__)"
python scripts/check_environment.py --require-cuda  # only for GPU tasks

A successful core import proves neither optional model imports nor checkpoint access. Validate each selected optional class with a targeted import after the user installs its extra; do not import every model namespace as a proxy.

3. Route discovery

Build a short list, not a catalog dump:

1. Classify the task as PX (time-stepping forecast), DX (diagnostic, downscaling, derived, or tracking), DA (beta assimilation), or data-only.
2. Filter candidates by region, temporal scale, variables/levels, deterministic or ensemble requirement, GPU/VRAM, and release/version. Record the extra and any access or license prerequisite for each candidate.
3. Identify a data-source family: analysis/reanalysis, forecast, satellite or observations, local arrays, or tabular/forecast-frame observations. A data source uses (time, variable) and returns an xarray DataArray; a forecast source adds lead_time; dataframe variants return pandas dataframes.
4. Compare the model's input_coords() variable coordinate with the candidate lexicon's VOCAB keys. This is a necessary screen, not proof of fit: also compare pressure/height conventions, latitude/longitude grid, time/lead-time coverage, source availability, and any authentication.
5. Recommend one to three relevant gallery patterns, such as getting started, medium range, downscaling, nowcasting, seasonal, data assimilation, IO, or extension. Examples are patterns, not a promise that their checkpoints or remote inputs are available in the user's environment.
6. Select an output backend only by storage need: ZarrBackend is the default datetime-friendly choice; AsyncZarrBackend is for asynchronous/sharded writes with filesystem/inode trade-offs; NetCDF4Backend, XarrayBackend, and KVBackend cover other file, in-memory, or key/value needs. This is discovery guidance only; no workflow is executed here.

For AutoModel-backed classes, load_default_package() only creates a package reference. Asset access occurs later when model loading resolves package files. from_pretrained(path_or_uri) accepts a local package or supported fsspec-style URI, including NGC, Hugging Face, and S3 forms. Explain cache and licensing boundaries before any later load: Earth2Studio's Apache-2.0 license does not license third-party checkpoints or datasets, and public access does not remove provider terms or credential requirements.

4. Return a handoff

Return:

• normalized task and runtime facts, including unknowns;
• selected package source, exact extras, and why broader extras were rejected;
• a small model/data shortlist with API class names, required variables, lexicon evidence, hardware fit, and unresolved access/license limits;
• one to three examples/patterns and the candidate IO backend;
• import/environment check results and the next user-run command;
• explicit omissions: no inference, remote data fetch, checkpoint download, serving, or exhaustive catalog claim.

When an import, Python, CUDA, extra conflict, source lexicon, grid, or access condition cannot be proven locally, label it as an unresolved gap and give the smallest read-only check that would resolve it.