Data2story Pro

Data Journalist Agent (Data2Story)

Turn $ARGUMENTS into a blog. Orchestrates the roles below in sequence.

Orchestration rituals

Five process rules earned from real runs. Each is one rule + why it exists; follow them across every run regardless of topic.

• (D1) Candidate-image review loop. For any hero/cover image of a named person or specific real object, generate N candidates, then run a VLM (or human) review and select one — never ship the first render. Why: text2image of named people intermittently refuses outright and quality varies shot-to-shot, so a single render is a coin-flip; a small candidate pool plus a review step is the only reliable way to land a usable, correctly-identified image.
• (D2) Audit-before-finalize. Run the read-only multi-agent audit (provenance / repro / assets / IP lenses) to find every defect FIRST, collect them, and only THEN make one editing pass to fix them. Why: interleaving find-and-fix makes agents edit the same file against a moving target and re-introduce each other's defects; separating the finding phase from the fixing phase prevents that churn.
• (D3) Single owner of one big file. Parallel agents may produce data and assets concurrently, but exactly ONE agent writes index.html. Why: the HTML is one indivisible artifact; concurrent edits to it interleave and corrupt it, so it must have a single writer even when everything feeding it is parallel.
• (D4) Headless-verify-then-defer-render. Prove everything you can without a browser — node --check the scripts, recompute a known model output and compare, byte-compare each inline JSON island to its verify/ file — then hand the final visual/browser sign-off to the user. Why: deterministic checks catch the failures that don't need eyes cheaply and early, while genuine render correctness needs a real browser this harness can't drive, so the human does that last mile (see also the chart-width-0 class of bug, invisible to node shims).
• (D5) Verify-coexistence-with-zero-engine-edits. New interactive features layer on top of the frozen Verify engine (the in-page Inspector panel + verify/ artifacts); never edit the engine to make a feature fit. Why: the Verify layer is the paper's coding verifier and a hard gate — editing it to accommodate a feature risks silently breaking provenance, so features adapt to it, not the reverse.

The 7 teams

