Coding agents

The Ionworks Agentic Toolkit gives coding agents the context they need to drive Ionworks Studio end-to-end: ingest cycling data, organize cell characterization, run simulations, and structure research projects — without hand-holding on endpoints, schemas, or conventions. Each skill is a single SKILL.md file with YAML frontmatter. Any agent that understands the skill convention — Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Anthropic SDK agents, and others — can load them.

What you get

install

Installing the SDK, configuring IONWORKS_API_KEY, verifying the install, upgrading, troubleshooting auth and proxy errors.

discover-api

Always call client.capabilities() and client.schema(name) first so later steps don’t guess endpoint shapes.

process-data

Convert raw cycler data (MATLAB, CSV, JSON, vendor exports) into the platform’s parquet + JSON hierarchy or the portable BDF format.

validate-data

Validate processed data against the platform’s authoritative schemas and strict measurement checks before upload — schema, parquet, and domain validators in one gate.

upload-data

Upload time-series, file, and properties measurements. When to use each measurement type.

manage-cells

Create and query cell specifications, instances, and measurements. Parent/child relationships across the cells domain.

run-simulations

Run electrochemical simulations with UCP protocols, design-of-experiments sweeps, and retrieve results.

sim-results

Fetch and analyse simulation output — time-series and step DataFrames, SOC, DCIR, step identification, plotting, and the per-step capacity-reset caveat.

run-simple-pipelines

Fire-and-forget single datafit or validation runs via SimplePipeline — submit a config, poll for completion, retrieve the result.

manage-projects

Organize work across projects, studies, models, parameterized models, and optimizations.

build-data-report

Build a comprehensive multi-section data analysis report (rate capability, DCIR, OCV, GITT, entropic, aging, gap analysis) for cells whose measurements live on the platform — markdown + PDF.

Quick install — paste this into your coding agent

Drop the block below into Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, or any agent with shell access. It auto-detects which agent it’s running in, picks the right install path, verifies the SDK is set up, and tells you what’s missing.

Install the Ionworks agentic toolkit for me.

Fetch https://raw.githubusercontent.com/ionworks/ionworks-skills/main/README.md
and follow the install instructions there. Pick the path that matches the
agent you (the assistant) are running in — Claude Code, Codex, Cursor,
Gemini CLI, GitHub Copilot, or another.

After install, verify the skills are accessible, make sure `ionworks-api` is in
the Python env I'll be running code in, and check whether IONWORKS_API_KEY
is set in my shell. If the key is missing, tell me to grab one from
https://app.ionworks.com/dashboard/account — don't try to mint one yourself.

Finally, invoke the `install` skill to run the SDK's self-check, then report
what you did and anything I still need to do by hand.

The agent fetches the canonical README on every run, so install instructions stay in sync as new agents are supported.

Manual install paths

If you’d rather drive it yourself, pick the path that matches your agent.

Any agent (auto-detect)

The fastest path uses the skills CLI from vercel-labs/skills. It auto-detects your agent and installs to the right directory:

npx skills add ionworks/ionworks-skills        # project-level
npx skills add ionworks/ionworks-skills -g     # user-level

Add --all to install every skill non-interactively, or --skill <name> to install just one. npx skills update -g keeps the install in sync with new releases. This path natively covers Cursor (skills land in ~/.cursor/skills/) and GitHub Copilot for VS Code and the CLI (Copilot auto-discovers SKILL.md from .agents/skills/ and .github/skills/ — no extra config).

Claude Code

Native plugin install — also brings in the slash commands and the SessionStart skill-index hook:

claude plugin marketplace add ionworks/ionworks-skills
claude plugin install ionworks@ionworks

Verify with claude plugin list — the entry should show Status: ✔ enabled.

Codex

Codex needs a marketplace directory that references one or more plugins. This repository ships .codex-plugin/plugin.json but not a marketplace manifest, so install via a small local scaffold:

Clone the public skills repo

