diff --git a/.mcp.json b/.mcp.json index 76317c8..ab465dc 100644 --- a/.mcp.json +++ b/.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": { diff --git a/README.md b/README.md index c89e16d..3d011cb 100644 --- a/README.md +++ b/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 diff --git a/plugins/spedas-codex/.mcp.json b/plugins/spedas-codex/.mcp.json index 76317c8..ab465dc 100644 --- a/plugins/spedas-codex/.mcp.json +++ b/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": { diff --git a/plugins/spedas-codex/skills/README.md b/plugins/spedas-codex/skills/README.md new file mode 100644 index 0000000..7f42086 --- /dev/null +++ b/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 /skills --clean +``` + +Then: + +1. connect the Agent Kit MCP server; +2. discover the shared skill catalog through `spedas-skill://index` and + `spedas-skill://skills/`; +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. diff --git a/plugins/spedas-codex/skills/pyspedas-load-planning/SKILL.md b/plugins/spedas-codex/skills/pyspedas-load-planning/SKILL.md new file mode 100644 index 0000000..024eb4e --- /dev/null +++ b/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. diff --git a/plugins/spedas-codex/skills/spedas-heritage-vocabulary/SKILL.md b/plugins/spedas-codex/skills/spedas-heritage-vocabulary/SKILL.md new file mode 100644 index 0000000..c735372 --- /dev/null +++ b/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. diff --git a/plugins/spedas-codex/skills/spedas-skills-index/SKILL.md b/plugins/spedas-codex/skills/spedas-skills-index/SKILL.md index 9972a9c..b54bdf6 100644 --- a/plugins/spedas-codex/skills/spedas-skills-index/SKILL.md +++ b/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` | diff --git a/plugins/spedas-codex/skills/tplot-data-lifecycle/SKILL.md b/plugins/spedas-codex/skills/tplot-data-lifecycle/SKILL.md new file mode 100644 index 0000000..87a7671 --- /dev/null +++ b/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. diff --git a/skills/README.md b/skills/README.md new file mode 100644 index 0000000..7f42086 --- /dev/null +++ b/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 /skills --clean +``` + +Then: + +1. connect the Agent Kit MCP server; +2. discover the shared skill catalog through `spedas-skill://index` and + `spedas-skill://skills/`; +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. diff --git a/skills/pyspedas-load-planning/SKILL.md b/skills/pyspedas-load-planning/SKILL.md new file mode 100644 index 0000000..024eb4e --- /dev/null +++ b/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. diff --git a/skills/spedas-heritage-vocabulary/SKILL.md b/skills/spedas-heritage-vocabulary/SKILL.md new file mode 100644 index 0000000..c735372 --- /dev/null +++ b/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. diff --git a/skills/spedas-skills-index/SKILL.md b/skills/spedas-skills-index/SKILL.md index 9972a9c..b54bdf6 100644 --- a/skills/spedas-skills-index/SKILL.md +++ b/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` | diff --git a/skills/tplot-data-lifecycle/SKILL.md b/skills/tplot-data-lifecycle/SKILL.md new file mode 100644 index 0000000..87a7671 --- /dev/null +++ b/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.