The newsroom is 7 teams (the paper's 7 canonical roles), staffed by 14 agents. Two teams are a single agent; five are a small team with a lead who coordinates one or more members. The folders stay flat and every Skill call resolves by the member's frontmatter name: — the teams are a coordination overlay, not a folder move. You (this orchestrator) are the top coordinator across all 7 teams.

| Team (paper role) | Lead | Members | Kind | |---|---|---|---| | Detective | Detective | + Scout | multi-agent | | Analyst | Analyst | + Imagineer | multi-agent | | Editor | Editor | + Copywriter | multi-agent | | Designer | Designer | + Interaction + Hero + Cinematographer | multi-agent | | Programmer | Programmer | — | single-lead | | Auditor | Auditor | + Critic (+ Playtester step) | multi-agent | | Inspector | Inspector | — | single-lead |

Each lead's SKILL.md carries a "Team coordination" section describing how it briefs and integrates its members; the member Skill calls below are mirrored in those sections so a member is never silently skipped. The cross-team checkpoints (the two gates and the Critic revision loop) are owned by this top orchestrator, not delegated into any team.

Setup

Resolve paths before doing anything:

• Never hard-code machine-local paths and never ask the user to export path variables.
• Resolve SKILL_DIR = the directory containing this SKILL.md (.../skills/data2story-pro)
• Resolve ARCHIVE_DIR = the ancestor directory that contains skills/ (two levels up from SKILL_DIR, i.e. SKILL_DIR/../..)
• Resolve DATA2STORY_ROOT = parent of ARCHIVE_DIR
• Commands below use symbolic placeholders such as ARCHIVE_DIR; replace them with resolved, quoted paths before running Bash.
• DATA_NAME = the dataset folder name (e.g. pick_a_card). In URL / IDEA mode it is taken from the DATA_DIR that Stage 0 — Input dispatch (below) resolves, so run Stage 0 before resolving PROJECT_DIR.
• DATA_DIR = the validated dataset folder, resolved by Stage 0 — Input dispatch below. It originates from one of: the existing path in $ARGUMENTS (DATA MODE, path); find-data's output folder (DATA MODE, URL); or ideation's output folder (IDEA MODE). For a bare dataset name with no Stage-0 acquisition, fall back to DATA2STORY_ROOT/data/{DATA_NAME}.
• TIMESTAMP = current time formatted as MMDD_HHMM (e.g. 0401_1618): date +%m%d_%H%M (run in bash)
• PROJECT_DIR = DATA2STORY_ROOT/project/{DATA_NAME}/blog_{MODEL}_{TIMESTAMP}
• Create PROJECT_DIR/, PROJECT_DIR/assets/, PROJECT_DIR/code/ — after Stage 0 has resolved DATA_DIR/DATA_NAME (immediate in path mode; after the Stage-0 acquisition in URL / IDEA mode).
• Write PROJECT_DIR/run_config.json = {"run_profile": "premium"} or {"run_profile": "fast"} from the Stage-0 Run profile decision (below). validate.py/generate_viewer.py read it; absent ⇒ premium.

> Windows: there is usually no python3 on PATH — run the python3 … commands in this skill as py (or py -3). Set PYTHONUTF8=1 (e.g. $env:PYTHONUTF8=1) to avoid GBK console errors when scripts print Unicode.

> Sibling-skill dependency. This skill requires the sibling skills frontend-design/ and dataviz-craft/ to live under the same skills/ parent (ARCHIVE_DIR/skills/). The Designer/Programmer/Auditor/Critic borrow their component recipes, design tokens, quality rubric, and dataviz craft from them via ../frontend-design/... and ../dataviz-craft/... relative paths. Deploy all three together — data2story-pro/ alone is incomplete; a clone missing either sibling will break the design/audit references. IDEA MODE additionally requires the sibling skills find-data/ and sparring-partner/ under the same skills/ parent: Stage 0's ideation sub-skill drives sparring-partner to converge a topic and find-data to acquire a real dataset. A clone missing either of these two can still run DATA MODE (a path or URL), but cannot run IDEA MODE (an empty/free-text idea).

Stage 0 — Input dispatch (data path · URL · idea)

Classify $ARGUMENTS before resolving DATA_DIR. This stage decides how DATA_DIR is obtained; every later stage (Detective → … → Inspector) is identical regardless of which branch ran. FIRST match wins:

1. Empty / whitespace → IDEA MODE (open by inviting the idea: "what do you want to tell a story about?").
2. An existing path on disk ($ARGUMENTS resolves to a file or directory) → DATA MODE. The current behavior, unchanged: set DATA_DIR to that path and proceed into the pipeline.
3. A data URL ($ARGUMENTS starts with http:// or https://) → DATA MODE via find-data url-mode. Run Skill find-data "" — it fetches the resource and validates it against the 4 completeness gates, producing a dataset folder. Set DATA_DIR to that folder and continue the pipeline.
4. Otherwise (free-text prose, not a path) → IDEA MODE.

Ambiguity guard. If $ARGUMENTS LOOKS like a path (contains a slash, a drive letter, or a file extension) but does NOT exist on disk, do one quick confirmation question instead of silently treating it as an idea — e.g. "that looks like a path but I can't find it; did you mean a dataset folder, or a topic to research?" — and branch on the answer.

IDEA MODE

Hand the user's idea to the ideation sub-skill, passing the raw $ARGUMENTS text verbatim and the resolved DATA2STORY_ROOT:

Skill ideation "" 

ideation runs the brainstorming dialogue (reusing sparring-partner) to converge the vague idea into one concrete data-story topic, then runs find-data to acquire a real, validated dataset — with a user checkpoint after each step — and returns exactly one of:

• DATA_DIR= — success. A story_brief.json will sit at /meta/story_brief.json. Set DATA_DIR and DATA_NAME from this folder and proceed into the EXISTING pipeline unchanged (Detective → … → Inspector). Nothing downstream differs.
• IDEATION_ABORTED: — the user aborted, or no adequate real dataset could be found. Halt gracefully with an honest one-line message that relays the reason. Do NOT run the pipeline, and do NOT fabricate data or a dataset to "succeed".

Run profile — Fast vs Premium (select ONCE, then commit)

Data2Story ships two committed profiles. Resolve the profile once, here at Stage 0, and write it to PROJECT_DIR/run_config.json; do not revisit it mid-run. A profile is a self-consistent bundle (which stages run AND the matching gate set), NOT a pile of per-stage toggles.

• premium (default) — the full 14-agent newsroom: verified media (Scout), interactive playgrounds (Imagineer + Interaction), an animated cover (Hero), a cinematic scroll (Cinematographer), titling (Copywriter), the Critic revision loop, and the full runnable verify layer (in-page panel + runnable Pyodide cells + a reproducible notebook). ~1–1.5 h. The flagship.
• fast (~15 min) — the 7 canonical roles only: Detective → Analyst → Editor → Designer (charts + static images, no media generation) → Programmer → Auditor → Inspector. Keeps the in-page traceability panel (click any claim → its code/source) but NOT the runnable cells / reproducible notebook. Skips Scout, Imagineer, Copywriter, Interaction, Hero, Cinematographer, and the Critic loop. The premium floors (mandatory cinematic / BGM / richness / engagement / runnable-verify / playtest) do not apply.

Resolve it:

1. If $ARGUMENTS contains --fast → fast; --premium → premium. Strip the flag from $ARGUMENTS before input dispatch. A headless/automated call with no flag defaults to premium.
2. Otherwise (interactive, no flag) → ask one AskUserQuestion: "Fast (~15 min — charts + static images, traceability only) or Premium (~90 min — the full cinematic/interactive flagship)?"
3. Write the choice to PROJECT_DIR/run_config.json as {"run_profile": "premium"} or {"run_profile": "fast"} right after PROJECT_DIR is created (Setup). validate.py and generate_viewer.py read this file; absent ⇒ premium, so the default and every automated call is the full flagship.

Each stage heading below is marked [premium] when the fast profile skips it; unmarked stages run in both.

Archival

Immediately after creating PROJECT_DIR, snapshot the current skills:

mkdir -p PROJECT_DIR/archival
cp -r ARCHIVE_DIR/skills PROJECT_DIR/archival/skills

This preserves the exact skill versions used for this run.

Tools available

All media tools route through OpenRouter. Set OPENROUTER_API_KEY before any generation call.

Media generation is the Designer's job, so the media tools (text2image, text2video, image2video, text2music, embeddings) live under SKILL_DIR/designer/scripts/openrouter-*/. The full list — default models and exact python3 ... invocations — is in [designer/references/tools.json](designer/references/tools.json); full per-tool docs are each tool's own SKILL.md under SKILL_DIR/designer/scripts/openrouter-*/. Note: text2music is for opt-in atmospheric sound-design / SFX (un-findable sounds — drones, textures, best-effort foley), NOT the front-of-blog BGM — the BGM must be a sourced real track (sourced_bgm, found by the Scout), never AI-composed.

Pipeline Overview

The pipeline is a single linear sequence that produces a traceable HTML blog from raw data:

DATA → Detective → Scout → Analyst → Imagineer → Editor → Copywriter → Designer → Interaction → Hero → Cinematographer → media-purpose + richness + cinematic-supply gates → Programmer → Auditor + Playtester → contract gate → Inspector verify.py (Stage 6.4 → verifier.json) → Critic (bounded loop, =4 AND >=1 dim >=5; re-runs Programmer + Auditor + validate.py + verify.py each round) → Inspector generate_viewer.py (Stage 7, REQUIRED terminal step — MUST exit 0) → final index.html (with the in-page Inspector panel) + verify/ artifacts

> Two profiles (set once at Stage 0). The sequence above is the premium flagship. The fast profile (~15 min) runs only the 7 canonical roles — Detective → Analyst → Editor → Designer (charts + static images) → Programmer → Auditor → Inspector — keeping the in-page traceability panel but skipping every stage whose heading is marked [premium] (Scout, Imagineer, Copywriter, Interaction, Hero, Cinematographer, the Critic loop) plus the runnable-verify cells + notebook. Its gate set drops the premium floors (cinematic / BGM / richness / engagement / playtest / runnable-verify) to match. Absent run_config.json ⇒ premium.

> The Imagineer (Stage 2.5) fans out candidate interactive concepts; the Editor curates them into the hero + supporting set; the Copywriter (Stage 3.5) re-titles the masthead + every section title + every figure/photo/table caption to a titling standard that kills the AI-tell patterns (strings only — names, never edits); the Interaction Engineer (Stage 4.5) builds that whole SET (not just one centerpiece); the Hero (Stage 4.6) crafts the animated cover; the Cinematographer (Stage 4.7) consumes that cover as its first scene (cin_00); the Playtester (a step inside the Auditor team at Stage 6) drives every built playground in a real browser before the contract gate.

> A run is INCOMPLETE — do NOT present it as finished — if the contract gate (validate.py) Section 7 reports any verify_* error, OR Section 15 reports any send_back_open / playtest_hard_unresolved, OR generate_viewer.py (Stage 7) exits nonzero. The verify layer is the paper's coding verifier; it is a hard pipeline gate, not an optional flourish, and "the panel and verify/ artifacts are mentioned as MANDATORY" is enforced by those deterministic checks, not by prose alone. A left-open detected defect (a Section-15 send_back_open / playtest_hard_unresolved) blocks flagship in the same class as a verify_* error.

Run each stage in order. Each stage reads the previous artifact(s) before starting. Do not proceed to the next stage until the current artifact is complete.

> Model tier (optional). The mechanical stages — the Programmer's HTML build and the Inspector's scripts (verify.py, generate_viewer.py) — are deterministic and run fine on a cheaper/faster model; the creative and analytical stages (Detective, Analyst, Editor, Designer, Interaction, Critic) benefit most from a strong model. Spend the budget where judgment matters.

The stages below are grouped under their team heading. The stage numbers, Input/Output, What, and Call lines are unchanged — run them in the same linear order regardless of grouping.

Detective team — context + verified media (lead: Detective; member: Scout)

Stage 1 — Detective

Input: DATA_DIR Output: PROJECT_DIR/detective.json What: Researches external context — background knowledge, domain history, related findings, why this data matters. Each finding gets a det_xx ID.

Stage 1.5 — Scout [premium]

Input: DATA_DIR, PROJECT_DIR/detective.json Output: PROJECT_DIR/scout.json, PROJECT_DIR/assets/scout_* What: Sources and verifies rich external media the Detective's background pass didn't cover — license-clean music for the front-of-blog BGM, high-value real photos/video of the story's key subjects, and the latest live status (timestamped, display-only). Every a

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: QinghongLin
• Source: QinghongLin/data2story-skill
• License: MIT
• Homepage: https://data2story.github.io/

Install and usage instructions live in the source repository linked above.