Sigma AI Coding-Agent Skills

Skills for building and maintaining analytics in Sigma Computing from any AI coding agent.

The skills split along the surfaces of the Sigma REST API: data models, responsive workbooks, fixed-layout reports, and utility skills that orchestrate them. Each skill is a self-contained directory.

Quick start

These are coding-agent tools, not an end-user Sigma wizard. They can serve business users through an agent, but installation and API access still need a technical owner.

Claude Code

/plugin marketplace add twells89/sigma-skills
/plugin install sigma-skills@sigma-skills

This is the lowest-friction path: no clone or symlinks.

Cursor, Codex, Cline, Continue

git clone https://github.com/twells89/sigma-skills.git ~/sigma-skills
cd ~/sigma-skills
./scripts/check-prerequisites.sh sigma-workbooks
./scripts/install-into-project.sh sigma-api cursor ~/work/myproject
./scripts/install-into-project.sh sigma-workbooks cursor ~/work/myproject

Replace cursor with the agent name. The installer copies both the generated agent rule and a runnable companion under /.sigma-skills//, including scripts and reference files. It also installs the sigma-api runtime beside API-dependent skills.

Credentials must be plain-text environment assignments, not an RTF/Word/TextEdit document. Start from .env.example, keep the result out of version control, and never paste tokens into prompts or logs.

cp .env.example .env
# Edit .env as plain text, then load it into the current shell:
set -a; source .env; set +a

Prerequisites

scripts/check-prerequisites.sh reports missing tools and platform-specific install hints without changing the machine.

Supported agents (generated/ outputs per skill, install via scripts/install-into-project.sh):

See Installation below for the install helper.

Skills

Looking for tableau-to-sigma or tableau-vds-to-snowflake? Those skills are still iterating and live in the private twells89/sigma-skills-staging repo. They graduate here once they’re stable across multiple real conversions.

Pick the right skill

Architecture

sigma-data-models     ──┐
                        ├── building blocks (load on demand)
sigma-workbooks       ──┘
sigma-reports         ─── fixed-layout report authoring and delivery

custom-sql-to-data-model    ─── orchestrator: SQL extraction + DM creation

sigma-data-models, sigma-workbooks, and sigma-reports are authoring building blocks. Workbooks are responsive and exploratory; reports use fixed physical pages. custom-sql-to-data-model is a higher-level pipeline that depends on the data-model and workbook skills.

Auth

Use the sigma-api skill to configure authentication and mint a token. Interactive browser OAuth is preferred when a human is present; OAuth client credentials are the unattended fallback. The common helper resolves a saved browser session first, then client credentials:

export SIGMA_BASE_URL="https://api.sigmacomputing.com"
eval "$(bash ~/sigma-skills/sigma-api/scripts/get-token.sh)"

It emits SIGMA_API_TOKEN, SIGMA_TOKEN_MINTED_AT, and SIGMA_AUTH_METHOD. Select auto (default), browser, or client-credentials with SIGMA_AUTH_MODE / --auth-mode. Before the canonical Python provider emits either kind of token, it verifies it with a non-redirecting GET /v2/whoami; failed, forbidden, malformed, or redirecting responses abort without printing or writing the bearer token.

Preferred — interactive browser login (one-time setup)

export SIGMA_BASE_URL="https://api.sigmacomputing.com"  # adjust per cloud; pragma: allowlist secret

# Opens the browser, captures the redirect, and stores the refresh token plus
# a short-lived access-token cache in the OS keychain, never the workspace.
eval "$(bash ~/sigma-skills/sigma-api/scripts/browser-login.sh)"

# Later, use the cached access token or refresh headlessly:
eval "$(bash ~/sigma-skills/sigma-api/scripts/get-token.sh)"

The refresh token never enters auth.json or the workspace. See sigma-api/reference/browser-oauth-login.md for the full flow.

Fallback — client credentials (headless / automation)

export SIGMA_CLIENT_ID="..."
export SIGMA_CLIENT_SECRET="..."
eval "$(bash ~/sigma-skills/sigma-api/scripts/get-token.sh)"

Sigma client credentials are issued from Administration → Developer Access in your Sigma org. Force this method with --auth-mode client-credentials.

Installation

Claude Code (plugin marketplace)

This repo is a Claude Code marketplace. Skill directories stay at the repo root (so Cursor / Codex / symlink installs do not change); skills/ is a set of relative links Claude Code uses when it copies the plugin.

/plugin marketplace add twells89/sigma-skills
/plugin install sigma-skills@sigma-skills

After install, invoke a skill as /sigma-skills: (for example /sigma-skills:sigma-workbooks). Run scripts from that skill directory — paths in each SKILL.md are relative.

Refresh later with /plugin marketplace update sigma-skills.

Advanced: Claude Code & Cortex Code manual clone/symlinks

Prefer the plugin path above for Claude Code. Use this only when you specifically need a clone on disk. Do not glob every top-level directory — scripts/ and skills/ are not skills. Windows users should use WSL or the copy-based install helper instead of manual symlinks.

git clone https://github.com/twells89/sigma-skills.git ~/sigma-skills
mkdir -p ~/.claude/skills
for name in sigma-api sigma-data-models sigma-workbooks sigma-reports sigma-plugin-authoring custom-sql-to-data-model; do
  ln -sf ~/sigma-skills/"$name" ~/.claude/skills/"$name"
done

Cortex Code reads ~/.claude/skills/ as a fallback, so the same setup works for both. Or symlink into ~/.snowflake/cortex/skills/ explicitly.

Codex / Cursor / Cline / Continue (use generated files)

Each skill ships pre-built outputs in generated/. Use the install helper to drop them into a project (or your user-global config):

# Project-local install
~/sigma-skills/scripts/install-into-project.sh sigma-api         codex  ~/work/myproject
~/sigma-skills/scripts/install-into-project.sh sigma-workbooks   cursor ~/work/myproject
~/sigma-skills/scripts/install-into-project.sh sigma-reports     all    ~/work/myproject
~/sigma-skills/scripts/install-into-project.sh sigma-workbooks   all    ~/work/myproject

# User-global install
~/sigma-skills/scripts/install-into-project.sh sigma-workbooks   codex  --global   # → ~/.codex/AGENTS.md
~/sigma-skills/scripts/install-into-project.sh sigma-workbooks   cursor --global   # → ~/.cursor/rules/

The Codex installer preserves unrelated AGENTS.md content and replaces its own marked section on refresh, so rerunning it does not duplicate a skill. Non-Claude installs also copy runnable skill files to /.sigma-skills/ (or ~/.sigma-skills/ with --global).

Regenerating outputs after a SKILL.md edit

ruby ~/sigma-skills/scripts/sync-targets.rb ~/sigma-skills/

The rewriter strips Claude-only marker blocks, reveals non-Claude marker blocks, and injects each target’s expected frontmatter. Markers in SKILL.md:

This text appears only in the canonical SKILL.md (Claude Code, Cortex Code).

Updating

These skills are maintained against current Sigma API behavior. When the API evolves and a skill returns a “schema mismatch” error (unknown field, unexpected property, invalid argument on shape), pull the latest:

/plugin marketplace update sigma-skills

Or, if you cloned the repo:

cd ~/sigma-skills && git pull

Each skill’s SKILL.md includes a Troubleshooting section that points at the live OpenAPI spec for spot-fixes when the skill is mid-update.

License

Licensed under the Apache License, Version 2.0.