[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M71RHSZVP0RQSQHX92K459NP":3,"skill-same:01M71RHSZVP0RQSQHX92K459NP":271},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":23,"publishedAt":44,"linkOnly":45,"markdownContent":46,"markdownBody":47,"frontMatter":48,"refName":49,"commitSha":50,"skillDirectory":51,"forksCount":52,"repositoryHtmlUrl":53,"repositoryHomepageUrl":54,"ownerHtmlUrl":55,"ownerBlogUrl":54,"ownerDescription":6,"updatedAt":56,"install":57,"resources":70},"01M71RHSZVP0RQSQHX92K459NP","sigma-workbooks",null,"Build, edit, and iterate on Sigma workbook specs — the JSON definition you send as `contents` in a POST to \u002Fv2\u002Fworkbooks, covering pages, layout, controls, charts, KPIs, tables, formulas, and sources. The Sigma OpenAPI is the source of truth for every shape and field; this skill adds navigation, style guidance, and proven recipes for effective dashboards and operational apps. Use when the user wants to construct a dashboard from a spec, generate a Sigma app (planning, approval, allocation, or exception), reproduce a screenshot\u002Fmockup\u002FClaude design artifact as a native Sigma app, add or modify pages \u002F elements \u002F controls \u002F formulas, validate a spec before submission, or work through the workbook spec lifecycle programmatically. Requires an SIGMA_API_TOKEN — obtain via the sigma-api skill first.","sigmacomputing\u002Fsigma-agent-skills","sigmacomputing","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F7460687?v=4","01M71RGQ6AE5S9T049REJ3K4TH","Sigma Computing","01M71RGQ6Z8DH62Q715RZDC6FA",23,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002FSKILL.md",[18],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",[24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43],"sigma workbooks","sigma","apps","modify","send","definition","for","allocation","tables","formulas","you","design","recipes","app","as","artifact","edit","Charts","screenshot","generate","2026-11-10 13:02:02",false,"---\nname: sigma-workbooks\ndescription: >-\n  Build, edit, and iterate on Sigma workbook specs — the JSON definition you\n  send as `contents` in a POST to \u002Fv2\u002Fworkbooks, covering pages, layout, controls, charts, KPIs,\n  tables, formulas, and sources. The Sigma OpenAPI is the source of truth for\n  every shape and field; this skill adds navigation, style guidance, and\n  proven recipes for effective dashboards and operational apps. Use when the\n  user wants to construct a dashboard from a spec, generate a Sigma app\n  (planning, approval, allocation, or exception), reproduce a\n  screenshot\u002Fmockup\u002FClaude design artifact as a native Sigma app, add or\n  modify pages \u002F elements \u002F controls \u002F formulas, validate a spec before\n  submission, or work through the workbook spec lifecycle programmatically.\n  Requires an SIGMA_API_TOKEN — obtain via the sigma-api skill first.\n---\n\n# Sigma Workbooks (Spec via REST API)\n\nThis skill helps you build effective Sigma workbooks by **navigating the Sigma OpenAPI** and applying **style guidance + proven recipes** beyond what the OpenAPI alone teaches.\n\n## Scope\n\nThe workbook **spec** — the JSON you send as the `contents` field in `POST \u002Fv2\u002Fworkbooks` (or `PUT \u002Fv2\u002Fworkbooks\u002F{id}\u002Fcontents`), defining pages, elements, sources, formulas, and layout. Layout supports grid placement plus responsive stack containers. Lifecycle around the workbook (embeds, grants, materialization schedules, bookmarks, sharing) is a separate API surface and out of scope here.\n\n## Sources of truth\n\nSigma's public API docs are an index at `https:\u002F\u002Fhelp.sigmacomputing.com\u002Fopenapi.json` that lists two **canonical split specs** (split from one large spec to fix compilation \u002F out-of-memory errors — so the structure changed subtly). **That index now serves an HTML page, not JSON** (verified 2026-08-05) — it renders links to the two specs rather than returning a machine-readable list, so treat it as a human landing page and go straight to the two URLs below:\n\n1. **`https:\u002F\u002Fhelp.sigmacomputing.com\u002Fopenapi\u002Fopenapi\u002Fsigma-rest-api.json`** — the REST API: endpoint request\u002Fresponse shapes (workbooks, data models, members, connections, exports, materialization, …). Use for API *calls*.\n2. **`https:\u002F\u002Fhelp.sigmacomputing.com\u002Fopenapi\u002Fopenapi\u002Fcode-representation.json`** — the \"code representation\" (as-code) spec. Today it documents the **data-model** spec (`\u002Fv2\u002FdataModels\u002Fspec`); use it for data-model element shapes.\n\n**Workbook element\u002Fcontrol\u002Fformat shapes** (the `bar-chart` \u002F `kpi-chart` \u002F `control` \u002F format `kind`s that go under a workbook's `contents`) are **not inlined in either split spec** — get them from one of, roughly in this order.\n\n> **The split specs don't document the workbook content endpoints in any depth**: `sigma-rest-api.json` documents `GET \u002Fv2\u002Fworkbooks\u002F{id}`, `POST \u002Fv2\u002Fworkbooks`, and `PUT \u002Fv2\u002Fworkbooks\u002F{id}\u002Fcontents` only at the bare resource-metadata level — the `contents` body itself (element\u002Fcontrol\u002Fformat shapes) isn't inlined — and `code-representation.json` carries only the two `\u002Fv2\u002FdataModels\u002Fspec*` paths. So for workbook authoring the split specs are not merely missing the inlined element shapes; the `contents` shape itself is absent. Use a per-endpoint reference page, the compiled asset, or a live readback (all below).\n\n- **A live workbook readback** — `GET \u002Fv2\u002Fworkbooks\u002F{id}?includeContents=true` on the user's org. Read literal elements from flat `contents.elements[]`; pages, overlays, and panels are metadata and layout determines placement.\n- **A single endpoint's stable reference page** — `https:\u002F\u002Fhelp.sigmacomputing.com\u002Freference\u002F\u003Cendpoint-slug>`. Use it to confirm one endpoint's current request\u002Fresponse envelope. Create accepts `{name, folderId, description?, contents: {...}}`; update (`PUT ...\u002Fcontents`) accepts exactly `{contents: {...}, documentVersion?}`. \u003C!-- pragma: allowlist secret -->\n- **The full compiled OpenAPI** — one document covering every workbook `kind`, and the **only** source that documents the workbook `contents` shape at all. Use it for bulk discovery (\"list every kind the API accepts\") that no single per-endpoint page can do. **This is the canonical, stable, unauthenticated URL — use it directly:**\n\n  ```\n  https:\u002F\u002Fassets.sigmacomputing.com\u002Fopenapi\u002Fpublic-rest-api\u002Fsigma-computing-public-rest-api.json\n  ```\n\n### Fetching the compiled asset\n\n```bash\ncurl -sfL https:\u002F\u002Fassets.sigmacomputing.com\u002Fopenapi\u002Fpublic-rest-api\u002Fsigma-computing-public-rest-api.json \\\n  -o \u002Ftmp\u002Fsigma-api.json\n```\n\nPlain `GET`, no auth, no signature, no content hash — safe to hardcode. Title \"Sigma Computing Public REST API\", `version: 2.0.0`, ~6.8 MB (it uses `$ref`s into `components.schemas`, so **deref as you walk** — element kinds are behind `#\u002Fcomponents\u002Fschemas\u002FWorkbookElement`).\n\n> **Do not use the old Fern docs asset** (`fdr-prod-docs-files-public.s3.amazonaws.com\u002Fsigma.docs.buildwithfern.com\u002F\u003Chash>\u002F…`). It is content-addressed, now requires AWS presigned query params (a bare fetch 403s), and — the reason that actually matters — **it lags the live API**. As of 2026-08-05 it was missing report content support entirely, still documented the pre-`contents`-wrapper request body, and **did not contain the `repeated-container` element kind**, which caused this skill to previously assert that repeated containers were not spec-authorable. They are. Working from a stale asset produces confidently wrong documentation; prefer the `assets.sigmacomputing.com` URL above, and treat a live workbook readback as the tiebreaker.\n\nThe old `help.sigmacomputing.com\u002Fopenapi.json` index is now an HTML landing page and does not link the compiled asset at all.\n\nWhen this skill and the spec (or a live readback) disagree, the spec wins. When a feature isn't covered here, consult the spec \u002F a live workbook and use what it documents.\n\n## Consulting the shapes (per-endpoint pages, compiled OpenAPI, or a live readback)\n\n**The field lists and examples in this skill are illustrative, not exhaustive** — when you need the complete, current shape of anything, pick the right tool for the question:\n\n- **One endpoint, one doubt** (does this field still exist, is the body wrapped or flat, what's required) — go straight to that endpoint's stable reference page, `https:\u002F\u002Fhelp.sigmacomputing.com\u002Freference\u002F\u003Cendpoint-slug>` (see *Sources of truth*). No caching, no `jq`, just read the page.\n- **Every `kind` the API accepts, or every field on a `kind`** (bulk discovery — e.g. building out `reference\u002Fspecification\u002F*.md`) — the per-endpoint pages don't help here (one endpoint each); use the compiled OpenAPI or a live workbook readback instead. Fetch the compiled spec once per session and inspect with `jq`:\n\n```bash\n# Assumes \u002Ftmp\u002Fsigma-api.json from \"Fetching the compiled asset\" above.\n# If a field looks wrong, check that field's per-endpoint page, or read a live workbook spec\n# (GET \u002Fv2\u002Fworkbooks\u002F{id}?includeContents=true) and navigate contents.elements[] by kind.\n\n# The workbook create request body. NOTE: the outer object is {name, folderId, description?, contents},\n# so elements\u002Fpages\u002Foverlays\u002Fpanels\u002Flayout\u002Fsettings\u002Fagents are under .contents:\njq '.paths.\"\u002Fv2\u002Fworkbooks\".post.requestBody.content.\"application\u002Fjson\".schema' \u002Ftmp\u002Fsigma-api.json\n```\n\nElement, source, control, and format shapes are identified by their `kind` value (e.g. `bar-chart`, `kpi-chart`, `join`, `warehouse-table`) rather than by a top-level schema name. They live in `components.schemas` and are reached by `$ref` (element kinds hang off `#\u002Fcomponents\u002Fschemas\u002FWorkbookElement`) — so **deref as you walk** if you're writing your own traversal. The `jq` recipes below scan the whole document, so they work regardless:\n\n```bash\n# List every kind the spec accepts (elements, sources, controls, formats, …):\njq -r '[.. | objects | select(.properties.kind.enum) | .properties.kind.enum[0]] | unique[]' \u002Ftmp\u002Fsigma-api.json\n\n# Full field list (required + optional) for one kind — swap bar-chart for any kind above:\njq --arg k bar-chart 'first(.. | objects | select((.allOf? and any(.allOf[]?; .properties?.kind?.enum==[$k])) or .properties?.kind?.enum==[$k]))\n  | {required: ([.allOf[]?.required \u002F\u002F .required] | add | unique), properties: ([(.allOf[]?.properties \u002F\u002F .properties) | keys[]] | unique)}' \u002Ftmp\u002Fsigma-api.json\n\n# The full nested shape for that kind (to inspect sub-objects like source, yAxis, format, comparison):\njq --arg k bar-chart 'first(.. | objects | select((.allOf? and any(.allOf[]?; .properties?.kind?.enum==[$k])) or .properties?.kind?.enum==[$k]))' \u002Ftmp\u002Fsigma-api.json\n```\n\n`WebFetch` works for the JSON too. Either path is fine.\n\nNo `curl`\u002F`jq` on the machine (e.g. Windows without WSL)? `scripts\u002Fwb-rep.rb`\nships a `capabilities` subcommand that does the same three queries with\npure-Ruby `Net::HTTP` + `JSON.parse` — no external tools required:\n\n```bash\nruby scripts\u002Fwb-rep.rb capabilities                          # list every kind\nruby scripts\u002Fwb-rep.rb capabilities --kind bar-chart          # field list for one kind\nruby scripts\u002Fwb-rep.rb capabilities --kind bar-chart --field source  # one field's shape\n```\n\n**Why bother:** the API ships new fields and viz configurations regularly, and this skill covers the common surface, not every field. If you want a capability and don't see it documented here, **assume it may exist and check the spec before concluding it doesn't** — the `kind` query above answers in seconds.\n\n## Auth\n\nAuthenticate via the `sigma-api` skill first to populate `$SIGMA_BASE_URL` and `$SIGMA_API_TOKEN`. Two options there: **client credentials** (`SIGMA_CLIENT_ID`\u002F`SIGMA_CLIENT_SECRET`, best for headless\u002Fautomation) or **interactive browser login** (`sigma-api\u002Fscripts\u002Fbrowser-login.sh` → refresh headlessly with `refresh-token.sh`, no client ID\u002Fsecret). Either yields a `$SIGMA_API_TOKEN`; the rest of this skill is identical.\n\n## Recommended Workflow\n\nThese are guidelines, not mandates — but they prevent the failure modes that show up most often when drafting from scratch.\n\n> **Schema drift signal:** an error about request *shape* (`invalid argument`, `unknown field`, `missing required field`, `unexpected property`) usually means this skill is stale on that detail. Fetch the OpenAPI and compare; the canonical shape is there.\n\n### Step 0 — Authenticate, capture user identity\n\n```bash\nUSER_ID=$(curl -s -H \"Authorization: Bearer $SIGMA_API_TOKEN\" \\\n  \"$SIGMA_BASE_URL\u002Fv2\u002Fwhoami\" | jq -r '.userId')\n\nHOME_FOLDER_ID=$(curl -s -H \"Authorization: Bearer $SIGMA_API_TOKEN\" \\\n  \"$SIGMA_BASE_URL\u002Fv2\u002Fmembers\u002F$USER_ID\" | jq -r '.homeFolderId')\n```\n\nIf the user provided a **target image or design artifact** (a screenshot,\nmockup, PDF, or Claude-generated app design they want reproduced), pause here\nand load `reference\u002Fworkflows\u002Ffrom-image.md` — it adds mandatory whole-screen\ninventory, behavior classification, design-manifest, native-first routing,\nrender-diff, and iteration gates that happen *before and alongside* normal data\ndiscovery. The standard workflow alone tends to reproduce the data visuals\nwhile missing the app shell and behavior.\n\nIf the user asked to generate \u002F build \u002F scaffold a Sigma **app** (planning,\napproval, allocation, exception, or an unspecified “app”) and did **not**\nsupply a target image, pause here and load\n`reference\u002Fworkflows\u002Fgenerate-apps.md` — it classifies the app type,\n**interviews** before it builds (which fields users may edit, whether the\nworkflow needs approvals, whether to add a Sigma Agent and what it is\nfor), records an intake manifest, states a build plan, and clones a\nbest-practice **architecture** fixture.\nDesign is a separate pass: load `styling.md` as a library and compose for\nthis type (do not stamp the five-recipe dashboard *or* the navy-hero\ncommand-center example). A\ntarget image still wins: load `from-image.md` instead.\n\n### Step 1 — Find a reference workbook to study\n\nAny existing workbook on the user's org doubles as a template. List and pick one with similar content:\n\n```bash\ncurl -s -H \"Authorization: Bearer $SIGMA_API_TOKEN\" \\\n  \"$SIGMA_BASE_URL\u002Fv2\u002Fworkbooks?limit=50\" | jq '.entries[] | {workbookId, name}'\n```\n\nIf no relevant workbook exists, pick any — the goal is studying spec structure, not matching content. If the org has no workbooks at all, draft from scratch using the OpenAPI shapes + this skill's recipes.\n\n### Step 2 — Study the reference spec\n\nYAML is the canonical format for workbook specs in this skill — easier to read, diff, and review than JSON. Sigma's API accepts both (`Content-Type: application\u002Fyaml` or `application\u002Fjson`); `Accept: application\u002Fyaml` is the default on `GET \u002Fv2\u002Fworkbooks\u002F\u003Cid>?includeContents=true`. Use `yq` to inspect spec YAML the same way you'd use `jq` on JSON.\n\n```bash\ncurl -s -H \"Authorization: Bearer $SIGMA_API_TOKEN\" \\\n  \"$SIGMA_BASE_URL\u002Fv2\u002Fworkbooks\u002F\u003Creference-workbook-id>?includeContents=true\" \\\n  > \u002Ftmp\u002Freference-spec.yaml\n```\n\nLook at source structure, column IDs, formulas, flat `contents.elements`, page\nmetadata, and layout XML. Do not copy an obsolete `pages[].elements` shape.\n\n### Step 3 — Discover data sources\n\nLoad `reference\u002Fworkflows\u002Fdiscover.md`. Quick summary:\n\n1. `GET \u002Fv2\u002Fconnections` — find the user's connection by name or type.\n2. Ask the user for the table path; verify with `POST \u002Fv2\u002Fconnection\u002F\u003Cid>\u002Flookup`.\n3. Discover columns with the `sigma-api` paginated column helper, which exhausts `GET \u002Fv2\u002Fconnections\u002Ftables\u002F{inodeId}\u002Fcolumns` (the raw response holds only 50 columns by default; full mechanics in `reference\u002Fworkflows\u002Fdiscover.md`). Only fall back to asking the user when the endpoint doesn't return what's needed.\n\n**Never invent column names** — only use names returned by the API or supplied by the user.\n\n**Verify literal values before writing predicates.** If your task involves filtering on a categorical column (e.g., `CountIf([Status] = \"active\")`, `If([Type] = \"sale\", ...)`), you need to know what values that column *actually* contains — the `\u002Fv2\u002Fconnections\u002Ftables\u002F{inodeId}\u002Fcolumns` endpoint gives you names and types but not values. Run a `SELECT DISTINCT \u003Ccol>` via any tool that reaches the warehouse — an MCP server (warehouse or [Sigma](https:\u002F\u002Fhelp.sigmacomputing.com\u002Fdocs\u002Fuse-sigma-mcp-server)), a SQL CLI, or just ask the user. Don't guess literals. See `reference\u002Fworkflows\u002Fdiscover.md`.\n\n**Verify the composed source grain before drafting.** Name the expected grain\nkey (or composite key), then prove that the source as the workbook will read it\nhas one row per key. For a single key, assert\n`COUNT(*) = COUNT(DISTINCT \u003Cgrain-key>)`; for a composite key, group by all key\ncolumns and require zero duplicate groups. For a 1:1 or many:1 join intended to\npreserve the left grain, compare row count and distinct left-grain count before\nand after the join and require both to stay unchanged. Inner joins and\nintentional 1:many joins need a written expected shrink\u002Fexpansion instead.\nDo not draft plausible-looking counts over an unproven fanout. See\n`reference\u002Fworkflows\u002Fdiscover.md`.\n\n### Step 4 — Identify features and load only what you need\n\nMap the user's request to the **Reference Index** below. State the features you identified, then read the listed reference files before drafting. **If the user asks for a feature this skill doesn't cover**, fetch the OpenAPI and inspect the relevant schema.\n\nWhen choosing a visualization, use the data-shape selector at the top of\n`reference\u002Fspecification\u002Fcharts.md` before copying a chart recipe. A ranked\ncategorical comparison defaults to a horizontal bar, not a sorted table used\nas the primary visualization.\n\nIf the user asked to generate an app, run `generate-apps.md` first (Step 0)\nbefore choosing an input-table architecture here. That interview already\nrecorded which fields users may edit, whether the workflow needs\napprovals, and whether to include a workbook agent. Load\n`reference\u002Fspecification\u002Fstyling.md` as a library and compose for this\napp's job — do not stamp the five-pattern exec-dashboard stack or the\nnavy-hero command-center example.\n\nIf the request includes an input table, writeback, “populate,” “seed,” planning,\napproval, allocation, or exception workflow, load\n`reference\u002Fspecification\u002Finput-tables.md` before choosing an architecture.\nCreating an input-table element, loading initial rows, composing a downstream\nread path, and submitting a runtime action are four different operations. Do\nnot substitute actions, unions, or joins for one another when the first\napproach leaves the table empty.\n\n### Step 5 — Draft the spec to a local file\n\nWrite the spec YAML to disk (e.g., `\u002Ftmp\u002Fworkbook-spec.yaml`). YAML is preferred over JSON in this skill — easier to read, diff, and comment for human review. The API accepts either; pick YAML unless something downstream specifically needs JSON. Key rules:\n\n- Every element needs a unique `id` and a descriptive `name`.\n- Every column needs a unique `id`, a `name`, and a `formula`.\n- Follow the formula reference rules in `reference\u002Fspecification\u002Fformulas.md` exactly — most spec errors happen here.\n- **Write explicit `contents.layout` XML whenever elements are non-empty.** It\n  is the source of truth for page\u002Fcontainer\u002Ftab organization.\n- Emit `\u003CElement>` for layout leaves and `\u003CContainer>` for nested grid or stack\n  containers. Use `type=\"grid\"` when children need `gridColumn` \u002F `gridRow`;\n  use `type=\"stack\"` for ordered responsive flow. Stack children omit grid\n  coordinates and may use responsive `\u003CSize>` blocks. Repeated-container\n  elements still use the grid-bodied form. `\u003CTabbedContainer>` \u002F `\u003CTab>` remain\n  valid. Never emit the legacy `\u003CLayoutElement>` \u002F `\u003CGridContainer>` aliases;\n  live verification rejects `\u003CLayoutElement>` (`valid:false`; some API\n  versions returned HTTP 400 instead).\n- Start with 1–2 pages. Add more later via update.\n\nFor **create**, include outer `name`\u002F`folderId` and `contents` with required\n`schemaVersion`, `kind: workbook`, flat `elements`, and metadata-only `pages`.\nOptional `contents` fields include `overlays`, `panels`, `settings`, and `agents`.\nThis skill requires `layout` whenever `elements` is non-empty. See\n`reference\u002Fspecification\u002Fschema.md`.\n\n### Step 6 — Validate the spec\n\n**Run the bundled validator first — do not skip.**\n\n```bash\n.\u002Fscripts\u002Fvalidate-spec.sh \u002Ftmp\u002Fworkbook-spec.yaml\n```\n\nThen do the manual formula pass and final shape checks per `reference\u002Fworkflows\u002Fvalidate.md`. Fix everything reported before continuing.\n\n### Step 7 — Create the workbook\n\n```bash\ncurl -s -X POST -H \"Authorization: Bearer $SIGMA_API_TOKEN\" \\\n  -H \"Content-Type: application\u002Fyaml\" \\\n  -H \"Accept: application\u002Fyaml\" \\\n  --data-binary @\u002Ftmp\u002Fworkbook-spec.yaml \\\n  \"$SIGMA_BASE_URL\u002Fv2\u002Fworkbooks\" > \u002Ftmp\u002Fcreate-response.yaml\n\nWORKBOOK_ID=$(yq -r '.workbookId' \u002Ftmp\u002Fcreate-response.yaml)\ncp \u002Ftmp\u002Fworkbook-spec.yaml \"\u002Ftmp\u002Fworkbook-spec-${WORKBOOK_ID}.yaml\"\n```\n\nPersist the spec after a successful create so subsequent `PUT` updates can start from it. Report **both** the workbook URL **and** the saved spec path.\n\nIf creation fails, read the error, fix the spec, re-validate, retry. See `reference\u002Fworkflows\u002Fvalidate.md` for decoding cryptic errors.\n\n### Step 7b — Verify the workbook actually compiles\n\n**Do not skip.** A successful POST is necessary but not sufficient — Sigma accepts specs whose formulas don't resolve, then surfaces the failures at query time by embedding the error as a string literal in the compiled SQL (`'Unknown column \"[X]\"'`, `'Circular column reference to [Y]'`). Affected elements render empty in the UI. Only Sigma's compiler knows whether your formula references actually resolve.\n\n```bash\n.\u002Fscripts\u002Fverify-workbook.sh \"$WORKBOOK_ID\"\n```\n\nThe script reads `SIGMA_BASE_URL` and `SIGMA_API_TOKEN` from its environment,\nso they must be **exported**, not just set in your shell. Run `export` on both,\nor put them in front of the command\n(`SIGMA_BASE_URL=… SIGMA_API_TOKEN=… .\u002Fscripts\u002Fverify-workbook.sh …`). If\nthey're missing, the script exits 2 without sending a request.\n\nIf any element reports `[FAIL]`, fix the column formulas in the spec (most often a missing source prefix, a self-referencing column, or a friendly-name mismatch with the warehouse — see `reference\u002Fspecification\u002Fformulas.md`), `PUT` the corrected spec, and re-verify.\n\n### Step 8 — Iterate\n\nAfter initial creation, use `PUT \u002Fv2\u002Fworkbooks\u002F\u003Cid>\u002Fcontents` to add pages or refine the workbook.\n\n**For anything beyond ~1 page \u002F ~10 elements, switch to the element rep** (`reference\u002Fworkflows\u002Felement-rep.md`): `scripts\u002Fwb-rep.rb pull \u003Cid> \u003Cdir>` explodes the spec into one file per element so each edit touches a ~½KB file instead of the whole spec, `push` handles drift-check + validation + PUT, and `render` exports page PNGs you can actually look at. The raw GET\u002FPUT flow below remains fine for small workbooks and one-off tweaks.\n\n> **IDs are preserved on CREATE.** The `id` values you POST (pages, elements, columns) are kept verbatim, and `layout` `elementId` references stay valid — so you can edit your saved spec and `PUT` it back, re-wrapped as just `{contents: {...}}` (see below — PUT does not take the outer `name`\u002F`folderId`). `GET` the current spec first only if you don't have your latest copy. See `reference\u002Fworkflows\u002Fcrud.md`.\n>\n> **`PUT \u002Fv2\u002Fworkbooks\u002F\u003Cid>\u002Fcontents` is contents-only.** Sending `name`, `folderId`, or `description` alongside `contents` is silently ignored — use `PUT \u002Fv2\u002Ffiles\u002F{fileId}` to rename or move a workbook.\n\n```bash\ncurl -s -H \"Authorization: Bearer $SIGMA_API_TOKEN\" \\\n  \"$SIGMA_BASE_URL\u002Fv2\u002Fworkbooks\u002F\u003Cworkbook-id>?includeContents=true\" \\\n  > \u002Ftmp\u002Fcurrent-spec.yaml\n\n# Edit \u002Ftmp\u002Fcurrent-spec.yaml inside .contents; preserve elements, pages,\n# overlays, panels, layout, settings, and agents.\n# then PUT only the contents object — see reference\u002Fworkflows\u002Fcrud.md for why\n# sending the outer name\u002FfolderId\u002Fresponse-only fields alongside it is ignored:\nyq '{\"contents\": .contents}' \u002Ftmp\u002Fcurrent-spec.yaml > \u002Ftmp\u002Fcurrent-spec-put.yaml\ncurl -s -X PUT -H \"Authorization: Bearer $SIGMA_API_TOKEN\" \\\n  -H \"Content-Type: application\u002Fyaml\" \\\n  -H \"Accept: application\u002Fyaml\" \\\n  --data-binary @\u002Ftmp\u002Fcurrent-spec-put.yaml \\\n  \"$SIGMA_BASE_URL\u002Fv2\u002Fworkbooks\u002F\u003Cworkbook-id>\u002Fcontents\" | yq .\n\ncp \u002Ftmp\u002Fcurrent-spec.yaml \"\u002Ftmp\u002Fworkbook-spec-\u003Cworkbook-id>.yaml\"\n.\u002Fscripts\u002Fverify-workbook.sh \"\u003Cworkbook-id>\"\n```\n\n### Step 9 — Report back\n\nReport the workbook URL and the saved spec path. **Do not tack on generic \"improvement ideas\" or \"next steps.\"** Match the response to what was asked.\n\nSurface follow-up items only when they're load-bearing, and name them concretely:\n\n- **Tradeoffs you made during the build** — dropped a chart, simplified a formula, skipped a control because the shape wasn't in your reference.\n- **Obvious gaps revealed by the column list** — e.g., the user asked for \"sales by region\" and the table has a `region_tier` column that would make the breakdown richer. One sentence, named.\n\nIf none apply, just report the URL + spec path and stop.\n\n## Reference Index\n\nThe reference is feature-sliced — don't read every file up-front. The index has three sections: **elements** (the visual \u002F interactive pieces), **sources** (where each element gets its data), and **cross-cutting** (formulas, layout, formatting, validation, CRUD).\n\n### Elements\n\n| File | When to load |\n|------|--------------|\n| `reference\u002Fspecification\u002Ftables.md` | Table element, tabular data, data grid, spreadsheet-style list. Also **element-level filters** (`list`, `top-n`, `number-range`, `date-range`, `text-match`, `hierarchy`), groupings (pivot, group by), the `pivot-table` and editable `input-table` element kinds, and `conditionalFormats` (threshold-based cell coloring, on pivot\u002Finput tables). |\n| `reference\u002Fspecification\u002Fcharts.md` | **Load before choosing a visualization.** Data-shape → chart selection, then chart\u002Fgraph recipes for line \u002F bar \u002F column \u002F stacked \u002F grouped \u002F combo \u002F donut \u002F pie \u002F scatter \u002F waterfall \u002F share-of \u002F breakdown. Cartesian axes, color, trellis, legend, trendlines, reference marks. |\n| `reference\u002Fspecification\u002Fmaps.md` | Map visualizations — `geography-map` (GeoJSON shapes), `point-map` (lat\u002Flong bubbles), `region-map` (states \u002F counties \u002F countries). |\n| `reference\u002Fspecification\u002Fkpis.md` | KPI, stat, big number, single value, metric card — including layout \u002F value styling, the comparison Δ badge (`comparisonColumn` + `comparison:{display:\"delta\"}` — spec-authorable and readback-stable; the house default), and the trend\u002Fsparkline block (still UI-bound). |\n| `reference\u002Fspecification\u002Fcontrols.md` | Filter, dropdown, picker, multi-select, date range, date picker, text filter, number range, slider, segmented, hierarchy, legend, and drill controls. Also entry controls and formula handles. |\n| `reference\u002Fspecification\u002Fcontent-elements.md` | The non-data elements — `text` (Markdown + inline styling), `image`, `divider`, `embed` (external URLs), `page-break` (PDF\u002Fprint pagination), `form`, `progress`, `navigation`, `plugin`. Titles, callouts, logos, rules, embedded content. |\n| `reference\u002Fspecification\u002Finput-tables.md` | **Load for every input-table or “populate\u002Fseed” request.** Operational supplement for `input-table`: supported row-arrival decision tree, write connection, UI-only published permission, publish gate, linked-key correlation, warehouse views, and why actions\u002Funions\u002Fjoins are not bulk seeding mechanisms. |\n| `reference\u002Fspecification\u002Fstyling.md` | **Load when composing a look from spec.** A library of options (hero bands, KPI cards, gradients, section headers, chart color, formats) plus an anti-pattern checklist. Not a house style — do not stamp the five-pattern exec dashboard onto every app. PNG fail: skill chrome, invisible entry controls, Dark-by-default on data-entry, 3-KPI status on operational apps. |\n| `reference\u002Fspecification\u002Fagents.md` | Workbook AI agent, chat with your data, agent, chatbot, AI assistant. The workbook-top-level `agents:[]` array + page-level `chat` element; Analyze \u002F Configure \u002F Navigate \u002F Act capability profiles; direct control\u002Fnavigation\u002Fwrite action tools; read-only analyst vs. operator; the four `tools[]` kinds (`action`, `mcp-connector`, `warehouse-agent`, `search-service`), `greeting`, `requiresApproval`, why action sequences are referenceable but not authorable; org-feature gate + graceful degrade. |\n\n### Sources\n\n| File | When to load |\n|------|--------------|\n| `reference\u002Fspecification\u002Fsources-warehouse.md` | Always — load before drafting any spec. Warehouse-table source (Snowflake, BigQuery, Databricks, Redshift, Postgres\u002FMySQL). |\n| `reference\u002Fspecification\u002Fsources.md` | Reference another chart\u002Ftable\u002Felement, derive from existing element, join, combine tables, data model \u002F semantic-layer source, custom SQL, union, transpose, unpivot. |\n\n### Cross-cutting\n\n| File | When to load |\n|------|--------------|\n| `reference\u002Fspecification\u002Fschema.md` | Always — wrapped shape, required flat `contents.elements`, metadata-only pages, overlays, panels, settings, backgrounds, and the PUT-only-contents rule. |\n| `reference\u002Fspecification\u002Fformulas.md` | Always — load before drafting any spec. Formula syntax, qualification, special characters, the #1 mistake. |\n| `reference\u002Fspecification\u002Fformatting.md` | Format, currency, percentage, date format, decimals — column formatting. |\n| `reference\u002Fspecification\u002Flayout.md` | **Always load.** Required layout policy; page\u002Fcontainer organization; backgrounds\u002Fspacing; panels, headers, sidebars, navigation; repeated and tabbed containers. |\n| `reference\u002Fspecification\u002Fexample-full.yaml` | A real multi-page reference spec (KPIs, charts, joins, controls, layout) — copy shapes from when in doubt. |\n| `reference\u002Fspecification\u002Fcomparative-kpi-card.yaml` | Minimal clone-able comparative KPI card — `value` + `comparisonColumn` + `comparison:{display:\"delta\"}`, the house-default comparative shape (see `kpis.md`). |\n| `reference\u002Fspecification\u002Ftrellis-chart-support.md` | The empirical coverage matrix for trellis charts — how each kind was verified live (POST + readback + render). Load when `charts.md`'s trellis guidance needs the underlying evidence. |\n\n### Workflows\n\n| File | When to load |\n|------|--------------|\n| `reference\u002Fworkflows\u002Fdiscover.md` | Finding connections, tables, and column names. Load before composing a new spec. |\n| `reference\u002Fworkflows\u002Fcomposition.md` | Open-ended design decisions, named asymmetric splits\u002Fmosaic, and the content-prescriptive `ledger` record-lookup archetype. Covers when to ask, chart-vs-table defaults, editorial sizing, and hidden source pages. Load before drafting when the prompt leaves design choices unmade or asks users to find\u002Fbrowse records. |\n| `reference\u002Fworkflows\u002Fapp-compositions.md` | **Operational app visual composition.** Load with `generate-apps.md`: keeps semantic architecture separate from appearance, selects `workbench` \u002F `queue-rail` \u002F `builder-preview`, requires a local design manifest, emits asymmetric work-surface-first layout via `Composition.compose`, and adds a two-render PNG polish gate. |\n| `reference\u002Fworkflows\u002Factions.md` | Buttons, write-back, and **all twelve** action effects — insert\u002Fupdate\u002Fdelete-rows, clear-control, set-control-value, open\u002Fclose-overlay (modal **and** drawer), open-url, open-document (incl. passing `targetControls` into another workbook), navigate, select-tab, refresh-element — plus the append-only-log pattern and the masked-error catalog. Load when the user wants a button, a \"log\u002Fsave\u002Fsubmit\" action, tab\u002Fpage navigation, a deep link, or a write-back workflow. |\n| `reference\u002Fworkflows\u002Fgenerate-apps.md` | **Generate a Sigma app.** Load first when the user asks to build a planning, approval, allocation, or exception app (and did not supply a target image). Classifies the type, **interviews** for editable fields \u002F approvals \u002F an Analyze–Configure–Navigate–Act workbook-agent contract, clones an architecture fixture (planning is a multi-page studio shell), then **composes** an app shell + `workbench` \u002F `queue-rail` \u002F `builder-preview` look. Fail the PNG pass on skill chrome, invisible entry controls, Dark-by-default on data-entry, a 3-KPI status strip, an empty work surface, or `Unknown column` \u002F `Invalid Query` on a page measure. |\n| `reference\u002Fworkflows\u002Ffixtures\u002FREADME.md` | Rules for cloning an operational-app architecture fixture (placeholders only — never commit real org\u002Fuser\u002Ffolder\u002Fworkbook IDs). Load alongside `generate-apps.md`, not standalone. |\n| `reference\u002Fworkflows\u002Ffixtures\u002Fplanning-app.yaml` | Starting spec for a planning app. Clone via `generate-apps.md`; don't read standalone. |\n| `reference\u002Fworkflows\u002Ffixtures\u002Fallocation-app.yaml` | Starting spec for an allocation app. Clone via `generate-apps.md`; don't read standalone. |\n| `reference\u002Fworkflows\u002Ffixtures\u002Fapproval-app.yaml` | Starting spec for an approval app. Clone via `generate-apps.md`; don't read standalone. |\n| `reference\u002Fworkflows\u002Ffixtures\u002Fexception-app.yaml` | Starting spec for an exception app. Clone via `generate-apps.md`; don't read standalone. |\n| `reference\u002Fworkflows\u002Fplanning-apps.md` | **Scenario planning, budgeting, and forecasting apps.** Scenario × Period × Planning Line grain, governed baseline, scenario matrix, linked override grid, financial sign, filter-propagation choices, approval\u002Faudit, and runtime gates. |\n| `reference\u002Fworkflows\u002Fallocation-apps.md` | **Allocation and capacity apps.** Budget\u002Ftarget vs. baseline at Period × Allocation Dimension grain, linked editable units\u002Fuplifts, working allocation, request queue, and exact variance gates. |\n| `reference\u002Fworkflows\u002Fapproval-apps.md` | **Approval and decision apps.** Stable entity-key queues, counter-values, immutable audit logs, one-row status updates, agent boundaries, and runtime tests. |\n| `reference\u002Fworkflows\u002Fexception-apps.md` | **Exception command centers.** Stable operational-key queues, deterministic recommendations, overrides, ownership, resolution logs, and exact KPI-delta tests. |\n| `reference\u002Fworkflows\u002Fcrud.md` | POST \u002F GET \u002F PUT against the workbook content endpoints. Load when creating, retrieving, or updating a workbook. |\n| `reference\u002Fworkflows\u002Fvalidate.md` | Pre-submit + post-create structural validation. Load before any POST or PUT; for joins, controls, writeback, agents, or numeric claims continue to `runtime-verification.md`. |\n| `reference\u002Fworkflows\u002Fruntime-verification.md` | **Runtime evidence loop:** compile, render, export, cardinality, numeric oracle, published writeback, linked-row correlation, control scope, approval scope, and agent tests. |\n| `reference\u002Fworkflows\u002Ffrom-image.md` | The user supplied a target image or Claude design artifact to reproduce. Load *before* discovery — it inventories the entire app shell and behavior, routes native Sigma vs plugin\u002FUI-only surfaces, requires a local design manifest, and enforces first-render → diff → final-render acceptance. |\n| `reference\u002Fworkflows\u002Felement-rep.md` | **Large or multi-page workbooks, parallel element work, or iterative refinement.** `scripts\u002Fwb-rep.rb` explodes the spec into one small file per element (pull\u002Fstatus\u002Fpush\u002Frender) so edits never drag the whole spec through context — element-level semantics over the whole-spec API, plus PNG renders to inspect what you built. |\n| `reference\u002Fworkflows\u002Felement-rep-companion.md` | Design rationale for the element rep (why per-element files instead of a middleware layer). Background reading — not required to use `element-rep.md`. |\n\n## Quick Formula Rules\n\nThe single most common spec error is bare `[column_name]` references to warehouse columns. Full rules in `reference\u002Fspecification\u002Fformulas.md`. Skeleton:\n\n**Outside the element** — use `[SourceName\u002Fcolumn_name]`:\n- Warehouse-table source: `SourceName` = last segment of the `path` array (e.g., `[ORDERS\u002FRevenue]`)\n- Another element: `SourceName` = that element's `name`\n- Join legs: prefix by the leg's `name`, or by the join's top-level `name` for `primarySource` columns\n\n**Inside the same element** — use `[column_name]` (no prefix):\n- References a column defined in this element by its `name` field.\n- A column cannot reference itself (circular reference error).\n\n**Data-model metrics** — use `[Metrics\u002F\u003Cmetric name>]`:\n- `Metrics` is a reserved namespace; use the metric's `name`, not its ID.\n- `[\u003Celement name>\u002F\u003Cmetric>]` is a column reference and can fail with\n  `Dependency not found` even though the metric exists.\n- Confirm the metric survives the data-model GET readback before binding it.\n\n## Troubleshooting\n\n### \"I don't see this field in the skill\"\n\nFetch the OpenAPI. The skill documents stable, common surface area; the API has more. See **Consulting the shapes** above.\n\n### API schema mismatch (skill is stale)\n\nA 400 about request *shape* — `invalid argument`, `unknown field`, `unexpected property`, `missing required field` — usually means the API moved past the skill. Fetch the OpenAPI (see **Consulting the shapes**), diff the live shape for that `kind`, and retry **once** with the correction. Tell the user it looks like the skill is out of date and worth updating through whatever channel they installed it from; don't loop on retries.\n\n### 401 Unauthorized\n\nSigma OAuth tokens expire after ~1 hour. Long workbook-building sessions (orchestrated batch conversions, multi-step iterations, anything that runs >50 minutes) will hit this mid-flight.\n\n**Ruby callers** (`scripts\u002Fwb-rep.rb`, or anything using `scripts\u002Flib\u002Fcode_rep.rb`): there's no automatic refresh-and-retry wrapper in this skill — `wb-rep.rb`'s `api()` helper dies loudly on any non-2xx, including 401. Re-export `SIGMA_API_TOKEN` (`eval \"$(scripts\u002Fget-token.sh)\"`) and re-run the command.\n\n**Bash \u002F curl callers**: re-run `eval \"$(scripts\u002Fget-token.sh)\"` to refresh manually. For long shell loops, wrap the curl in a small helper that retries once on 401:\n\n```bash\nsigma_curl() {\n  local resp code\n  resp=$(curl -sS -w '\\n%{http_code}' -H \"Authorization: Bearer $SIGMA_API_TOKEN\" \"$@\")\n  code=$(echo \"$resp\" | tail -1)\n  if [ \"$code\" = \"401\" ]; then\n    eval \"$(scripts\u002Fget-token.sh)\"\n    resp=$(curl -sS -w '\\n%{http_code}' -H \"Authorization: Bearer $SIGMA_API_TOKEN\" \"$@\")\n  fi\n  echo \"$resp\" | sed '$d'  # strip trailing status code\n}\n```\n\nIf 401 persists after refresh, re-authenticate via `sigma-api`: for client credentials verify `SIGMA_BASE_URL`, `SIGMA_CLIENT_ID`, `SIGMA_CLIENT_SECRET`; for browser login re-run `sigma-api\u002Fscripts\u002Frefresh-token.sh` (or `browser-login.sh` if the refresh token has expired).\n\n### 403 Forbidden on workbook create\n\nThe credentials authenticated but aren't permitted to create workbooks here. Ask the user's Sigma admin to confirm the credential's permissions and folder access.\n\n### \"Invalid column reference\" or formula errors on creation\n\nThe most common spec issue. A bare `[column_name]` was used where `[TABLE\u002Fcolumn_name]` is needed. See `reference\u002Fspecification\u002Fformulas.md` for the full rules and `reference\u002Fworkflows\u002Fvalidate.md` for the manual checklist.\n\n### \"Unknown column\" errors\n\nThe column name in the formula doesn't match what the warehouse actually has. Re-confirm the column names via `GET \u002Fv2\u002Fconnections\u002Ftables\u002F{inodeId}\u002Fcolumns` (raw warehouse names) and the readback (`GET \u002Fv2\u002Fworkbooks\u002F\u003Cid>?includeContents=true`, which may preserve the raw spelling or show Sigma's canonicalized friendly form). Raw names are accepted authoring input; use the returned readback form for later edits.\n\n### `jq` or `yq` not installed\n\n`jq` is used for OpenAPI inspection (the OpenAPI is JSON). `yq` is used for workbook-spec inspection (specs are YAML).\n\n- `jq`: `brew install jq` (macOS) or `apt install jq` (Debian\u002FUbuntu).\n- `yq`: **two different tools share this name** — the Go **mikefarah\u002Fyq** (`brew install yq`) and the Python **`pip install yq`** wrapper around jq. *Reading* works the same in both (`yq -r '.workbookId' f.yaml`), but *in-place editing differs*: mikefarah uses `yq -i '…' f.yaml`, while the Python wrapper needs `yq -y -i '…' f.yaml`. Run `yq --help` to see which you have and adapt.\n\n### Cryptic validation errors \u002F silent bad data\n\nSee `reference\u002Fworkflows\u002Fvalidate.md` for `contents.elements[N]` and layout error triage.\n","# Sigma Workbooks (Spec via REST API)\n\nThis skill helps you build effective Sigma workbooks by **navigating the Sigma OpenAPI** and applying **style guidance + proven recipes** beyond what the OpenAPI alone teaches.\n\n## Scope\n\nThe workbook **spec** — the JSON you send as the `contents` field in `POST \u002Fv2\u002Fworkbooks` (or `PUT \u002Fv2\u002Fworkbooks\u002F{id}\u002Fcontents`), defining pages, elements, sources, formulas, and layout. Layout supports grid placement plus responsive stack containers. Lifecycle around the workbook (embeds, grants, materialization schedules, bookmarks, sharing) is a separate API surface and out of scope here.\n\n## Sources of truth\n\nSigma's public API docs are an index at `https:\u002F\u002Fhelp.sigmacomputing.com\u002Fopenapi.json` that lists two **canonical split specs** (split from one large spec to fix compilation \u002F out-of-memory errors — so the structure changed subtly). **That index now serves an HTML page, not JSON** (verified 2026-08-05) — it renders links to the two specs rather than returning a machine-readable list, so treat it as a human landing page and go straight to the two URLs below:\n\n1. **`https:\u002F\u002Fhelp.sigmacomputing.com\u002Fopenapi\u002Fopenapi\u002Fsigma-rest-api.json`** — the REST API: endpoint request\u002Fresponse shapes (workbooks, data models, members, connections, exports, materialization, …). Use for API *calls*.\n2. **`https:\u002F\u002Fhelp.sigmacomputing.com\u002Fopenapi\u002Fopenapi\u002Fcode-representation.json`** — the \"code representation\" (as-code) spec. Today it documents the **data-model** spec (`\u002Fv2\u002FdataModels\u002Fspec`); use it for data-model element shapes.\n\n**Workbook element\u002Fcontrol\u002Fformat shapes** (the `bar-chart` \u002F `kpi-chart` \u002F `control` \u002F format `kind`s that go under a workbook's `contents`) are **not inlined in either split spec** — get them from one of, roughly in this order.\n\n> **The split specs don't document the workbook content endpoints in any depth**: `sigma-rest-api.json` documents `GET \u002Fv2\u002Fworkbooks\u002F{id}`, `POST \u002Fv2\u002Fworkbooks`, and `PUT \u002Fv2\u002Fworkbooks\u002F{id}\u002Fcontents` only at the bare resource-metadata level — the `contents` body itself (element\u002Fcontrol\u002Fformat shapes) isn't inlined — and `code-representation.json` carries only the two `\u002Fv2\u002FdataModels\u002Fspec*` paths. So for workbook authoring the split specs are not merely missing the inlined element shapes; the `contents` shape itself is absent. Use a per-endpoint reference page, the compiled asset, or a live readback (all below).\n\n- **A live workbook readback** — `GET \u002Fv2\u002Fworkbooks\u002F{id}?includeContents=true` on the user's org. Read literal elements from flat `contents.elements[]`; pages, overlays, and panels are metadata and layout determines placement.\n- **A single endpoint's stable reference page** — `https:\u002F\u002Fhelp.sigmacomputing.com\u002Freference\u002F\u003Cendpoint-slug>`. Use it to confirm one endpoint's current request\u002Fresponse envelope. Create accepts `{name, folderId, description?, contents: {...}}`; update (`PUT ...\u002Fcontents`) accepts exactly `{contents: {...}, documentVersion?}`. \u003C!-- pragma: allowlist secret -->\n- **The full compiled OpenAPI** — one document covering every workbook `kind`, and the **only** source that documents the workbook `contents` shape at all. Use it for bulk discovery (\"list every kind the API accepts\") that no single per-endpoint page can do. **This is the canonical, stable, unauthenticated URL — use it directly:**\n\n  ```\n  https:\u002F\u002Fassets.sigmacomputing.com\u002Fopenapi\u002Fpublic-rest-api\u002Fsigma-computing-public-rest-api.json\n  ```\n\n### Fetching the compiled asset\n\n```bash\ncurl -sfL https:\u002F\u002Fassets.sigmacomputing.com\u002Fopenapi\u002Fpublic-rest-api\u002Fsigma-computing-public-rest-api.json \\\n  -o \u002Ftmp\u002Fsigma-api.json\n```\n\nPlain `GET`, no auth, no signature, no content hash — safe to hardcode. Title \"Sigma Computing Public REST API\", `version: 2.0.0`, ~6.8 MB (it uses `$ref`s into `components.schemas`, so **deref as you walk** — element kinds are behind `#\u002Fcomponents\u002Fschemas\u002FWorkbookElement`).\n\n> **Do not use the old Fern docs asset** (`fdr-prod-docs-files-public.s3.amazonaws.com\u002Fsigma.docs.buildwithfern.com\u002F\u003Chash>\u002F…`). It is content-addressed, now requires AWS presigned query params (a bare fetch 403s), and — the reason that actually matters — **it lags the live API**. As of 2026-08-05 it was missing report content support entirely, still documented the pre-`contents`-wrapper request body, and **did not contain the `repeated-container` element kind**, which caused this skill to previously assert that repeated containers were not spec-authorable. They are. Working from a stale asset produces confidently wrong documentation; prefer the `assets.sigmacomputing.com` URL above, and treat a live workbook readback as the tiebreaker.\n\nThe old `help.sigmacomputing.com\u002Fopenapi.json` index is now an HTML landing page and does not link the compiled asset at all.\n\nWhen this skill and the spec (or a live readback) disagree, the spec wins. When a feature isn't covered here, consult the spec \u002F a live workbook and use what it documents.\n\n## Consulting the shapes (per-endpoint pages, compiled OpenAPI, or a live readback)\n\n**The field lists and examples in this skill are illustrative, not exhaustive** — when you need the complete, current shape of anything, pick the right tool for the question:\n\n- **One endpoint, one doubt** (does this field still exist, is the body wrapped or flat, what's required) — go straight to that endpoint's stable reference page, `https:\u002F\u002Fhelp.sigmacomputing.com\u002Freference\u002F\u003Cendpoint-slug>` (see *Sources of truth*). No caching, no `jq`, just read the page.\n- **Every `kind` the API accepts, or every field on a `kind`** (bulk discovery — e.g. building out `reference\u002Fspecification\u002F*.md`) — the per-endpoint pages don't help here (one endpoint each); use the compiled OpenAPI or a live workbook readback instead. Fetch the compiled spec once per session and inspect with `jq`:\n\n```bash\n# Assumes \u002Ftmp\u002Fsigma-api.json from \"Fetching the compiled asset\" above.\n# If a field looks wrong, check that field's per-endpoint page, or read a live workbook spec\n# (GET \u002Fv2\u002Fworkbooks\u002F{id}?includeContents=true) and navigate contents.elements[] by kind.\n\n# The workbook create request body. NOTE: the outer object is {name, folderId, description?, contents},\n# so elements\u002Fpages\u002Foverlays\u002Fpanels\u002Flayout\u002Fsettings\u002Fagents are under .contents:\njq '.paths.\"\u002Fv2\u002Fworkbooks\".post.requestBody.content.\"application\u002Fjson\".schema' \u002Ftmp\u002Fsigma-api.json\n```\n\nElement, source, control, and format shapes are identified by their `kind` value (e.g. `bar-chart`, `kpi-chart`, `join`, `warehouse-table`) rather than by a top-level schema name. They live in `components.schemas` and are reached by `$ref` (element kinds hang off `#\u002Fcomponents\u002Fschemas\u002FWorkbookElement`) — so **deref as you walk** if you're writing your own traversal. The `jq` recipes below scan the whole document, so they work regardless:\n\n```bash\n# List every kind the spec accepts (elements, sources, controls, formats, …):\njq -r '[.. | objects | select(.properties.kind.enum) | .properties.kind.enum[0]] | unique[]' \u002Ftmp\u002Fsigma-api.json\n\n# Full field list (required + optional) for one kind — swap bar-chart for any kind above:\njq --arg k bar-chart 'first(.. | objects | select((.allOf? and any(.allOf[]?; .properties?.kind?.enum==[$k])) or .properties?.kind?.enum==[$k]))\n  | {required: ([.allOf[]?.required \u002F\u002F .required] | add | unique), properties: ([(.allOf[]?.properties \u002F\u002F .properties) | keys[]] | unique)}' \u002Ftmp\u002Fsigma-api.json\n\n# The full nested shape for that kind (to inspect sub-objects like source, yAxis, format, comparison):\njq --arg k bar-chart 'first(.. | objects | select((.allOf? and any(.allOf[]?; .properties?.kind?.enum==[$k])) or .properties?.kind?.enum==[$k]))' \u002Ftmp\u002Fsigma-api.json\n```\n\n`WebFetch` works for the JSON too. Either path is fine.\n\nNo `curl`\u002F`jq` on the machine (e.g. Windows without WSL)? `scripts\u002Fwb-rep.rb`\nships a `capabilities` subcommand that does the same three queries with\npure-Ruby `Net::HTTP` + `JSON.parse` — no external tools required:\n\n```bash\nruby scripts\u002Fwb-rep.rb capabilities                          # list every kind\nruby scripts\u002Fwb-rep.rb capabilities --kind bar-chart          # field list for one kind\nruby scripts\u002Fwb-rep.rb capabilities --kind bar-chart --field source  # one field's shape\n```\n\n**Why bother:** the API ships new fields and viz configurations regularly, and this skill covers the common surface, not every field. If you want a capability and don't see it documented here, **assume it may exist and check the spec before concluding it doesn't** — the `kind` query above answers in seconds.\n\n## Auth\n\nAuthenticate via the `sigma-api` skill first to populate `$SIGMA_BASE_URL` and `$SIGMA_API_TOKEN`. Two options there: **client credentials** (`SIGMA_CLIENT_ID`\u002F`SIGMA_CLIENT_SECRET`, best for headless\u002Fautomation) or **interactive browser login** (`sigma-api\u002Fscripts\u002Fbrowser-login.sh` → refresh headlessly with `refresh-token.sh`, no client ID\u002Fsecret). Either yields a `$SIGMA_API_TOKEN`; the rest of this skill is identical.\n\n## Recommended Workflow\n\nThese are guidelines, not mandates — but they prevent the failure modes that show up most often when drafting from scratch.\n\n> **Schema drift signal:** an error about request *shape* (`invalid argument`, `unknown field`, `missing required field`, `unexpected property`) usually means this skill is stale on that detail. Fetch the OpenAPI and compare; the canonical shape is there.\n\n### Step 0 — Authenticate, capture user identity\n\n```bash\nUSER_ID=$(curl -s -H \"Authorization: Bearer $SIGMA_API_TOKEN\" \\\n  \"$SIGMA_BASE_URL\u002Fv2\u002Fwhoami\" | jq -r '.userId')\n\nHOME_FOLDER_ID=$(curl -s -H \"Authorization: Bearer $SIGMA_API_TOKEN\" \\\n  \"$SIGMA_BASE_URL\u002Fv2\u002Fmembers\u002F$USER_ID\" | jq -r '.homeFolderId')\n```\n\nIf the user provided a **target image or design artifact** (a screenshot,\nmockup, PDF, or Claude-generated app design they want reproduced), pause here\nand load `reference\u002Fworkflows\u002Ffrom-image.md` — it adds mandatory whole-screen\ninventory, behavior classification, design-manifest, native-first routing,\nrender-diff, and iteration gates that happen *before and alongside* normal data\ndiscovery. The standard workflow alone tends to reproduce the data visuals\nwhile missing the app shell and behavior.\n\nIf the user asked to generate \u002F build \u002F scaffold a Sigma **app** (planning,\napproval, allocation, exception, or an unspecified “app”) and did **not**\nsupply a target image, pause here and load\n`reference\u002Fworkflows\u002Fgenerate-apps.md` — it classifies the app type,\n**interviews** before it builds (which fields users may edit, whether the\nworkflow needs approvals, whether to add a Sigma Agent and what it is\nfor), records an intake manifest, states a build plan, and clones a\nbest-practice **architecture** fixture.\nDesign is a separate pass: load `styling.md` as a library and compose for\nthis type (do not stamp the five-recipe dashboard *or* the navy-hero\ncommand-center example). A\ntarget image still wins: load `from-image.md` instead.\n\n### Step 1 — Find a reference workbook to study\n\nAny existing workbook on the user's org doubles as a template. List and pick one with similar content:\n\n```bash\ncurl -s -H \"Authorization: Bearer $SIGMA_API_TOKEN\" \\\n  \"$SIGMA_BASE_URL\u002Fv2\u002Fworkbooks?limit=50\" | jq '.entries[] | {workbookId, name}'\n```\n\nIf no relevant workbook exists, pick any — the goal is studying spec structure, not matching content. If the org has no workbooks at all, draft from scratch using the OpenAPI shapes + this skill's recipes.\n\n### Step 2 — Study the reference spec\n\nYAML is the canonical format for workbook specs in this skill — easier to read, diff, and review than JSON. Sigma's API accepts both (`Content-Type: application\u002Fyaml` or `application\u002Fjson`); `Accept: application\u002Fyaml` is the default on `GET \u002Fv2\u002Fworkbooks\u002F\u003Cid>?includeContents=true`. Use `yq` to inspect spec YAML the same way you'd use `jq` on JSON.\n\n```bash\ncurl -s -H \"Authorization: Bearer $SIGMA_API_TOKEN\" \\\n  \"$SIGMA_BASE_URL\u002Fv2\u002Fworkbooks\u002F\u003Creference-workbook-id>?includeContents=true\" \\\n  > \u002Ftmp\u002Freference-spec.yaml\n```\n\nLook at source structure, column IDs, formulas, flat `contents.elements`, page\nmetadata, and layout XML. Do not copy an obsolete `pages[].elements` shape.\n\n### Step 3 — Discover data sources\n\nLoad `reference\u002Fworkflows\u002Fdiscover.md`. Quick summary:\n\n1. `GET \u002Fv2\u002Fconnections` — find the user's connection by name or type.\n2. Ask the user for the table path; verify with `POST \u002Fv2\u002Fconnection\u002F\u003Cid>\u002Flookup`.\n3. Discover columns with the `sigma-api` paginated column helper, which exhausts `GET \u002Fv2\u002Fconnections\u002Ftables\u002F{inodeId}\u002Fcolumns` (the raw response holds only 50 columns by default; full mechanics in `reference\u002Fworkflows\u002Fdiscover.md`). Only fall back to asking the user when the endpoint doesn't return what's needed.\n\n**Never invent column names** — only use names returned by the API or supplied by the user.\n\n**Verify literal values before writing predicates.** If your task involves filtering on a categorical column (e.g., `CountIf([Status] = \"active\")`, `If([Type] = \"sale\", ...)`), you need to know what values that column *actually* contains — the `\u002Fv2\u002Fconnections\u002Ftables\u002F{inodeId}\u002Fcolumns` endpoint gives you names and types but not values. Run a `SELECT DISTINCT \u003Ccol>` via any tool that reaches the warehouse — an MCP server (warehouse or [Sigma](https:\u002F\u002Fhelp.sigmacomputing.com\u002Fdocs\u002Fuse-sigma-mcp-server)), a SQL CLI, or just ask the user. Don't guess literals. See `reference\u002Fworkflows\u002Fdiscover.md`.\n\n**Verify the composed source grain before drafting.** Name the expected grain\nkey (or composite key), then prove that the source as the workbook will read it\nhas one row per key. For a single key, assert\n`COUNT(*) = COUNT(DISTINCT \u003Cgrain-key>)`; for a composite key, group by all key\ncolumns and require zero duplicate groups. For a 1:1 or many:1 join intended to\npreserve the left grain, compare row count and distinct left-grain count before\nand after the join and require both to stay unchanged. Inner joins and\nintentional 1:many joins need a written expected shrink\u002Fexpansion instead.\nDo not draft plausible-looking counts over an unproven fanout. See\n`reference\u002Fworkflows\u002Fdiscover.md`.\n\n### Step 4 — Identify features and load only what you need\n\nMap the user's request to the **Reference Index** below. State the features you identified, then read the listed reference files before drafting. **If the user asks for a feature this skill doesn't cover**, fetch the OpenAPI and inspect the relevant schema.\n\nWhen choosing a visualization, use the data-shape selector at the top of\n`reference\u002Fspecification\u002Fcharts.md` before copying a chart recipe. A ranked\ncategorical comparison defaults to a horizontal bar, not a sorted table used\nas the primary visualization.\n\nIf the user asked to generate an app, run `generate-apps.md` first (Step 0)\nbefore choosing an input-table architecture here. That interview already\nrecorded which fields users may edit, whether the workflow needs\napprovals, and whether to include a workbook agent. Load\n`reference\u002Fspecification\u002Fstyling.md` as a library and compose for this\napp's job — do not stamp the five-pattern exec-dashboard stack or the\nnavy-hero command-center example.\n\nIf the request includes an input table, writeback, “populate,” “seed,” planning,\napproval, allocation, or exception workflow, load\n`reference\u002Fspecification\u002Finput-tables.md` before choosing an architecture.\nCreating an input-table element, loading initial rows, composing a downstream\nread path, and submitting a runtime action are four different operations. Do\nnot substitute actions, unions, or joins for one another when the first\napproach leaves the table empty.\n\n### Step 5 — Draft the spec to a local file\n\nWrite the spec YAML to disk (e.g., `\u002Ftmp\u002Fworkbook-spec.yaml`). YAML is preferred over JSON in this skill — easier to read, diff, and comment for human review. The API accepts either; pick YAML unless something downstream specifically needs JSON. Key rules:\n\n- Every element needs a unique `id` and a descriptive `name`.\n- Every column needs a unique `id`, a `name`, and a `formula`.\n- Follow the formula reference rules in `reference\u002Fspecification\u002Fformulas.md` exactly — most spec errors happen here.\n- **Write explicit `contents.layout` XML whenever elements are non-empty.** It\n  is the source of truth for page\u002Fcontainer\u002Ftab organization.\n- Emit `\u003CElement>` for layout leaves and `\u003CContainer>` for nested grid or stack\n  containers. Use `type=\"grid\"` when children need `gridColumn` \u002F `gridRow`;\n  use `type=\"stack\"` for ordered responsive flow. Stack children omit grid\n  coordinates and may use responsive `\u003CSize>` blocks. Repeated-container\n  elements still use the grid-bodied form. `\u003CTabbedContainer>` \u002F `\u003CTab>` remain\n  valid. Never emit the legacy `\u003CLayoutElement>` \u002F `\u003CGridContainer>` aliases;\n  live verification rejects `\u003CLayoutElement>` (`valid:false`; some API\n  versions returned HTTP 400 instead).\n- Start with 1–2 pages. Add more later via update.\n\nFor **create**, include outer `name`\u002F`folderId` and `contents` with required\n`schemaVersion`, `kind: workbook`, flat `elements`, and metadata-only `pages`.\nOptional `contents` fields include `overlays`, `panels`, `settings`, and `agents`.\nThis skill requires `layout` whenever `elements` is non-empty. See\n`reference\u002Fspecification\u002Fschema.md`.\n\n### Step 6 — Validate the spec\n\n**Run the bundled validator first — do not skip.**\n\n```bash\n.\u002Fscripts\u002Fvalidate-spec.sh \u002Ftmp\u002Fworkbook-spec.yaml\n```\n\nThen do the manual formula pass and final shape checks per `reference\u002Fworkflows\u002Fvalidate.md`. Fix everything reported before continuing.\n\n### Step 7 — Create the workbook\n\n```bash\ncurl -s -X POST -H \"Authorization: Bearer $SIGMA_API_TOKEN\" \\\n  -H \"Content-Type: application\u002Fyaml\" \\\n  -H \"Accept: application\u002Fyaml\" \\\n  --data-binary @\u002Ftmp\u002Fworkbook-spec.yaml \\\n  \"$SIGMA_BASE_URL\u002Fv2\u002Fworkbooks\" > \u002Ftmp\u002Fcreate-response.yaml\n\nWORKBOOK_ID=$(yq -r '.workbookId' \u002Ftmp\u002Fcreate-response.yaml)\ncp \u002Ftmp\u002Fworkbook-spec.yaml \"\u002Ftmp\u002Fworkbook-spec-${WORKBOOK_ID}.yaml\"\n```\n\nPersist the spec after a successful create so subsequent `PUT` updates can start from it. Report **both** the workbook URL **and** the saved spec path.\n\nIf creation fails, read the error, fix the spec, re-validate, retry. See `reference\u002Fworkflows\u002Fvalidate.md` for decoding cryptic errors.\n\n### Step 7b — Verify the workbook actually compiles\n\n**Do not skip.** A successful POST is necessary but not sufficient — Sigma accepts specs whose formulas don't resolve, then surfaces the failures at query time by embedding the error as a string literal in the compiled SQL (`'Unknown column \"[X]\"'`, `'Circular column reference to [Y]'`). Affected elements render empty in the UI. Only Sigma's compiler knows whether your formula references actually resolve.\n\n```bash\n.\u002Fscripts\u002Fverify-workbook.sh \"$WORKBOOK_ID\"\n```\n\nThe script reads `SIGMA_BASE_URL` and `SIGMA_API_TOKEN` from its environment,\nso they must be **exported**, not just set in your shell. Run `export` on both,\nor put them in front of the command\n(`SIGMA_BASE_URL=… SIGMA_API_TOKEN=… .\u002Fscripts\u002Fverify-workbook.sh …`). If\nthey're missing, the script exits 2 without sending a request.\n\nIf any element reports `[FAIL]`, fix the column formulas in the spec (most often a missing source prefix, a self-referencing column, or a friendly-name mismatch with the warehouse — see `reference\u002Fspecification\u002Fformulas.md`), `PUT` the corrected spec, and re-verify.\n\n### Step 8 — Iterate\n\nAfter initial creation, use `PUT \u002Fv2\u002Fworkbooks\u002F\u003Cid>\u002Fcontents` to add pages or refine the workbook.\n\n**For anything beyond ~1 page \u002F ~10 elements, switch to the element rep** (`reference\u002Fworkflows\u002Felement-rep.md`): `scripts\u002Fwb-rep.rb pull \u003Cid> \u003Cdir>` explodes the spec into one file per element so each edit touches a ~½KB file instead of the whole spec, `push` handles drift-check + validation + PUT, and `render` exports page PNGs you can actually look at. The raw GET\u002FPUT flow below remains fine for small workbooks and one-off tweaks.\n\n> **IDs are preserved on CREATE.** The `id` values you POST (pages, elements, columns) are kept verbatim, and `layout` `elementId` references stay valid — so you can edit your saved spec and `PUT` it back, re-wrapped as just `{contents: {...}}` (see below — PUT does not take the outer `name`\u002F`folderId`). `GET` the current spec first only if you don't have your latest copy. See `reference\u002Fworkflows\u002Fcrud.md`.\n>\n> **`PUT \u002Fv2\u002Fworkbooks\u002F\u003Cid>\u002Fcontents` is contents-only.** Sending `name`, `folderId`, or `description` alongside `contents` is silently ignored — use `PUT \u002Fv2\u002Ffiles\u002F{fileId}` to rename or move a workbook.\n\n```bash\ncurl -s -H \"Authorization: Bearer $SIGMA_API_TOKEN\" \\\n  \"$SIGMA_BASE_URL\u002Fv2\u002Fworkbooks\u002F\u003Cworkbook-id>?includeContents=true\" \\\n  > \u002Ftmp\u002Fcurrent-spec.yaml\n\n# Edit \u002Ftmp\u002Fcurrent-spec.yaml inside .contents; preserve elements, pages,\n# overlays, panels, layout, settings, and agents.\n# then PUT only the contents object — see reference\u002Fworkflows\u002Fcrud.md for why\n# sending the outer name\u002FfolderId\u002Fresponse-only fields alongside it is ignored:\nyq '{\"contents\": .contents}' \u002Ftmp\u002Fcurrent-spec.yaml > \u002Ftmp\u002Fcurrent-spec-put.yaml\ncurl -s -X PUT -H \"Authorization: Bearer $SIGMA_API_TOKEN\" \\\n  -H \"Content-Type: application\u002Fyaml\" \\\n  -H \"Accept: application\u002Fyaml\" \\\n  --data-binary @\u002Ftmp\u002Fcurrent-spec-put.yaml \\\n  \"$SIGMA_BASE_URL\u002Fv2\u002Fworkbooks\u002F\u003Cworkbook-id>\u002Fcontents\" | yq .\n\ncp \u002Ftmp\u002Fcurrent-spec.yaml \"\u002Ftmp\u002Fworkbook-spec-\u003Cworkbook-id>.yaml\"\n.\u002Fscripts\u002Fverify-workbook.sh \"\u003Cworkbook-id>\"\n```\n\n### Step 9 — Report back\n\nReport the workbook URL and the saved spec path. **Do not tack on generic \"improvement ideas\" or \"next steps.\"** Match the response to what was asked.\n\nSurface follow-up items only when they're load-bearing, and name them concretely:\n\n- **Tradeoffs you made during the build** — dropped a chart, simplified a formula, skipped a control because the shape wasn't in your reference.\n- **Obvious gaps revealed by the column list** — e.g., the user asked for \"sales by region\" and the table has a `region_tier` column that would make the breakdown richer. One sentence, named.\n\nIf none apply, just report the URL + spec path and stop.\n\n## Reference Index\n\nThe reference is feature-sliced — don't read every file up-front. The index has three sections: **elements** (the visual \u002F interactive pieces), **sources** (where each element gets its data), and **cross-cutting** (formulas, layout, formatting, validation, CRUD).\n\n### Elements\n\n| File | When to load |\n|------|--------------|\n| `reference\u002Fspecification\u002Ftables.md` | Table element, tabular data, data grid, spreadsheet-style list. Also **element-level filters** (`list`, `top-n`, `number-range`, `date-range`, `text-match`, `hierarchy`), groupings (pivot, group by), the `pivot-table` and editable `input-table` element kinds, and `conditionalFormats` (threshold-based cell coloring, on pivot\u002Finput tables). |\n| `reference\u002Fspecification\u002Fcharts.md` | **Load before choosing a visualization.** Data-shape → chart selection, then chart\u002Fgraph recipes for line \u002F bar \u002F column \u002F stacked \u002F grouped \u002F combo \u002F donut \u002F pie \u002F scatter \u002F waterfall \u002F share-of \u002F breakdown. Cartesian axes, color, trellis, legend, trendlines, reference marks. |\n| `reference\u002Fspecification\u002Fmaps.md` | Map visualizations — `geography-map` (GeoJSON shapes), `point-map` (lat\u002Flong bubbles), `region-map` (states \u002F counties \u002F countries). |\n| `reference\u002Fspecification\u002Fkpis.md` | KPI, stat, big number, single value, metric card — including layout \u002F value styling, the comparison Δ badge (`comparisonColumn` + `comparison:{display:\"delta\"}` — spec-authorable and readback-stable; the house default), and the trend\u002Fsparkline block (still UI-bound). |\n| `reference\u002Fspecification\u002Fcontrols.md` | Filter, dropdown, picker, multi-select, date range, date picker, text filter, number range, slider, segmented, hierarchy, legend, and drill controls. Also entry controls and formula handles. |\n| `reference\u002Fspecification\u002Fcontent-elements.md` | The non-data elements — `text` (Markdown + inline styling), `image`, `divider`, `embed` (external URLs), `page-break` (PDF\u002Fprint pagination), `form`, `progress`, `navigation`, `plugin`. Titles, callouts, logos, rules, embedded content. |\n| `reference\u002Fspecification\u002Finput-tables.md` | **Load for every input-table or “populate\u002Fseed” request.** Operational supplement for `input-table`: supported row-arrival decision tree, write connection, UI-only published permission, publish gate, linked-key correlation, warehouse views, and why actions\u002Funions\u002Fjoins are not bulk seeding mechanisms. |\n| `reference\u002Fspecification\u002Fstyling.md` | **Load when composing a look from spec.** A library of options (hero bands, KPI cards, gradients, section headers, chart color, formats) plus an anti-pattern checklist. Not a house style — do not stamp the five-pattern exec dashboard onto every app. PNG fail: skill chrome, invisible entry controls, Dark-by-default on data-entry, 3-KPI status on operational apps. |\n| `reference\u002Fspecification\u002Fagents.md` | Workbook AI agent, chat with your data, agent, chatbot, AI assistant. The workbook-top-level `agents:[]` array + page-level `chat` element; Analyze \u002F Configure \u002F Navigate \u002F Act capability profiles; direct control\u002Fnavigation\u002Fwrite action tools; read-only analyst vs. operator; the four `tools[]` kinds (`action`, `mcp-connector`, `warehouse-agent`, `search-service`), `greeting`, `requiresApproval`, why action sequences are referenceable but not authorable; org-feature gate + graceful degrade. |\n\n### Sources\n\n| File | When to load |\n|------|--------------|\n| `reference\u002Fspecification\u002Fsources-warehouse.md` | Always — load before drafting any spec. Warehouse-table source (Snowflake, BigQuery, Databricks, Redshift, Postgres\u002FMySQL). |\n| `reference\u002Fspecification\u002Fsources.md` | Reference another chart\u002Ftable\u002Felement, derive from existing element, join, combine tables, data model \u002F semantic-layer source, custom SQL, union, transpose, unpivot. |\n\n### Cross-cutting\n\n| File | When to load |\n|------|--------------|\n| `reference\u002Fspecification\u002Fschema.md` | Always — wrapped shape, required flat `contents.elements`, metadata-only pages, overlays, panels, settings, backgrounds, and the PUT-only-contents rule. |\n| `reference\u002Fspecification\u002Fformulas.md` | Always — load before drafting any spec. Formula syntax, qualification, special characters, the #1 mistake. |\n| `reference\u002Fspecification\u002Fformatting.md` | Format, currency, percentage, date format, decimals — column formatting. |\n| `reference\u002Fspecification\u002Flayout.md` | **Always load.** Required layout policy; page\u002Fcontainer organization; backgrounds\u002Fspacing; panels, headers, sidebars, navigation; repeated and tabbed containers. |\n| `reference\u002Fspecification\u002Fexample-full.yaml` | A real multi-page reference spec (KPIs, charts, joins, controls, layout) — copy shapes from when in doubt. |\n| `reference\u002Fspecification\u002Fcomparative-kpi-card.yaml` | Minimal clone-able comparative KPI card — `value` + `comparisonColumn` + `comparison:{display:\"delta\"}`, the house-default comparative shape (see `kpis.md`). |\n| `reference\u002Fspecification\u002Ftrellis-chart-support.md` | The empirical coverage matrix for trellis charts — how each kind was verified live (POST + readback + render). Load when `charts.md`'s trellis guidance needs the underlying evidence. |\n\n### Workflows\n\n| File | When to load |\n|------|--------------|\n| `reference\u002Fworkflows\u002Fdiscover.md` | Finding connections, tables, and column names. Load before composing a new spec. |\n| `reference\u002Fworkflows\u002Fcomposition.md` | Open-ended design decisions, named asymmetric splits\u002Fmosaic, and the content-prescriptive `ledger` record-lookup archetype. Covers when to ask, chart-vs-table defaults, editorial sizing, and hidden source pages. Load before drafting when the prompt leaves design choices unmade or asks users to find\u002Fbrowse records. |\n| `reference\u002Fworkflows\u002Fapp-compositions.md` | **Operational app visual composition.** Load with `generate-apps.md`: keeps semantic architecture separate from appearance, selects `workbench` \u002F `queue-rail` \u002F `builder-preview`, requires a local design manifest, emits asymmetric work-surface-first layout via `Composition.compose`, and adds a two-render PNG polish gate. |\n| `reference\u002Fworkflows\u002Factions.md` | Buttons, write-back, and **all twelve** action effects — insert\u002Fupdate\u002Fdelete-rows, clear-control, set-control-value, open\u002Fclose-overlay (modal **and** drawer), open-url, open-document (incl. passing `targetControls` into another workbook), navigate, select-tab, refresh-element — plus the append-only-log pattern and the masked-error catalog. Load when the user wants a button, a \"log\u002Fsave\u002Fsubmit\" action, tab\u002Fpage navigation, a deep link, or a write-back workflow. |\n| `reference\u002Fworkflows\u002Fgenerate-apps.md` | **Generate a Sigma app.** Load first when the user asks to build a planning, approval, allocation, or exception app (and did not supply a target image). Classifies the type, **interviews** for editable fields \u002F approvals \u002F an Analyze–Configure–Navigate–Act workbook-agent contract, clones an architecture fixture (planning is a multi-page studio shell), then **composes** an app shell + `workbench` \u002F `queue-rail` \u002F `builder-preview` look. Fail the PNG pass on skill chrome, invisible entry controls, Dark-by-default on data-entry, a 3-KPI status strip, an empty work surface, or `Unknown column` \u002F `Invalid Query` on a page measure. |\n| `reference\u002Fworkflows\u002Ffixtures\u002FREADME.md` | Rules for cloning an operational-app architecture fixture (placeholders only — never commit real org\u002Fuser\u002Ffolder\u002Fworkbook IDs). Load alongside `generate-apps.md`, not standalone. |\n| `reference\u002Fworkflows\u002Ffixtures\u002Fplanning-app.yaml` | Starting spec for a planning app. Clone via `generate-apps.md`; don't read standalone. |\n| `reference\u002Fworkflows\u002Ffixtures\u002Fallocation-app.yaml` | Starting spec for an allocation app. Clone via `generate-apps.md`; don't read standalone. |\n| `reference\u002Fworkflows\u002Ffixtures\u002Fapproval-app.yaml` | Starting spec for an approval app. Clone via `generate-apps.md`; don't read standalone. |\n| `reference\u002Fworkflows\u002Ffixtures\u002Fexception-app.yaml` | Starting spec for an exception app. Clone via `generate-apps.md`; don't read standalone. |\n| `reference\u002Fworkflows\u002Fplanning-apps.md` | **Scenario planning, budgeting, and forecasting apps.** Scenario × Period × Planning Line grain, governed baseline, scenario matrix, linked override grid, financial sign, filter-propagation choices, approval\u002Faudit, and runtime gates. |\n| `reference\u002Fworkflows\u002Fallocation-apps.md` | **Allocation and capacity apps.** Budget\u002Ftarget vs. baseline at Period × Allocation Dimension grain, linked editable units\u002Fuplifts, working allocation, request queue, and exact variance gates. |\n| `reference\u002Fworkflows\u002Fapproval-apps.md` | **Approval and decision apps.** Stable entity-key queues, counter-values, immutable audit logs, one-row status updates, agent boundaries, and runtime tests. |\n| `reference\u002Fworkflows\u002Fexception-apps.md` | **Exception command centers.** Stable operational-key queues, deterministic recommendations, overrides, ownership, resolution logs, and exact KPI-delta tests. |\n| `reference\u002Fworkflows\u002Fcrud.md` | POST \u002F GET \u002F PUT against the workbook content endpoints. Load when creating, retrieving, or updating a workbook. |\n| `reference\u002Fworkflows\u002Fvalidate.md` | Pre-submit + post-create structural validation. Load before any POST or PUT; for joins, controls, writeback, agents, or numeric claims continue to `runtime-verification.md`. |\n| `reference\u002Fworkflows\u002Fruntime-verification.md` | **Runtime evidence loop:** compile, render, export, cardinality, numeric oracle, published writeback, linked-row correlation, control scope, approval scope, and agent tests. |\n| `reference\u002Fworkflows\u002Ffrom-image.md` | The user supplied a target image or Claude design artifact to reproduce. Load *before* discovery — it inventories the entire app shell and behavior, routes native Sigma vs plugin\u002FUI-only surfaces, requires a local design manifest, and enforces first-render → diff → final-render acceptance. |\n| `reference\u002Fworkflows\u002Felement-rep.md` | **Large or multi-page workbooks, parallel element work, or iterative refinement.** `scripts\u002Fwb-rep.rb` explodes the spec into one small file per element (pull\u002Fstatus\u002Fpush\u002Frender) so edits never drag the whole spec through context — element-level semantics over the whole-spec API, plus PNG renders to inspect what you built. |\n| `reference\u002Fworkflows\u002Felement-rep-companion.md` | Design rationale for the element rep (why per-element files instead of a middleware layer). Background reading — not required to use `element-rep.md`. |\n\n## Quick Formula Rules\n\nThe single most common spec error is bare `[column_name]` references to warehouse columns. Full rules in `reference\u002Fspecification\u002Fformulas.md`. Skeleton:\n\n**Outside the element** — use `[SourceName\u002Fcolumn_name]`:\n- Warehouse-table source: `SourceName` = last segment of the `path` array (e.g., `[ORDERS\u002FRevenue]`)\n- Another element: `SourceName` = that element's `name`\n- Join legs: prefix by the leg's `name`, or by the join's top-level `name` for `primarySource` columns\n\n**Inside the same element** — use `[column_name]` (no prefix):\n- References a column defined in this element by its `name` field.\n- A column cannot reference itself (circular reference error).\n\n**Data-model metrics** — use `[Metrics\u002F\u003Cmetric name>]`:\n- `Metrics` is a reserved namespace; use the metric's `name`, not its ID.\n- `[\u003Celement name>\u002F\u003Cmetric>]` is a column reference and can fail with\n  `Dependency not found` even though the metric exists.\n- Confirm the metric survives the data-model GET readback before binding it.\n\n## Troubleshooting\n\n### \"I don't see this field in the skill\"\n\nFetch the OpenAPI. The skill documents stable, common surface area; the API has more. See **Consulting the shapes** above.\n\n### API schema mismatch (skill is stale)\n\nA 400 about request *shape* — `invalid argument`, `unknown field`, `unexpected property`, `missing required field` — usually means the API moved past the skill. Fetch the OpenAPI (see **Consulting the shapes**), diff the live shape for that `kind`, and retry **once** with the correction. Tell the user it looks like the skill is out of date and worth updating through whatever channel they installed it from; don't loop on retries.\n\n### 401 Unauthorized\n\nSigma OAuth tokens expire after ~1 hour. Long workbook-building sessions (orchestrated batch conversions, multi-step iterations, anything that runs >50 minutes) will hit this mid-flight.\n\n**Ruby callers** (`scripts\u002Fwb-rep.rb`, or anything using `scripts\u002Flib\u002Fcode_rep.rb`): there's no automatic refresh-and-retry wrapper in this skill — `wb-rep.rb`'s `api()` helper dies loudly on any non-2xx, including 401. Re-export `SIGMA_API_TOKEN` (`eval \"$(scripts\u002Fget-token.sh)\"`) and re-run the command.\n\n**Bash \u002F curl callers**: re-run `eval \"$(scripts\u002Fget-token.sh)\"` to refresh manually. For long shell loops, wrap the curl in a small helper that retries once on 401:\n\n```bash\nsigma_curl() {\n  local resp code\n  resp=$(curl -sS -w '\\n%{http_code}' -H \"Authorization: Bearer $SIGMA_API_TOKEN\" \"$@\")\n  code=$(echo \"$resp\" | tail -1)\n  if [ \"$code\" = \"401\" ]; then\n    eval \"$(scripts\u002Fget-token.sh)\"\n    resp=$(curl -sS -w '\\n%{http_code}' -H \"Authorization: Bearer $SIGMA_API_TOKEN\" \"$@\")\n  fi\n  echo \"$resp\" | sed '$d'  # strip trailing status code\n}\n```\n\nIf 401 persists after refresh, re-authenticate via `sigma-api`: for client credentials verify `SIGMA_BASE_URL`, `SIGMA_CLIENT_ID`, `SIGMA_CLIENT_SECRET`; for browser login re-run `sigma-api\u002Fscripts\u002Frefresh-token.sh` (or `browser-login.sh` if the refresh token has expired).\n\n### 403 Forbidden on workbook create\n\nThe credentials authenticated but aren't permitted to create workbooks here. Ask the user's Sigma admin to confirm the credential's permissions and folder access.\n\n### \"Invalid column reference\" or formula errors on creation\n\nThe most common spec issue. A bare `[column_name]` was used where `[TABLE\u002Fcolumn_name]` is needed. See `reference\u002Fspecification\u002Fformulas.md` for the full rules and `reference\u002Fworkflows\u002Fvalidate.md` for the manual checklist.\n\n### \"Unknown column\" errors\n\nThe column name in the formula doesn't match what the warehouse actually has. Re-confirm the column names via `GET \u002Fv2\u002Fconnections\u002Ftables\u002F{inodeId}\u002Fcolumns` (raw warehouse names) and the readback (`GET \u002Fv2\u002Fworkbooks\u002F\u003Cid>?includeContents=true`, which may preserve the raw spelling or show Sigma's canonicalized friendly form). Raw names are accepted authoring input; use the returned readback form for later edits.\n\n### `jq` or `yq` not installed\n\n`jq` is used for OpenAPI inspection (the OpenAPI is JSON). `yq` is used for workbook-spec inspection (specs are YAML).\n\n- `jq`: `brew install jq` (macOS) or `apt install jq` (Debian\u002FUbuntu).\n- `yq`: **two different tools share this name** — the Go **mikefarah\u002Fyq** (`brew install yq`) and the Python **`pip install yq`** wrapper around jq. *Reading* works the same in both (`yq -r '.workbookId' f.yaml`), but *in-place editing differs*: mikefarah uses `yq -i '…' f.yaml`, while the Python wrapper needs `yq -y -i '…' f.yaml`. Run `yq --help` to see which you have and adapt.\n\n### Cryptic validation errors \u002F silent bad data\n\nSee `reference\u002Fworkflows\u002Fvalidate.md` for `contents.elements[N]` and layout error triage.\n",{"name":5,"description":7},"main","234c4c30e9d45319a33d2ef1a26cc89ad10aeb2a","skills\u002Fsigma-workbooks",8,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills","https:\u002F\u002Fsigmacomputing.com","https:\u002F\u002Fgithub.com\u002Fsigmacomputing","2026-11-10 04:54:22",{"source":8,"skillName":5,"commands":58,"prompt":68,"zipAvailable":69},[59,62,65],{"tool":60,"command":61},"npx","npx skills add sigmacomputing\u002Fsigma-agent-skills --skill sigma-workbooks",{"tool":63,"command":64},"bunx","bunx skills add sigmacomputing\u002Fsigma-agent-skills --skill sigma-workbooks",{"tool":66,"command":67},"pnpm","pnpm dlx skills add sigmacomputing\u002Fsigma-agent-skills --skill sigma-workbooks","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002FSKILL.md",true,[71,77,81,85,89,93,97,101,105,109,113,117,121,125,129,133,137,141,145,149,153,157,161,165,169,173,177,181,185,189,193,197,201,205,209,213,217,221,225,231,235,239,243,247,251,255,259,263,267],{"path":72,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":75,"sourceHtmlUrl":76},"reference\u002Fspecification\u002Fagents.md","REFERENCE","参考文档",15021,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Freference\u002Fspecification\u002Fagents.md",{"path":78,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":79,"sourceHtmlUrl":80},"reference\u002Fspecification\u002Fcharts.md",26904,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Freference\u002Fspecification\u002Fcharts.md",{"path":82,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":83,"sourceHtmlUrl":84},"reference\u002Fspecification\u002Fcomparative-kpi-card.yaml",1586,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Freference\u002Fspecification\u002Fcomparative-kpi-card.yaml",{"path":86,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":87,"sourceHtmlUrl":88},"reference\u002Fspecification\u002Fcontent-elements.md",14844,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Freference\u002Fspecification\u002Fcontent-elements.md",{"path":90,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":91,"sourceHtmlUrl":92},"reference\u002Fspecification\u002Fcontrols.md",19138,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Freference\u002Fspecification\u002Fcontrols.md",{"path":94,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":95,"sourceHtmlUrl":96},"reference\u002Fspecification\u002Fexample-full.yaml",22996,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Freference\u002Fspecification\u002Fexample-full.yaml",{"path":98,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":99,"sourceHtmlUrl":100},"reference\u002Fspecification\u002Fformatting.md",2720,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Freference\u002Fspecification\u002Fformatting.md",{"path":102,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":103,"sourceHtmlUrl":104},"reference\u002Fspecification\u002Fformulas.md",13709,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Freference\u002Fspecification\u002Fformulas.md",{"path":106,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":107,"sourceHtmlUrl":108},"reference\u002Fspecification\u002Finput-tables.md",9833,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Freference\u002Fspecification\u002Finput-tables.md",{"path":110,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":111,"sourceHtmlUrl":112},"reference\u002Fspecification\u002Fkpis.md",8128,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Freference\u002Fspecification\u002Fkpis.md",{"path":114,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":115,"sourceHtmlUrl":116},"reference\u002Fspecification\u002Flayout.md",26662,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Freference\u002Fspecification\u002Flayout.md",{"path":118,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":119,"sourceHtmlUrl":120},"reference\u002Fspecification\u002Fmaps.md",2287,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Freference\u002Fspecification\u002Fmaps.md",{"path":122,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":123,"sourceHtmlUrl":124},"reference\u002Fspecification\u002Fschema.md",9850,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Freference\u002Fspecification\u002Fschema.md",{"path":126,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":127,"sourceHtmlUrl":128},"reference\u002Fspecification\u002Fsources-warehouse.md",2228,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Freference\u002Fspecification\u002Fsources-warehouse.md",{"path":130,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":131,"sourceHtmlUrl":132},"reference\u002Fspecification\u002Fsources.md",8857,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Freference\u002Fspecification\u002Fsources.md",{"path":134,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":135,"sourceHtmlUrl":136},"reference\u002Fspecification\u002Fstyling.md",51107,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Freference\u002Fspecification\u002Fstyling.md",{"path":138,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":139,"sourceHtmlUrl":140},"reference\u002Fspecification\u002Ftables.md",19046,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Freference\u002Fspecification\u002Ftables.md",{"path":142,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":143,"sourceHtmlUrl":144},"reference\u002Fspecification\u002Ftrellis-chart-support.md",8012,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Freference\u002Fspecification\u002Ftrellis-chart-support.md",{"path":146,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":147,"sourceHtmlUrl":148},"reference\u002Fworkflows\u002Factions.md",24475,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Freference\u002Fworkflows\u002Factions.md",{"path":150,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":151,"sourceHtmlUrl":152},"reference\u002Fworkflows\u002Fallocation-apps.md",3417,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Freference\u002Fworkflows\u002Fallocation-apps.md",{"path":154,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":155,"sourceHtmlUrl":156},"reference\u002Fworkflows\u002Fapp-compositions.md",9404,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Freference\u002Fworkflows\u002Fapp-compositions.md",{"path":158,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":159,"sourceHtmlUrl":160},"reference\u002Fworkflows\u002Fapproval-apps.md",3331,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Freference\u002Fworkflows\u002Fapproval-apps.md",{"path":162,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":163,"sourceHtmlUrl":164},"reference\u002Fworkflows\u002Fcomposition.md",27143,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Freference\u002Fworkflows\u002Fcomposition.md",{"path":166,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":167,"sourceHtmlUrl":168},"reference\u002Fworkflows\u002Fcrud.md",8585,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Freference\u002Fworkflows\u002Fcrud.md",{"path":170,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":171,"sourceHtmlUrl":172},"reference\u002Fworkflows\u002Fdiscover.md",11217,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Freference\u002Fworkflows\u002Fdiscover.md",{"path":174,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":175,"sourceHtmlUrl":176},"reference\u002Fworkflows\u002Felement-rep-companion.md",6968,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Freference\u002Fworkflows\u002Felement-rep-companion.md",{"path":178,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":179,"sourceHtmlUrl":180},"reference\u002Fworkflows\u002Felement-rep.md",4791,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Freference\u002Fworkflows\u002Felement-rep.md",{"path":182,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":183,"sourceHtmlUrl":184},"reference\u002Fworkflows\u002Fexception-apps.md",3172,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Freference\u002Fworkflows\u002Fexception-apps.md",{"path":186,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":187,"sourceHtmlUrl":188},"reference\u002Fworkflows\u002Ffixtures\u002Fallocation-app.yaml",6482,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Freference\u002Fworkflows\u002Ffixtures\u002Fallocation-app.yaml",{"path":190,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":191,"sourceHtmlUrl":192},"reference\u002Fworkflows\u002Ffixtures\u002Fapproval-app.yaml",6229,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Freference\u002Fworkflows\u002Ffixtures\u002Fapproval-app.yaml",{"path":194,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":195,"sourceHtmlUrl":196},"reference\u002Fworkflows\u002Ffixtures\u002Fexception-app.yaml",6226,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Freference\u002Fworkflows\u002Ffixtures\u002Fexception-app.yaml",{"path":198,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":199,"sourceHtmlUrl":200},"reference\u002Fworkflows\u002Ffixtures\u002Fplanning-app.yaml",20994,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Freference\u002Fworkflows\u002Ffixtures\u002Fplanning-app.yaml",{"path":202,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":203,"sourceHtmlUrl":204},"reference\u002Fworkflows\u002Ffixtures\u002FREADME.md",2631,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Freference\u002Fworkflows\u002Ffixtures\u002FREADME.md",{"path":206,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":207,"sourceHtmlUrl":208},"reference\u002Fworkflows\u002Ffrom-image.md",16245,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Freference\u002Fworkflows\u002Ffrom-image.md",{"path":210,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":211,"sourceHtmlUrl":212},"reference\u002Fworkflows\u002Fgenerate-apps.md",25189,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Freference\u002Fworkflows\u002Fgenerate-apps.md",{"path":214,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":215,"sourceHtmlUrl":216},"reference\u002Fworkflows\u002Fplanning-apps.md",11507,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Freference\u002Fworkflows\u002Fplanning-apps.md",{"path":218,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":219,"sourceHtmlUrl":220},"reference\u002Fworkflows\u002Fruntime-verification.md",6577,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Freference\u002Fworkflows\u002Fruntime-verification.md",{"path":222,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":223,"sourceHtmlUrl":224},"reference\u002Fworkflows\u002Fvalidate.md",4229,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Freference\u002Fworkflows\u002Fvalidate.md",{"path":226,"resourceType":227,"resourceTypeDesc":228,"sizeBytes":229,"sourceHtmlUrl":230},"scripts\u002Fdesign-artifact.rb","SCRIPT","脚本",10060,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Fscripts\u002Fdesign-artifact.rb",{"path":232,"resourceType":227,"resourceTypeDesc":228,"sizeBytes":233,"sourceHtmlUrl":234},"scripts\u002Flib\u002Factions.rb",10609,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Fscripts\u002Flib\u002Factions.rb",{"path":236,"resourceType":227,"resourceTypeDesc":228,"sizeBytes":237,"sourceHtmlUrl":238},"scripts\u002Flib\u002Fapp_intake.rb",18242,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Fscripts\u002Flib\u002Fapp_intake.rb",{"path":240,"resourceType":227,"resourceTypeDesc":228,"sizeBytes":241,"sourceHtmlUrl":242},"scripts\u002Flib\u002Fcode_rep.rb",8598,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Fscripts\u002Flib\u002Fcode_rep.rb",{"path":244,"resourceType":227,"resourceTypeDesc":228,"sizeBytes":245,"sourceHtmlUrl":246},"scripts\u002Flib\u002Fcomposition.rb",19688,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Fscripts\u002Flib\u002Fcomposition.rb",{"path":248,"resourceType":227,"resourceTypeDesc":228,"sizeBytes":249,"sourceHtmlUrl":250},"scripts\u002Flib\u002Fkpi_card.rb",3297,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Fscripts\u002Flib\u002Fkpi_card.rb",{"path":252,"resourceType":227,"resourceTypeDesc":228,"sizeBytes":253,"sourceHtmlUrl":254},"scripts\u002Flib\u002Frichness.rb",17471,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Fscripts\u002Flib\u002Frichness.rb",{"path":256,"resourceType":227,"resourceTypeDesc":228,"sizeBytes":257,"sourceHtmlUrl":258},"scripts\u002Flib\u002Fstyling.rb",32315,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Fscripts\u002Flib\u002Fstyling.rb",{"path":260,"resourceType":227,"resourceTypeDesc":228,"sizeBytes":261,"sourceHtmlUrl":262},"scripts\u002Fvalidate-spec.sh",10409,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Fscripts\u002Fvalidate-spec.sh",{"path":264,"resourceType":227,"resourceTypeDesc":228,"sizeBytes":265,"sourceHtmlUrl":266},"scripts\u002Fverify-workbook.sh",3077,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Fscripts\u002Fverify-workbook.sh",{"path":268,"resourceType":227,"resourceTypeDesc":228,"sizeBytes":269,"sourceHtmlUrl":270},"scripts\u002Fwb-rep.rb",31761,"https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-workbooks\u002Fscripts\u002Fwb-rep.rb",[272,305,329,352,373,378],{"skillNo":273,"name":274,"nameZh":6,"description":275,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":276,"categories":277,"keywords":286,"publishedAt":44},"01M71RHDYSG56QM7R693SGWG8V","sigma-reports","Build, validate, retrieve, and safely update Sigma report code representations through \u002Fv2\u002Freports. Use for fixed-layout or pixel-perfect reports, executive board packets, wide operational tables, invoices, statements, regulatory documents, and PDF delivery. Covers reusable report scaffolds, report pages, absolute pixel layout, header\u002Ffooter panels, common elements, verification, full-contents replacement, and workbook conversion to reports. Do not use for responsive dashboards; use sigma-workbooks instead. Requires SIGMA_API_TOKEN from the sigma-api skill.","https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-reports\u002FSKILL.md",[278,281],{"categoryNo":279,"categoryName":280,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000002","文档处理",{"categoryNo":282,"categoryName":283,"taxonomyType":284,"taxonomyTypeDesc":285},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",[287,288,25,289,32,290,291,292,293,294,295,296,297,298,299,300,301,302,303,304],"sigma reports","reports","conversion","panels","layout","responsive","token","full","delivery","pixel","PDF","common","dashboards","api","verification","code","update","documents",{"skillNo":306,"name":307,"nameZh":6,"description":308,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":309,"categories":310,"keywords":314,"publishedAt":44},"01M71RH9RGX6RKXJW8E0ENZJFJ","sigma-data-models","Create, retrieve, or modify a Sigma data model spec (the JSON\u002FYAML semantic-layer definition with sources, columns, metrics, relationships, filters, controls, folder groupings, and column-level security) by calling the Sigma REST API directly. Use when the user wants to author a new data model from a description, export\u002Finspect\u002Fdownload an existing model's spec, edit columns or metrics, change a model's source, add relationships or row-level filters, or otherwise round-trip a data model through code. Requires an SIGMA_API_TOKEN — obtain via the sigma-api skill first.","https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-data-models\u002FSKILL.md",[311],{"categoryNo":312,"categoryName":313,"taxonomyType":284,"taxonomyTypeDesc":285},"01JBSEEDCAT000000000000033","数据分析师",[315,316,25,317,318,319,40,293,300,320,321,322,323,324,29,325,326,302,327,328],"sigma data models","models","data","export","filters","sources","columns","model","inspect","layer","when","new","create","change",{"skillNo":330,"name":331,"nameZh":6,"description":332,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":333,"categories":334,"keywords":335,"publishedAt":44},"01M71RH5K6VDAA8JKAEJC640K9","sigma-cli","Drive the full Sigma Computing REST API surface from the local `sigma` binary (Sigma CLI) and its OpenAPI-generated command tree. Use whenever the user wants to call any Sigma endpoint from the command line, needs a uniform `--params` \u002F `--json` shape across resources, wants to install or configure the CLI, or asks about `sigma api …`, `sigma auth login`, `list-prefixes`, or `schema`. Prefer this skill over raw `curl` when the user has the `sigma` binary installed; fall back to `sigma-api` for OAuth fundamentals and direct HTTP.","https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-cli\u002FSKILL.md",[],[336,25,337,338,339,300,340,341,342,343,325,344,345,294,346,347,348,349,350,351],"sigma cli","cli","direct","configure","auth","command","line","needs","login","resources","local","across","back","install","generated","list",{"skillNo":353,"name":354,"nameZh":6,"description":355,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":356,"categories":357,"keywords":362,"publishedAt":44},"01M71RH1VNAXTYYYV9DKV057A4","sigma-api","Authenticate against the Sigma Computing REST API and obtain a bearer token. Use whenever the user wants to call the Sigma API directly with curl\u002FHTTP, exchange OAuth client credentials for an access token, sign in interactively via a browser OAuth login (authorization-code + PKCE), configure SIGMA_BASE_URL \u002F SIGMA_CLIENT_ID \u002F SIGMA_CLIENT_SECRET, troubleshoot 401\u002F403 responses, or pick the right Sigma API hostname for their cloud. Use as a prerequisite when another Sigma skill needs an SIGMA_API_TOKEN.","https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsigma-api\u002FSKILL.md",[358,361],{"categoryNo":359,"categoryName":360,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000010","后端与接口",{"categoryNo":282,"categoryName":283,"taxonomyType":284,"taxonomyTypeDesc":285},[363,300,25,364,365,366,367,368,343,369,325,30,344,370,371,38,293,372,339,302],"sigma api","troubleshoot","browser","secret","credentials","access","responses","URL","hostname","pick",{"skillNo":374,"name":5,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":375,"categories":376,"keywords":377,"publishedAt":44},"01M71RGZTNJ2YQJTZ57BARBYM6","https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002F.cortex\u002Fskills\u002Fsigma-workbooks\u002FSKILL.md",[],[24,25],{"skillNo":379,"name":274,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":380,"categories":381,"keywords":382,"publishedAt":44},"01M71RGY6ZWV700RA2XCJDK912","https:\u002F\u002Fgithub.com\u002Fsigmacomputing\u002Fsigma-agent-skills\u002Fblob\u002Fmain\u002F.cortex\u002Fskills\u002Fsigma-reports\u002FSKILL.md",[],[288,287,25]]