git clone https://github.com/ionworks/ionworks-skills.git ~/ionworks-skills

Create a marketplace directory that points at it

mkdir -p ~/ionworks-marketplace/.agents/plugins ~/ionworks-marketplace/plugins
ln -sfn ~/ionworks-skills ~/ionworks-marketplace/plugins/ionworks
cat > ~/ionworks-marketplace/.agents/plugins/marketplace.json <<'JSON'
{
  "name": "ionworks",
  "interface": {"displayName": "Ionworks"},
  "plugins": [
    {
      "name": "ionworks",
      "source": {"source": "local", "path": "./plugins/ionworks"},
      "policy": {"installation": "AVAILABLE", "authentication": "ON_INSTALL"},
      "category": "Science"
    }
  ]
}
JSON

codex plugin marketplace add ~/ionworks-marketplace
codex plugin add ionworks@ionworks

Verify with codex plugin list — the entry should show (installed, enabled).

Gemini CLI

Gemini CLI picks up extensions that ship a gemini-extension.json at the repo root. Install via the Gemini CLI extension command:

gemini extensions install https://github.com/ionworks/ionworks-skills

After install, every skill is loaded into every Gemini session via GEMINI.md as passive context. Ask Gemini to use an Ionworks skill by name — e.g. “Use the discover-api skill” — and the loaded context will guide it.

Claude Agent SDK / API

Point your agent at any SKILL.md file directly:

from anthropic.agents import Skill

skill = Skill(path="ionworks-skills/skills/install/SKILL.md")

Manual

Clone the repo and copy any skills/<skill-name>/SKILL.md into your agent’s skills or context directory. The frontmatter description acts as the trigger; the body is general-purpose guidance the agent reads when activated.

Quick start

Install the skills

Use the paste-in prompt above, or npx skills add ionworks/ionworks-skills -g.

Install the Python SDK

In the environment your agent will execute code in:

uv add ionworks-api    # or: pip install ionworks-api

See the Python API client page for details.

Export your API key

Get one from your account settings, then:

export IONWORKS_API_KEY="iwk_..."

Verify with the install skill

Ask your agent something like “Use the ionworks install skill to verify my setup” — it will invoke install, then discover-api, and confirm the connection.

Requirements

Python 3.12+ in the environment the agent will execute code
ionworks-api — the Python SDK
Optional: ionworksdata for process-data workflows
Optional: ionworkspipeline for pipeline-based parameterization (licensed — contact Ionworks)

Model capability

The skills assume the agent can read Markdown, follow multi-step procedures, call a Python SDK, and handle JSON/parquet data. They’ve been authored and tested against Claude Sonnet / Opus and should work with any comparable frontier model. Smaller local models may struggle with the multi-step data-processing workflows in process-data and run-simulations.

Source code, full skill text, and releases live at github.com/ionworks/ionworks-skills.

Get Started

Core Concepts

Data

Build

Pipelines

Simulate

Optimize

What you get

install

discover-api

process-data

validate-data

upload-data

manage-cells

run-simulations

sim-results

run-simple-pipelines

manage-projects

build-data-report

Quick install — paste this into your coding agent

Manual install paths

Any agent (auto-detect)

Claude Code

Codex

Gemini CLI

Claude Agent SDK / API

Manual

Quick start

Requirements

Model capability

​What you get

install

discover-api

process-data

validate-data

upload-data

manage-cells

run-simulations

sim-results

run-simple-pipelines

manage-projects

build-data-report

​Quick install — paste this into your coding agent

​Manual install paths

​Any agent (auto-detect)

​Claude Code

​Codex

​Gemini CLI

​Claude Agent SDK / API

​Manual

​Quick start

​Requirements

​Model capability

What you get

Quick install — paste this into your coding agent

Manual install paths

Any agent (auto-detect)

Claude Code

Codex

Gemini CLI

Claude Agent SDK / API

Manual

Quick start

Requirements

Model capability