analyze-data

Category: Data & AI | Uploader: allenai | Downloads: 0 | Version: v1.0（Latest）
This skill should be used when the user asks to "analyze this dataset", "run datavoyager", "run data voyager", "explore this data", "what's in this CSV", "statistical analysis of", "find patterns in", or wants an AI-driven, code-executing analysis of a tabular dataset that answers a specific research question.
Changelog: Source: GitHub https://github.com/allenai/asta-plugins
Directory Structure

Current level: tree/main/plugins/asta-preview/skills/analyze-data/
📄 SKILL.md 7.0 KB
SKILL.md

---
name: analyze-data
description: This skill should be used when the user asks to "analyze this dataset", "run datavoyager", "run data voyager", "explore this data", "what's in this CSV", "statistical analysis of", "find patterns in", or wants an AI-driven, code-executing analysis of a tabular dataset that answers a specific research question.
metadata:
  internal: true
allowed-tools: Bash(asta auth login) Bash(asta auth status) Bash(asta analyze-data *) Bash(asta artifacts *) Bash(asta documents *) Bash(open *)
---

# Data Analysis

Uses the [DataVoyager](https://github.com/allenai/dv-core-asta-integration) agent (hosted on Cloud Run, accessed via `asta-gateway`) to run a multi-agent data-science pipeline: the agent writes and executes code against the caller's dataset(s) in a sandboxed notebook and answers a research question. Auth is `asta auth login`.

## Step 1 — Draft a tightened query

**Before asking the user anything**, analyze their request and the surrounding context (current project, conversation history, files they've been working on) to produce a **tightened analytical question** that:

- Names the specific dataset(s) that will be analyzed
- States what decision or insight the user is after, not just "analyze X"
- Is phrased as a question DataVoyager can actually answer with code

Examples:

- User says "look at this CSV" → inspect the file path, sample the top rows if possible, produce a concrete query like "Which columns in `sales_q3.csv` have the strongest correlation with quarterly revenue, controlling for region?"
- User says "what's in the titanic data" → "What features best predict survival in `titanic.csv`, and how do survival rates differ across passenger class and sex?"
- User gives a specific question with a specific dataset → echo it verbatim

## Step 2 — Confirm with one chat question

In chat (not `AskUserQuestion`), present:

> Proposed analysis:
> - **Dataset(s)**: `<path>` *(will be uploaded to your DataVoyager workspace)*
> - **Question**: **`<tightened>`**
>
> You can:
> - Reply **yes** / **go** to run as-is
> - Reply with edits (e.g. *"focus on just Q3"*, *"ignore missing values"*) and I'll revise the question
> - *(Only if `AskUserQuestion` is available)* Reply **interview** to refine the question through a form

Only include the **interview** bullet when the `AskUserQuestion` tool is available.

Wait for the user's response. Paths:

1. **Affirmative** ("yes", "go", "proceed", "looks good") → Step 4.
2. **Natural-language edit** → update the question, re-show the same prompt.
3. **"Interview" / "refine"** → Step 3 *(AskUserQuestion required; if unavailable, ask in chat instead)*.

**Never** ask the user to pre-upload the dataset. The skill handles the upload — see Step 4 — and the user just supplies the local file path.

## Step 3 — Optional interview (only when requested)

Fire one `AskUserQuestion` with:

1. **Question** — `<tightened>` vs `<alternative reframe>` (if you have one)
2. **Scope** — "focused (single hypothesis)" / "exploratory (multiple angles)"
3. **Extra context** — free-text "anything DataVoyager should know about the data?" (field meanings, known caveats)

Fold the answers back into the query string.

## Step 4 — Submit

A single `submit` call mints a session UUID, uploads the file(s) under `context/<uuid>/`, and starts the analysis. The response carries the task ID (`id`) and the session UUID (`contextId`); capture both for polling and any follow-ups.

```bash
asta analyze-data submit \
  --output "/tmp/analyze-data-$$.json" \
  "<confirmed question>" ./sales.csv ./regions.csv

TID=$(jq -r .id /tmp/analyze-data-$$.json)
CTX=$(jq -r .contextId /tmp/analyze-data-$$.json)
```

**Resumability.** `$CTX` identifies the DataVoyager session. To ask a follow-up against the same workspace, run `asta analyze-data submit --context-id "$CTX" '<follow-up question>' [<new-files>...]`. New files (if any) attach to the existing context; if no files are passed, the agent reuses what's already there. To start a clean session over the same datasets, omit `--context-id` and pass the files again.

## Step 5 — Poll

Don't foreground-poll in a loop (session blocks) and don't start individual `sleep 60`-then-check turns (harness blocks long leading sleeps). Instead, run the `poll` subcommand backgrounded — it exits on a terminal state and the harness will notify you when it finishes.

```bash
asta analyze-data poll "$TID" --output "/tmp/analyze-data-$TID.json"
```

Run with `run_in_background: true`. Status ticks go to stderr; the final Task JSON is written to `--output`. When the completion notification fires, read `/tmp/analyze-data-$TID.json` for the final payload.

While it's running, do not proactively check. Work on other things or wait — the notification is authoritative. If the user asks for a status check before the notification, only then tail the background task's stderr.

Terminal states:

- `completed` → Step 6
- `failed` → report `status.message` and stop
- `input-required` → relay to user, then `asta analyze-data send-message --task-id <ID> --context-id "$CTX" '<reply>'` and re-kick the polling loop

Runtime: highly variable (simple EDAs finish in a few minutes; multi-step modeling runs can take 20–40 min). Don't hard-fail before ~2 hours.

## Step 6 — Export and index

Hand off to the **Asta Artifacts** skill to export the task output (tables, plots, the notebook, any written analysis) and register each artifact with asta-documents. Pass `analyze-data` as the invoking skill and a slug derived from the analytical question; Asta Artifacts handles the path convention, manifest, and `index.yaml`.

## Step 7 — Summarize for the user

Present, in this order:

1. **Indexing + exploration paths** — one short block naming both ways to browse. Always include BOTH (the skill path for semantic search, the filesystem path for direct reading):

   > Indexed N artifacts in `.asta/analyze-data/<slug>/index.yaml`.
   > Explore via `asta documents search --summary='<concept>' --root=.asta/analyze-data/<slug>` or open the directory directly: `open <absolute-path-to-slug-dir>`

   Use the **absolute** path (e.g. `/Users/.../project/.asta/analyze-data/2026-04-23-…/`). Pick `<concept>` from a term central to the analysis (concrete, not generic — e.g. a column name, a model type).

2. **One-paragraph synthesis** — 2–4 sentences written fresh for this run. What's the headline finding? What did the data say vs. what did the user expect? Surface surprises, caveats, and whether the analysis answered the original question. This is discretionary — don't template it, read the output and synthesize.

3. **Table of key findings / charts** — one row per notable insight or figure: **finding** + **1–2 sentence detail** + (if applicable) **chart filename**.

Don't dump raw JSON. Don't repeat every step the agent took. Don't add a trailing "let me know if you'd like…" summary — the exploration block already tells the user how to keep going.

## References

- DataVoyager: <https://github.com/allenai/dv-core-asta-integration>
- A2A spec: <https://a2a-protocol.org/latest/specification/>
Comments 0
Latest | Hot
Please login before commenting.
Loading comments...
analyze-data

Directory Structure

SKILL.md

Report

Notice
