ThoughtSpot Agent Skills

AI agent skills for working with ThoughtSpot — platform conversion, semantic model authoring, multi-tenancy governance, and data querying. Packaged for Claude Code, Cortex Code CLI, Snowsight, and Databricks.

---

Skills

32 skills across six categories. Each ✓ in the runtime columns links to the SKILL.md for that runtime. For why an individual skill exists, who tends to need it, and when to reach for it, see skill personas.

---

Getting Started

1. Pick your runtime

Each setup guide covers prerequisites, installation, credential configuration, and verification steps for that runtime.

2. CLI quick start

Most users start here. Snowsight and Databricks users — follow the setup guide for your runtime instead.

# Clone
git clone https://github.com/thoughtspot/thoughtspot-agent-skills.git ~/thoughtspot-agent-skills

# Install the ts CLI (requires Python 3.9–3.13)
pip install -e ~/thoughtspot-agent-skills/tools/ts-cli

# Symlink skills — see agents/cli/SETUP.md for the full list

Cortex Code CLI:

mkdir -p ~/.snowflake/cortex/skills
ln -s ~/thoughtspot-agent-skills/agents/cli/ts-profile-thoughtspot ~/.snowflake/cortex/skills/ts-profile-thoughtspot
ln -s ~/thoughtspot-agent-skills/agents/shared ~/.snowflake/cortex/shared

Claude Code:

mkdir -p ~/.claude/skills
ln -s ~/thoughtspot-agent-skills/agents/cli/ts-profile-thoughtspot ~/.claude/skills/ts-profile-thoughtspot
ln -s ~/thoughtspot-agent-skills/agents/shared ~/.claude/shared
ln -s ~/thoughtspot-agent-skills/agents/shared/mappings ~/.claude/mappings

Then symlink each skill you want from the skills catalog above. The full symlink list is in agents/cli/SETUP.md.

3. ThoughtSpot CLI (ts)

A lightweight Python CLI used by CLI skills at runtime to authenticate with ThoughtSpot, search metadata, export/import TML, list connections, and create logical table objects. Located in tools/ts-cli/.

ts --help

Commands: ts auth, ts metadata search, ts tml export/import, ts connections list/get/add-tables, ts tables create, ts profiles list.

---

Repository Structure

thoughtspot-agent-skills/
├── agents/
│   ├── cli/        — Canonical CLI skills (Claude Code + Cortex Code CLI)
│   ├── claude/     — Claude Code-only skills (ts-profile-snowflake)
│   ├── coco-snowsight/ — Snowsight Workspace skills (stored procedures)
│   ├── databricks/ — Databricks runtime (Genie Code, Asset Bundles)
│   └── shared/     — Shared reference files used by all runtimes
│       ├── mappings/ts-snowflake/       — Column, join, formula, and property mapping rules
│       ├── mappings/ts-databricks/      — ThoughtSpot ↔ Databricks Metric View mapping rules
│       ├── mappings/tableau/            — Tableau → ThoughtSpot formula and TML rules
│       ├── mappings/looker/             — LookML → ThoughtSpot formula and TML rules
│       ├── schemas/                     — Platform schema references (ThoughtSpot TML, Snowflake SV)
│       └── worked-examples/snowflake/   — End-to-end conversion examples
├── scripts/        — Deployment helpers (pre-commit hook, deploy gate, stage sync)
└── tools/
    ├── ts-cli/     — ThoughtSpot CLI used by CLI skills at runtime
    ├── validate/   — Static validators (runtime coverage, consistency)
    ├── fixtures/   — Captured cluster topologies for `ts tenancy` (reference multi-tenancy environment)
    ├── smoke-tests/ — End-to-end smoke tests requiring live credentials
    ├── ossie-roundtrip/ — Round-trips real Models through the Apache Ossie converter (lives upstream)
    ├── formula-fidelity/ — Checks translated formulas return the source's values (oracle vs ThoughtSpot, live)
    ├── agentql-retest/ — Re-probes every documented AgentQL limitation and reports the rows whose behaviour moved (live)
    ├── pr-metrics/ — Baseline PR metrics (count, days open, size, review rounds), maintainer and external PRs reported separately
    └── quest/      — AgentQL Quest, the Learn AgentQL course as a browser game, built from the captured lesson SQL and published to GitHub Pages

---

Contributing

Start with the contributing guide: the routine for every pull request, the one-time setup, and how to run pr-ready in a terminal or in Claude Code.

Before your first commit, install the git hooks. The pre-commit hook runs the same gates CI does, so a stale registry, a failing validator or a leaked customer link surfaces in seconds locally instead of minutes later in CI; the commit-msg hook checks the commit message for customer references. A clone cannot install hooks — git has no way to do that — so it is one command, and a Claude Code session warns at start-up until it has been run:

bash scripts/install-hooks.sh          # installs the pre-commit and commit-msg dispatchers
bash scripts/install-hooks.sh --check  # exit 1 if either is missing or out of date

The dispatchers live in the clone’s shared hooks directory and run the committing worktree’s own scripts/pre-commit.sh and scripts/commit-msg.sh. An older branch runs its own older pre-commit.sh, which lacks gates added since, and has no commit-msg.sh (that hook then does nothing) until it merges main; CI’s whole-tree and per-commit scans are the backstop. (The older ln -s … .git/hooks/pre-commit symlink always ran the main checkout’s copy; the installer backs it up and replaces it.) It does not set core.hooksPath and refuses to run if you have set one, and it does not install the pre-push hook.

---

Troubleshooting

ts CLI install fails on Python 3.14 (macOS)

Symptom: pip install or pipx install fails with:

ImportError: Symbol not found: _XML_SetAllocTrackerActivationThreshold

Cause: Python 3.14 from Homebrew is compiled against a newer libexpat than the one shipped with macOS, causing a dynamic library mismatch. The ts CLI requires Python 3.9–3.13.

Fix: Install and use Python 3.12 or 3.13:

brew install [email protected]
pip3.12 install -e ~/thoughtspot-agent-skills/tools/ts-cli

If you installed via pipx, point it at a supported Python:

pipx install --python python3.12 -e ~/thoughtspot-agent-skills/tools/ts-cli

Note: also use pip install -e (not pipx install -e) — pipx is designed for standalone PyPI packages, not editable local installs.