Sync Agent Kit 8e378953 foundation skills

.mcp.json

@@ -6,7 +6,7 @@
         "--with",
         "mcp>=1.26.0,<2",
         "--from",
-        "git+https://github.com/spedas/spedas_agent_kit.git@fb5d4005fc5870ac4b8a94c1221efca4703b1c3a",
+        "git+https://github.com/spedas/spedas_agent_kit.git@8e3789539feb0ce79fe112be17465b40f363696d",
         "spedas-agent-kit"
       ],
       "env": {

README.md

@@ -31,7 +31,7 @@ backend packages unless you are maintaining the MCP itself.
 
 - Codex CLI/runtime with MCP/plugin support.
 - `uvx` available on `PATH`.
-- Network access the first time `uvx` installs `spedas_agent_kit` from GitHub. This wrapper pins `spedas_agent_kit` to `fb5d4005fc5870ac4b8a94c1221efca4703b1c3a` and bounds the MCP protocol dependency as `mcp>=1.26.0,<2`.
+- Network access the first time `uvx` installs `spedas_agent_kit` from GitHub. This wrapper pins `spedas_agent_kit` to `8e3789539feb0ce79fe112be17465b40f363696d` and bounds the MCP protocol dependency as `mcp>=1.26.0,<2`.
 
 ## Quick smoke prompt
 
@@ -245,7 +245,7 @@ The runtime smoke isolates SPEDAS data caches and falls back to temporary
 important in Codex sandboxes and CI. First runs may be slow because `uvx` resolves
 the pinned `spedas_agent_kit` commit from GitHub. Expected default smoke evidence
 is `ok: true`, a `tool_count` of at least the 13 base tools (optional tiers may
-add more), a `resource_count` of at least 61, empty `missing_core_tools`,
+add more), a `resource_count` of at least 64, empty `missing_core_tools`,
 `missing_skill_resources`, and `missing_preset_resources` lists, and readable
 `spedas-skill://index`, `spedas-skill://skills/spedas-workflow`,
 `spedas-preset://schemas/reproduction_provenance`, and

plugins/spedas-codex/.mcp.json

@@ -6,7 +6,7 @@
         "--with",
         "mcp>=1.26.0,<2",
         "--from",
