build-data-app
/build-data-app
Tworzy lub zmienia aplikację danych Holistics w jednym pliku HTML, który pyta zbiory danych przez SDK.
- Autor
- holistics ↗
- Repozytorium
- skills ↗
- Licencja
- Apache-2.0
- Ostatnia zmiana repozytorium
- 10.11.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 3
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 3
Brak sygnałów. Repozytorium zmienione 10.11.2026, bez odwołań do wycofanych modeli i API.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
Co robi i kiedy
Tworzy lub zmienia aplikację danych Holistics w jednym pliku HTML, który pyta zbiory danych przez SDK.
Oryginalny opis (EN)
Build or change a Holistics Data App, one self-contained HTML file that queries the user's datasets through the `Anfra` SDK global and renders them with its own HTML, CSS and JS. Use when the user asks for a Data App, or a custom page, report or interactive analysis over their datasets. Do NOT trigger for a one-off chart or data question.
Jak działa
- 1. Collect the datasets and the idea
- 2. Agree on the design
- Look and feel
- 3. Write the file
- 4. Hand over and iterate
Podgląd SKILL.md
---
name: build-data-app
description: Build or change a Holistics Data App, one self-contained HTML file that queries the user's datasets through the `Anfra` SDK global and renders them with its own HTML, CSS and JS. Use when the user asks for a Data App, or a custom page, report or interactive analysis over their datasets. Do NOT trigger for a one-off chart or data question.
---
# Building a Data App
A **Data App** is one self-contained HTML file stored in Holistics and edited in its Data App editor.
It runs in a sandboxed frame where the SDK is already on the global `Anfra`. The SDK supplies
data and state; every pixel is yours. You never run the app yourself: the user runs it and reports
back, so their console and the editor's Inspect panel are your only debuggers.
To export or convert a claude.ai artifact, load the `convert-artifact-dashboard` skill instead.
References, read when a step needs them:
- [api.md](references/api.md): every SDK call, the result shape, page structure and errors. **Read it before
writing any code; do not invent APIs.**
- [aql](../aql/) skill: writing the query bodies.
- [example.html](references/example.html): a complete app in the default Holistics look. Start the file from its
skeleton; its dataset and field names are placeholders.
## 1. Collect the datasets and the idea
You need the **datasets** the app may use (their fields and metrics) and a **description** of the
app. The invocation may hold a data snapshot, a description, both or neither, so check before
asking. A snapshot is JSON with `user` and `datasets`; when one is there, use it, and the rest of
the invocation is the description.
1. **No description:** ask what the app should show and who it's for, in one short question. Don't
suggest app ideas unless the user asks for them.
2. **No snapshot, Holistics MCP server connected:** read the datasets through it rather than asking
for a snapshot, which saves the user copying code and JSON back and forth.
1. With the description in hand, call `list_datasets` and shortlist the datasets that fit. Skip
ones tagged `Archived` or `Deprecated` or similar.
2. In one message, show the shortlist, name the server, and ask the user to confirm both the
datasets and that the app will live in that server's workspace (it may point at a different
one).
3. Call `fetch_dataset` for each. Its `relationships` show which models join, and its
descriptions carry the modeler's caveats on grain, fan-out and which date to use: follow
them.
3. **No snapshot and no MCP server**, or the server points at another workspace: ask for the
snapshot. Send the user this message as written, with the script right under the message's
step 2 so it sits next to the step that uses it:
> 1. Open a Data App in the workspace the app will live in, or create one,
> and click **Edit**.
> 2. Replace everything in the **Code** tab with this script, then select **Update preview**.
>
> ```html
> <pre id="out" style="white-space:pre-wrap"></pre>
> <script>
> const summary = {
> user: Anfra.user,
> datasets: Object.fromEntries(Object.entries(Anfra.datasets).map(([uname, d]) => [uname, {
> label: d.label,
> models: Object.fromEntries(d.data_models.map((m) => [m.name,
> m.fields.map((f) => `${f.name}: ${f.type}${f.is_custom_measure ? ' (measure)' : ''}`)])),
> metrics: d.metrics.map((m) => `${m.name}: ${m.type}`),
> }])),
> };
> document.getElementById('out').textContent = JSON.stringify(summary, null, 2);
> </script>
> ```
>
> 3. Copy the JSON that appears and paste it here.
>
> Tips:
>
> - If you already know which datasets the app needs, delete the others before pasting.
> - If you already know what the app should show and who it's for, include that with the JSON.
Whichever source you use:
- A dataset's key (`uname` from MCP) is what `dataset:` takes.
- A field is `model.field`, with the model name exactly as the snapshot or `fetch_dataset` gives
it (`ecommerce_orders.created_at`, not `orders.created_at`); a dataset metric is its bare name.
A filter's or mapping's `field` is the same `model.field` the query uses.
- A field marked `(measure)` in the snapshot is a measure (`orders.total_revenue`); the
[aql](../aql/) skill covers how to use one.
- If a number the app needs has no field or metric, declare it as a query-local metric in the AQL.
If AQL can't express it, tell the user it needs adding to the dataset; never compute it in
JavaScript.
Done when you hold a description and the fields and metrics of every dataset the app may use.
## 2. Agree on the design
1. **Restate the request** as one result the user can check ("revenue for the last full week
against the week before, with a country picker"). When the data cannot answer it, say so and
offer the nearest thing it can.
2. **Ask only what changes the numbers**: what a business word means, which date counts, what to
exclude. One question at a time, each with your recommended answer; skip what the description
already settles.
3. **Ask which look they want**, unless they said: the **default style** (recommended),
**something creative** (you choose palette and layout), or **their own design** (a brand,
colors or a reference). See [Look and feel](#look-and-feel).
4. **Write the declaration list**, one line per item:
- **Entities:** every `createQuery` (dataset, dimensions, measures), `createFilter`,
`createDateDrill`, `mapControl` and `mapCrossFilter`, using only names that appear verbatim
in the environment or are declared query-local in the AQL.
- **Rendering:** chart or table per query (default ECharts 6 from jsDelivr, as in the example).
- **Cross-filtering:** which clicks filter which queries (same dataset only), and whether they
replace the selection or toggle rows (see [api.md](references/api.md#cross-filtering)).
5. **Show the list and get a yes** before writing the file.
## Look and feel
An app must look finished without the user asking: no native controls, default buttons or unstyled
text. In every look (default, creative or their own design):
- A filter is a styled dropdown with search, multi-select for several values, never
`<select multiple>`. For dates, two styled `<input type="date">` and preset buttons, as in the
example. A preset sends its date phrase (`matches`, `last 30 days`) for the server to resolve, so
a saved app stays current: never compute preset dates in the browser.
- Give ECharts hex colors: it cannot parse `oklch`.
Then by look:
- **Default style (Holistics):** start from the example, which maps Holistics' in-app tokens onto
[Basecoat UI](https://basecoatui.com), with pinned CDN CSS and JS. Use its tokens as CSS
variables, Inter, its text sizes (24px page title, 14px card titles and body, 12px captions),
32px controls, one Blue 600 primary action and the chart palette (Blue 600 first). Green, purple
and amber belong in charts and status, never on actions.
- Filters are Basecoat comboboxes (`aria-multiselectable="true"` for several values). Basecoat's
deferred script sets them up on `DOMContentLoaded`: add the options and call `refresh()` after
that, as the example does.
- Basecoat `.card` is a flex column that clips overflow. On a filter bar card set
`flex-direction: row; align-items: flex-end; overflow: visible` (as `.card.filters` in the
example), or the controls drift right and dropdowns get cut off.
- **Creative:** your own palette, type and layout, in Basecoat or your own CSS, keeping readable
contrast, tabular numerals, light and dark (`prefers-color-scheme`), and styled loading, empty
and error states.
- **Their own design:** follow it. Take only the SDK wiring and the sandbox rules from the example,
not its look.
## 3. Write the file
Write the app as one whole HTML document, handed over as step 4 says. Follow the example's
skeleton: declare everything, `subscribe` a render function, `execute()`, then wire controls and
clicks to set state and `execute()` again. Keep the look (styles, markup, chart theme) apart from
the SDK wiring.
**Queries.** Write each `aql` with the [aql](../aql/) skill. The SDK applies the reader's state (filters,
selection, sorts, date drills, page) to the query's `explore { }` before it runs, so a pipe-style
query fails as soon as a reader touches a control, sort or date drill mapped to it. Nothing a reader
changes goes in the AQL text: static conditions go in `filters`; a reader's choice is a control
(`createFilter` + `mapControl`). Write flat table queries, not pivot queries (`rows { }` /
`columns { }`): pivot the rows in the app when it needs a pivot. Alias every dimension and measure
(`region: users.region`, `revenue: orders.total_revenue`): sorts, date drills, cross-filters and
row keys all go by the alias.
**The sandbox** allows scripts only, has an opaque origin and a content policy:
- Data comes only from the SDK. `fetch`, XHR, WebSocket and `sendBeacon` are blocked except to the
CDNs below; never call any service from the app.
- Libraries, styles and fonts load only from cdn.jsdelivr.net, cdnjs.cloudflare.com and Google
Fonts, by `https://` URL with a pinned version. Everything else is blocked, esm.sh and unpkg.com
included: load npm packages from jsDelivr (`/npm/<pkg>@<version>/<file>`), and ES modules from
its `+esm` build. Images may come from any `https://` server.
- Every CDN `<script src>` and stylesheet `<link>` carries `integrity="sha384-…"
crossorigin="anonymous"`, as in the example. Copy a file's hash from its jsDelivr page, and never
guess one: a wrong hash blocks the file. If you can't look a hash up, use only the libraries and
versions in the example. Load fonts from `@fontsource` on jsDelivr, as the example does: Google
Fonts' CSS differs per browser, so it can't be hashed.
- The app is its one HTML file: no relative `src` or `href`. Inline your scripts and styles, and
images as SVG or a `data:` URI.
- `localStorage`, `sessionStorage` and cookies throw: keep state in variables, and follow
`prefers-color-scheme` rather than Basecoat's theme switcher, which stores the mode.
- Forms, popups, navigation, `<iframe>` and `<base>` are blocked: use buttons and `change`
listeners, never `<form>`.
**Structure.** Mark the page as [api.md](references/api.md#structure) shows: `data-anfra-container`
and `data-anfra-block` (with a `data-anfra-label`) on its parts, and `data-anfra-query` or
`data-anfra-control` on the element each query and control draws into.
**Rendering.**
- Render each query's four states: `executing`, `success`, `error` (show `error.message`, and a
distinct "you don't have access" for `PermissionError`), and success with no rows ("No sales this
week", never a bare zero).
- On a selection change, restyle the marks already drawn (dim the unselected ones) rather than
rebuild the chart, which would replay its entry animation on every click. With ECharts, merge a
selection with a plain `setOption(option)` and keep `replaceMerge` for a new result.
- Put on the page the definitions, dates and rounding a reader needs to trust a number.
Record **generation metadata** in the example's `data-app-metadata` block, the first child of
`<head>` after `<meta charset>`. Keep it static JSON, with every `<` escaped as `\u003c` so prompt
text cannot close the script tag:
- `prompt`: the user's description, verbatim, never summarised or corrected: the invocation text
without any pasted snapshot, else their first message describing the app. It never changes.
- `model` and `effort`: the model and reasoning effort the runtime or session explicitly gives for
this revision; never infer them from the agent, product or task.
- `createdAt`: the first generation's UTC time in ISO 8601 (`"2026-09-24T14:30:00Z"`), read from a
clock. Kept on later revisions.
- `updatedAt`: this revision's UTC time; on the first generation, equal to `createdAt`.
Any value you can't read is `null`, never a guess. When editing an older file, add the missing
fields the same way.
Done when the file holds every entity from the agreed list, every part is marked, each query
renders all four states, every CDN asset carries its hash, the example's error banner script is kept before every other script,
and the metadata block has all five fields with known values or explicit `null`s.
## 4. Hand over and iterate
Check every name against the environment before handing over.
**Save with `create_data_app` when that tool is available**, instead of handing over a file. Write
the document straight into the call (`title`, `code`, and an optional `description`) and give the
user the returned URL in place of the paste steps below. Save every later fix to the same Data App
by passing its `id` as `overwrite_app_id`; without it, each call makes a new one.
**Hand over a file, not only a code block.** A long code block copied out of a terminal or chat can
lose or break lines, and a damaged paste leaves a blank or half-styled page. When you can write
files, save the app as one `.html` file and give its full path. Where a clipboard command exists
(`pbcopy` on macOS, `clip` on Windows, `wl-copy` or `xclip -selection clipboard` on Linux), also put
the file on the clipboard and say so. Give the whole file in one code block only when you can't
write files.
When a browser is available to you (headless Chrome, Playwright), render the file once before
handing over, with a stub `Anfra` built from the snapshot or the MCP datasets: their `datasets`
and `user`, and a `createApp` whose queries return one made-up row. That catches syntax errors,
crashes and broken layout. It says nothing about the AQL, which only the real SDK checks.
Then give the user these steps: in the Data App, click **Edit**, replace everything in the
**Code** tab with the file, select **Update preview**, and try every control and click. Select
**Save** whenever it looks right; they can keep refining after saving.
Tell them, in their terms, what the page shows and how to use each control, the assumptions you
made, and that you could not run it yourself. Ask them to check one headline number against one
they trust. If anything is off, ask for:
- what they see, against what they expected;
- the console panel contents;
- for a query that errored or looks wrong, its entry in the editor's Inspect panel (state,
executed AQL, error), and any problems the panel shows on the structure tree.
A page that shows its static markup but nothing the script fills in (placeholder text, no rows,
half the styles) means the script never ran, almost always a damaged paste. The error banner from
the example names the line where the parser noticed, usually at or just after the damage. Ask the
user to paste again from the file or clipboard, and to compare the **Code** tab's last line number
with the file's line count.
Read their report against [api.md](references/api.md#errors), and compare a misbehaving query's
executed AQL with what you meant. A query marked "Not drawn yet" has no element marked with it. A
handle the user pastes is found as [api.md](references/api.md#structure) says.
Change the smallest thing that explains the problem, and restate a change first if it alters what a
number means. Return the whole updated file the same way as the first, never a diff or a
snippet, since the whole **Code** tab is replaced. Preserve `prompt` and `createdAt`, refresh `model`, `effort` and
`updatedAt`, and repeat until the user says it's done.
Pliki w paczce (3)
- SKILL.md 15 KB
- references/api.md 17 KB
- references/example.html 19 KB
Wersje
| Repozytorium | Wynik | Licencja |
|---|---|---|
| Ta strona · holistics/skills | 100 | Apache-2.0 |
| altertable-ai/skills | 100 | MIT |
| holistics/skills | 91 | Apache-2.0 |
Migawka bazy z 13.11.2026 · wersja paczki 8fe8307168c1 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100convert-artifact-dashboard
Przenosi pulpit Claude, czyli stronę claude.ai z danymi, do aplikacji danych Holistics, zamieniając dane na zbiory danych Holistics. - 100setup-holistics-mcp
Konfiguruje połączenie z MCP Holistics i włącza narzędzia search_docs, execute_aql i generate_viz. - 100report-builder
Buduje jednoplikowy raport lub dashboard HTML z danych w Pythonie, Jinja2, Bootstrap 5 i Chart.js lub Plotly. - 100interactive-dashboard-builder
Buduje samodzielne interaktywne dashboardy HTML z Chart.js, filtrami rozwijanymi i profesjonalnym stylem, działające bez serwera i gotowe do udostępnienia. - 100build-data-report
Zamienia odpowiedzi z danych otwartych Date deschise w raport HTML z wykresami, tabelami i źródłami SQL. - 100datasets
Wyświetla listę podłączonych zbiorów danych ze statusem, liczbą tabel i datą ostatniej analizy.