> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ionworks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Coding agents

> Install the Ionworks agentic toolkit in Claude Code, Codex, Cursor, Gemini CLI, or Copilot — skills for data ingest, cells, simulations, and pipelines.

The [Ionworks Agentic Toolkit](https://github.com/ionworks/ionworks-skills)
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

<CardGroup cols={2}>
  <Card title="install" icon="download">
    Installing the SDK, configuring `IONWORKS_API_KEY`, verifying the install,
    upgrading, troubleshooting auth and proxy errors.
  </Card>

  <Card title="discover-api" icon="compass">
    Always call `client.capabilities()` and `client.schema(name)` first so
    later steps don't guess endpoint shapes.
  </Card>

  <Card title="process-data" icon="arrow-right-arrow-left">
    Convert raw cycler data (MATLAB, CSV, JSON, vendor exports) into the
    platform's parquet + JSON hierarchy or the portable BDF format.
  </Card>

  <Card title="validate-data" icon="circle-check">
    Validate processed data against the platform's authoritative schemas and
    strict measurement checks before upload — schema, parquet, and domain
    validators in one gate.
  </Card>

  <Card title="upload-data" icon="cloud-arrow-up">
    Upload time-series, file, and properties measurements. When to use each
    measurement type.
  </Card>

  <Card title="manage-cells" icon="layer-group">
    Create and query cell specifications, instances, and measurements.
    Parent/child relationships across the cells domain.
  </Card>

  <Card title="run-simulations" icon="play">
    Run electrochemical simulations with UCP protocols, design-of-experiments
    sweeps, and retrieve results.
  </Card>

  <Card title="sim-results" icon="chart-line">
    Fetch and analyse simulation output — time-series and step DataFrames,
    SOC, DCIR, step identification, plotting, and the per-step
    capacity-reset caveat.
  </Card>

  <Card title="run-simple-pipelines" icon="bolt">
    Fire-and-forget single datafit or validation runs via `SimplePipeline` —
    submit a config, poll for completion, retrieve the result.
  </Card>

  <Card title="manage-projects" icon="folder-tree">
    Organize work across projects, studies, models, parameterized models, and
    optimizations.
  </Card>

  <Card title="build-data-report" icon="file-chart-column">
    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.
  </Card>
</CardGroup>

## 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.

```text theme={null}
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.
```

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

## 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`](https://www.npmjs.com/package/skills) CLI from
[vercel-labs/skills](https://github.com/vercel-labs/skills). It auto-detects
your agent and installs to the right directory:

```bash theme={null}
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:

```bash theme={null}
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:

<Steps>
  <Step title="Clone the public skills repo">
    ```bash theme={null}
    git clone https://github.com/ionworks/ionworks-skills.git ~/ionworks-skills
    ```
  </Step>

  <Step title="Create a marketplace directory that points at it">
    ```bash theme={null}
    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
    ```
  </Step>

  <Step title="Register the marketplace and install the plugin">
    ```bash theme={null}
    codex plugin marketplace add ~/ionworks-marketplace
    codex plugin add ionworks@ionworks
    ```
  </Step>
</Steps>

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:

```bash theme={null}
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:

```python theme={null}
from anthropic.agents import Skill

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

### Manual

Clone the [repo](https://github.com/ionworks/ionworks-skills) 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

<Steps>
  <Step title="Install the skills">
    Use the paste-in prompt above, or `npx skills add ionworks/ionworks-skills -g`.
  </Step>

  <Step title="Install the Python SDK">
    In the environment your agent will execute code in:

    ```bash theme={null}
    uv add ionworks-api    # or: pip install ionworks-api
    ```

    See the [Python API client](/api-client) page for details.
  </Step>

  <Step title="Export your API key">
    Get one from your
    [account settings](https://app.ionworks.com/dashboard/account), then:

    ```bash theme={null}
    export IONWORKS_API_KEY="iwk_..."
    ```
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Requirements

* Python 3.12+ in the environment the agent will execute code
* [`ionworks-api`](https://pypi.org/project/ionworks-api/) — the Python SDK
* Optional: [`ionworksdata`](https://pypi.org/project/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`.

<Note>
  Source code, full skill text, and releases live at
  [github.com/ionworks/ionworks-skills](https://github.com/ionworks/ionworks-skills).
</Note>