-        "git+https://github.com/spedas/spedas_agent_kit.git@fb5d4005fc5870ac4b8a94c1221efca4703b1c3a",
+        "git+https://github.com/spedas/spedas_agent_kit.git@8e3789539feb0ce79fe112be17465b40f363696d",
         "spedas-agent-kit"
       ],
       "env": {

plugins/spedas-codex/skills/README.md

@@ -0,0 +1,27 @@
+# SPEDAS Agent Kit shared skills
+
+These are the canonical shared workflow skills for the SPEDAS Agent Kit. Runtime
+wrappers such as `spedas_claude`, `spedas_codex`, and future OpenCode/Cursor
+packages should stay thin and package/sync these skills rather than owning
+scientific workflow logic independently.
+
+## Runtime integration workflow
+
+The packaged skills are one half of the runtime-neutral Agent Kit contract. The
+other half is the MCP server and resource surface. Runtime wrappers should follow
+the workflow in [`docs/examples/agent_kit_integration_workflow.md`](/docs/examples/agent_kit_integration_workflow.md). To materialize the canonical skill set into a runtime wrapper, use:
+
+```bash
+python scripts/export_packaged_skills.py --target <runtime-plugin>/skills --clean
+```
+
+Then:
+
+1. connect the Agent Kit MCP server;
+2. discover the shared skill catalog through `spedas-skill://index` and
+   `spedas-skill://skills/<skill-name>`;
+3. run the canonical SPEDAS sequence from `docs/examples/agent_workflow.md`:
+   search/plan -> browse/load/parameters -> bundle -> fetch/compute ->
+   artifact/provenance summary;
+4. keep Claude Code, Codex, OpenCode, Claude Science, and future wrappers thin by
+   consuming this shared MCP + skill layer rather than copying scientific logic.

plugins/spedas-codex/skills/pyspedas-load-planning/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: pyspedas-load-planning
+description: Plan PySPEDAS mission/product/time data loads through Agent Kit's compact MCP surface, preserving time clipping, cache, variable naming, and provenance hygiene without adding mission-specific tools.
+---
+
+# PySPEDAS load planning
+
+Use this skill when a user asks for a SPEDAS/PySPEDAS data load, mission/product selection, quick-look data availability check, or a reproducible first-pass load plan. It translates PySPEDAS loader vocabulary into the SPEDAS Agent Kit workflow without expanding the default MCP tool surface.
+
+## MCP/default-surface boundary
+
+This skill adds no MCP tool. When documenting external routes, use the structured marker `external_runtime_route.not_an_mcp_tool: true`. PySPEDAS loader functions such as `pyspedas.themis.fgm`, `pyspedas.mms.fgm`, `pyspedas.omni.data`, `pyspedas.kyoto.dst`, or `pyspedas.noaa.noaa_load_kp` are **external runtime routes** and are `not_an_mcp_tool` unless a future Agent Kit tool explicitly exposes them. For MCP-only clients, route through the compact Agent Kit surface:
+
+1. `spedas_overview()` when uncertain.
+2. `create_spedas_analysis_bundle(...)` for a run directory and `provenance/run.json`.
+3. `search_spedas_data_sources(...)` or `browse_data_sources(...)` for source discovery.
+4. `plan_spedas_observation(...)` before fetching.
+5. `browse_data_parameters(...)`, `load_data_source(...)`, `fetch_data_product(...)`, and `manage_data_cache(...)` only after the plan is bounded.
+
+## Loader contract to preserve
+
+| PySPEDAS concept | Planning rule for agents |
+|---|---|
+| `trange` | Use a narrow, explicit UTC range. Do not let an exploratory request become a multi-day fetch unless the user asks. |
+| `time_clip=True` | Prefer or explicitly discuss `time_clip=True`; PySPEDAS can load whole CDF spans around a requested time range. |
+| `downloadonly` | Use `downloadonly` or Agent Kit plan/cache discovery for preflight provenance when data volume or source availability is uncertain. |
+| `notplot` | Use `notplot` or an Agent Kit compact metadata route when the next step is inspection, not plotting; avoid dumping arrays into chat. |
+| `no_update` | Use `no_update` / cache-only validation for reproducible tests, CI, and cold-cache caveats. |
+| `prefix` / `suffix` | Require run-scoped prefixes or suffixes when loading overlapping missions/products to avoid tplot name collisions. |
+| `varformat` / `varnames` | Request only the variables needed for the science question. Record the variable selection in provenance. |
+| `level` / `datatype` / `probe` / `instrument` | Treat these as science choices, not defaults to guess silently. If uncertain, browse or ask; for autonomous work, choose a documented minimal product and label it. |
+| `get_support_data` | Include support data only when the analysis requires it; otherwise keep the first-pass load compact. |
+
+## Planning procedure
+
+1. **Restate the science intent.** Identify mission, target interval, coordinate/context needs, and expected artifact: table, plot, CDF/CSV, or analysis bundle.
+2. **Create or reuse an analysis bundle.** Prefer `create_spedas_analysis_bundle(...)`; update `provenance/run.json` after every real load, derived variable, plot, or caveat.
+3. **Select the source route.** Prefer Agent Kit's unified route. Use external PySPEDAS only when the required loader is not yet represented by Agent Kit discovery/fetch tools, and mark that route as `not_an_mcp_tool`.
+4. **Make the load bounded.** Include `trange`, product/instrument/datatype, variable subset, `time_clip=True` or an explicit reason not to clip, cache policy, and output directory.
+5. **Plan before fetch.** Use discovery and planning calls first; fetch only the smallest interval/product that answers the question.
+6. **Preserve provenance.** Record source type, mission/product, loader-like options, cache mode, variable names, and output artifact paths. Do not paste raw tplot arrays.
+
+## Fast first-pass patterns
+
+- **OMNI/Kyoto/NOAA indices:** small bounded intervals are good smoke tests. Use the geomagnetic/overview skill for Dst/AE/Kp/SYM-H context, then write artifact summaries and caveats.
+- **THEMIS FGM/state:** choose probes and instrument/datatype deliberately; prefer one probe or a short multi-probe interval before expanding.
+- **MMS FGM/MEC/FPI:** start with FGM/MEC overview or cache-only planning. Burst/FPI/particle products can be large; hand off to dedicated MMS/particle skills when needed.
+- **PSP/Solar Orbiter:** keep heliophysics intervals narrow and cite coordinate/frame assumptions before combining with SPICE geometry.
+
+## Provenance checklist
+
+Every real load plan or execution should leave enough grain for another agent to reproduce it:
+
+- Mission/source and dataset/product identifiers.
+- Requested `trange` and actual clipped range.
+- Loader-like options: `time_clip=True`, `downloadonly`, `notplot`, `no_update`, `prefix`/`suffix`, `varnames`/`varformat`, support-data policy.
+- Cache/source state: cold cache, cache-only, public archive rate limit, authentication caveat.
+- Artifact paths: downloaded files, compact metadata JSON, figures, exported tables, and `provenance/run.json`.
+- Known limitations and whether the route was Agent Kit MCP, packaged resource, or external PySPEDAS runtime.

plugins/spedas-codex/skills/spedas-heritage-vocabulary/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: spedas-heritage-vocabulary
+description: Translate IDL SPEDAS, PySPEDAS, tplot, GUI plugin, and SPEDAS-J vocabulary into coherent Agent Kit skills/resources while marking external routines as not MCP tools.
+---
+
+# SPEDAS heritage vocabulary bridge
+
+Use this skill when mining IDL SPEDAS, PySPEDAS, SPEDAS-J, GUI/plugin metadata, or legacy examples for Agent Kit content. It keeps heritage terminology useful without importing IDL implementation or telling MCP-only clients to call routines that are not Agent Kit tools.
+
+## Boundary rule
+
+Use the structured marker `external_runtime_route.not_an_mcp_tool: true` for examples or route objects. IDL `.pro` routines and PySPEDAS/PyTplot functions are source evidence or external runtime routes unless Agent Kit exposes a current MCP tool. Mark them as `not_an_mcp_tool` when writing skills. The Agent Kit user-facing path is: skill/resource guidance -> compact MCP planning/loading/geometry/cache tools -> artifact paths and provenance.
+
+## Vocabulary map
+
+| Heritage term | Agent Kit interpretation |
+|---|---|
+| IDL `tplot`, PyTplot `tplot` | Plotting/export workflow; backend writes figure artifacts, chat reports paths and compact stats. |
+| IDL `STORE_DATA` / `GET_DATA`, PySPEDAS `store_data` / `get_data` | tplot variable lifecycle; inspect metadata/shape/coords/units before analysis. |
+| `CDF`, `netCDF`, `tplot_save`, `tplot_restore`, ASCII export | Artifact formats; record paths, hashes, source products, and variable lists. |
+| `spd_download`, CDAWeb, HAPI | Data-source routes; prefer Agent Kit discovery/planning/cache tools, with external PySPEDAS fallback labeled. |
+| `cotrans`, `FAC`, `LMN`, `MVA`, `GSE/GSM/SM/GEO/J2000` | Coordinate/frame assumptions; route to existing geometry/rotation/LMN skills and cite provenance. |
+| MMS/THEMIS/PSP/ERG loader names | Mission/product vocabulary; do not create one MCP tool per loader. Use skills/resources to choose products and bounded intervals. |
+| GUI plugin `project`, `load_data`, `config`, `menu`, `data_processing`, `about` | Metadata schema for translating plugins into Agent Kit skills/resources: what it loads, options, menus/intents, processing steps, caveats. |
+| SPEDAS-J / ERG / SuperDARN / IUGONET plugins | Domain source evidence and advanced external routes requiring human/domain review before first-class Agent Kit claims. |
+| IDL-vs-PySPEDAS validation | Parity methodology and golden tests; actual validators belong in backend/CI artifacts. |
+
+## Plugin-to-skill translation
+
+When a SPEDAS plugin or example is considered for Agent Kit, extract this minimum metadata:
+
+1. **Project/domain:** mission, instrument, ground network, model, or service.
+2. **Load route:** preferred Agent Kit MCP route, or external PySPEDAS/IDL route marked `not_an_mcp_tool`.
+3. **Options:** time range, probe/station, level/datatype, cadence, coordinates, support data, cache policy.
+4. **Science intent:** what question this enables, and which existing skill should consume the output.
+5. **Artifacts:** expected files/plots/tables and how to update `provenance/run.json`.
+6. **Review owner:** whether this needs mission/domain expert review, IDL parity validation, or human approval.
+
+## Compatibility and parity checklist
+
+- Cite evidence paths or official docs; do not rely on routine names alone.
+- Distinguish vocabulary translation from executable support.
+- Prefer one composable skill over many thin loader-name skills.
+- Preserve public names carefully: `spedas_agent_kit` is the product; older `spedas_mcp` names are historical unless kept as compatibility aliases.
+- For IDL/PySPEDAS parity claims, record variable mappings, tolerances, time clipping, coordinate frame, units, and known archive/cache differences.
+- For SPEDAS-J/ERG/IUGONET/SuperDARN content, mark maturity and domain-review caveats before surfacing to ordinary users.
+
+## Do not do this
+
+- Do not tell a naive MCP client to call `pyspedas.*`, `tplot_names`, `store_data`, `twavpol`, `neutral_sheet`, `cotrans`, `spd_download`, or an IDL `.pro` routine as if it were an Agent Kit MCP tool.
+- Do not duplicate every IDL/PySPEDAS loader into Agent Kit. Use skills/resources to route intent; add backend support only when repeated workflows prove the generic surface inadequate.
+- Do not import GUI/plugin code as a runtime dependency merely because its menu vocabulary is useful.

plugins/spedas-codex/skills/spedas-skills-index/SKILL.md

@@ -43,6 +43,9 @@ Low-level / source-specific compat tools exist for maintenance only — skills d
 | ERG/Arase radiation-belt, wave-particle, PWE/MGF/particle, or ground-conjugate ISEE/OMTI/MAGDAS route scout | `erg-arase-radiation-belt-waves` | `spedas_overview`; use this skill to choose `pyspedas.erg.*` / CDAWeb satellite routes, and keep ground routes labeled PySPEDAS-only |
 | Standard mission overview plot, geomagnetic-index context, GOES XRS operational storm context, THEMIS FGM/ESA substorm/dipolarization proxy, or RBSP MagEIS/REPT radiation-belt overview | `overview-geomagnetic-indices` | `spedas_overview` |
 | To know what data/sources exist at all | `spedas-workflow` | `spedas_overview` |
+| Plan a PySPEDAS mission/product/time data load with `time_clip=True`, cache, `downloadonly`, `notplot`, and provenance hygiene | `pyspedas-load-planning` | `create_spedas_analysis_bundle` |
+| Manage tplot variables from load through inspect, derive, plot/export, and cleanup without raw-array chat output | `tplot-data-lifecycle` | `create_spedas_analysis_bundle` |
+| Translate IDL SPEDAS / PySPEDAS / plugin vocabulary into Agent Kit skills/resources while marking external routines as `not_an_mcp_tool` | `spedas-heritage-vocabulary` | `spedas_overview` |
 
 | Trace a spacecraft to its ionospheric footpoint / magnetic-equator (conjugacy, L-shell) | `field-line-footpoint` | `create_spedas_analysis_bundle` |
 | Quick-look 1-D power spectral density (PSD slope/peak) of an interval | `power-spectral-density` | `create_spedas_analysis_bundle` |

plugins/spedas-codex/skills/tplot-data-lifecycle/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: tplot-data-lifecycle
+description: Manage PySPEDAS/tplot variable state as an artifact-first lifecycle from load to inspect, derive, plot, export, and cleanup while avoiding raw-array chat output and name collisions.
+---
+
+# tplot data lifecycle
+
+Use this skill when a workflow mentions tplot variables, PyTplot, IDL SPEDAS `STORE_DATA` / `GET_DATA`, PySPEDAS `store_data` / `get_data`, plotting, export, or variable cleanup. The goal is to keep global-ish tplot state understandable and reproducible inside an Agent Kit run.
+
+## MCP/default-surface boundary
+
+When documenting tplot runtime routes, use the structured marker `external_runtime_route.not_an_mcp_tool: true`. `tplot_names`, `store_data`, `get_data`, `del_data`, `tplot`, `tplotxy`, `cdf_to_tplot`, `tplot_save`, and related routines are PySPEDAS/PyTplot runtime routines, not default Agent Kit MCP tools. Treat them as `not_an_mcp_tool` unless a current Agent Kit tool explicitly exposes the action. MCP clients should ask Agent Kit to plan/load/export/plot through existing tools and should receive compact metadata plus artifact paths.
+
+## Lifecycle model
+
+1. **Load or create variables.** Use a bounded plan and run-scoped `prefix` / `suffix` so variable names reveal mission, product, and interval.
+2. **List and inspect.** Record names, shapes, time span, cadence, coordinate metadata, units, support-data status, and fill values. Do not paste raw arrays.
+3. **Normalize metadata.** Preserve or set coordinate systems and units before rotations, LMN/MVA, spectra, or particle calculations.
+4. **Derive variables.** Copy/rename before destructive operations; name derived products with method and frame, e.g. `mms1_fgm_gsm_lmn_batch1`.
+5. **Plot/export.** Figures, CDF/CSV/JSON summaries, and notebook snippets are artifacts. Return paths, hashes, variable lists, and compact stats.
+6. **Cleanup or checkpoint.** Delete scratch variables only after exported artifacts and `provenance/run.json` capture what was done.
+
+## Inspection checklist
+
+For each important tplot variable, capture:
+
+- Variable name and source product.
+- Time range after clipping and number of samples.
+- Data shape and component labels.
+- Units and coordinate frame (`GSE`, `GSM`, `SM`, `FAC`, `LMN`, `RTN`, or unknown).
+- Whether it is original, support data, or derived.
+- Fill-value/de-spike/interpolation/smoothing status.
+- Artifact path for any plot or exported table.
+
+## Name-collision and state hygiene
+
+- Use `suffix`/`prefix` at load time when loading repeated intervals or multiple probes.
+- Never assume a variable name is unique across a long agent session; list first.
+- Prefer copy/derive names over in-place mutation for science products.
+- Use bundle-local export paths instead of relying on lingering interactive tplot state.
+- For CI or review, prefer `notplot`/metadata summaries and no-update/cache-only validation.
+
+## Plotting and export discipline
+
+A plot request should produce a file, not a chat-sized data dump. Ask the backend/MCP layer for a figure or export artifact and report:
+
+- Path and file type.
+- Variables plotted/exported.
+- Plot options that affect interpretation: y/z log scale, spectrogram, legend names, highlights, limits, coordinate frame.
+- Any dropped/fill/interpolated data and whether the interval was clipped.
+
+## Downstream skill handoff
+
+Use this lifecycle before calling focused science skills:
+
+- `timeseries-cleaning` for despiking, gap handling, smoothing, and interpolation.
+- `coordinate-frame-tour`, `apply-rotation-matrix`, `boundary-minimum-variance`, or `magnetopause-lmn-analysis` when coordinate/frame assumptions matter.
+- `power-spectral-density`, `wave-polarization`, or `spectral-cross-coherence` after cadence and gap checks.
+- `particle-velocity-slice` and `pitch-angle-distribution` only after particle product shape, units, and calibration caveats are explicit.

skills/README.md

@@ -0,0 +1,27 @@
+# SPEDAS Agent Kit shared skills
+
+These are the canonical shared workflow skills for the SPEDAS Agent Kit. Runtime
+wrappers such as `spedas_claude`, `spedas_codex`, and future OpenCode/Cursor
+packages should stay thin and package/sync these skills rather than owning
+scientific workflow logic independently.
+
+## Runtime integration workflow
+
+The packaged skills are one half of the runtime-neutral Agent Kit contract. The
+other half is the MCP server and resource surface. Runtime wrappers should follow
+the workflow in [`docs/examples/agent_kit_integration_workflow.md`](/docs/examples/agent_kit_integration_workflow.md). To materialize the canonical skill set into a runtime wrapper, use:
+
+```bash
+python scripts/export_packaged_skills.py --target <runtime-plugin>/skills --clean
+```
+
+Then:
+
+1. connect the Agent Kit MCP server;
+2. discover the shared skill catalog through `spedas-skill://index` and
+   `spedas-skill://skills/<skill-name>`;
+3. run the canonical SPEDAS sequence from `docs/examples/agent_workflow.md`:
+   search/plan -> browse/load/parameters -> bundle -> fetch/compute ->
+   artifact/provenance summary;
+4. keep Claude Code, Codex, OpenCode, Claude Science, and future wrappers thin by
+   consuming this shared MCP + skill layer rather than copying scientific logic.