{"id":48444,"plugin_id":"plugin_asdk_app_6ad0a4765acc8191a6745747f9159eec","kind":"skill","collection_source":"plugin_package","comparison_source":null,"observed_at":"2026-10-24T13:36:28.736Z","digest":"e17558d42666364d7efae25b4f98c872b7fe0fc7e0c596a7b78d9d59eb9b4453","against":null,"payload":{"description":"Manage Supersimple dashboards and YAML model, metric, and exploration files with the supersimple command. Use for database discovery, dbt conversion, bulk configuration, and AI instructions. For data questions use Supersimple MCP; for Supersimple Apps development use supersimple-apps.","included_files":[{"relative_path":"references/cli-reference.md","size_in_bytes":9705},{"relative_path":"references/data-model-yaml.md","size_in_bytes":11544},{"relative_path":"references/explorations-yaml.md","size_in_bytes":29069}],"name":"supersimple","skill_md_contents":"---\nname: supersimple\ndescription: Manage Supersimple dashboards and YAML model, metric, and exploration files with the supersimple command. Use for database discovery, dbt conversion, bulk configuration, and AI instructions. For data questions use Supersimple MCP; for Supersimple Apps development use supersimple-apps.\nmetadata:\n  minimum-cli-version: \"2.27.0\"\n---\n\n# Supersimple configuration\n\nSupersimple runs analytics against a connected warehouse. The CLI manages models, metrics,\nexplorations, and workspace AI instructions as YAML; importing changes the connected account.\n\n## Choose MCP or the CLI\n\nThe [Supersimple MCP server](https://docs.supersimple.io/integrations/mcp-server) lets agents\nask analytics questions and inspect live explorations. Use an existing connection, or connect your agent to\n`https://app.supersimple.io/mcp` using streamable HTTP and sign in through OAuth; the linked\nguide has client setup and API-token instructions. Tools run with the connected user's access.\n\n- Answer data questions with MCP `ask_supersimple`.\n- Read shared explorations with `get_exploration*`; inspect results with `get_exploration_block_data`.\n- Use the CLI for version-controlled or bulk models, metrics, dashboards, and AI configuration.\n- Manage answer guidance through MCP.\n- MCP `draft_app` creates a version of an existing app without publishing it; the target block\n  must separately pin the returned `appVersionId`. See `supersimple-apps` for the edit workflow.\n\nTool availability depends on connection scopes and role permissions. If MCP is unavailable,\nuse the setup guide when live inspection would help; CLI configuration work can continue.\n\n### Debug an existing exploration\n\nUse `get_exploration` to find the block, then `get_exploration_block` to inspect its\n`dereferencedPipeline` (including steps inherited from parent blocks). Run\n`get_exploration_block_data` with the same variable values in `params` to check actual results\nor query errors. Omitted variables use their defaults. Keep the account, user permissions,\nfilters, and date range consistent when comparing results; use `limit`/`offset` for bounded samples.\nAfter changing and importing a model or exploration, rerun the affected block and compare a\nspecific expected value. For regressions, `get_exploration_history` and `get_exploration_version`\ncan help identify the changed definition.\n\n## Start with the existing setup\n\nCLI steps require terminal access and separate CLI authentication; otherwise use available MCP tools or prepare files for the user to apply.\n\n1. Require CLI **2.27.0 or later**: check `supersimple --version`, `supersimple status`, and the project's existing configuration.\n   If the CLI is missing, installation instructions are at\n   https://docs.supersimple.io/guides/managing-the-data-model/using-the-cli.\n   On macOS: `brew tap gosupersimple/cli && brew trust --tap gosupersimple/cli && brew install supersimple`.\n   Direct macOS and Linux binaries are also linked from the CLI docs.\n2. For unattended commands, use an existing `SUPERSIMPLE_TOKEN` environment variable. The account\n   is derived from the token.\n   `SUPERSIMPLE_HOST` optionally selects a different API host.\n3. If credentials are missing, have the user run `supersimple login` in their terminal with a token\n   from https://app.supersimple.io/settings/developers. Interactive login saves credentials under\n   `~/.config/supersimple/config.json`; using an environment token does not save it.\n   Do not print or commit tokens.\n\n`status` reports the connected account without prompting. Read its output: the command always exits 0, including failed checks. Help, `fix`, and dbt conversion work without authentication.\n\nIf product behavior differs from this skill, compare `supersimple --version` with the latest\nreleased CLI and check for skill updates using the\n[skill installation guide](https://docs.supersimple.io/guides/ai-coding-agents#installation).\nThe minimum CLI version above is not a freshness check. Update the complete skill folder,\nincluding its references, preserving local edits, then retry the affected step. If the mismatch\nremains, report the observed behavior rather than assuming the skill is correct.\n\n## Choose the source of truth\n\nFollow the project's established workflow. Models and metrics are commonly version-controlled;\nedit their source files, validate, then import. For dbt-managed models, edit dbt annotations and\nregenerate the YAML. For explorations or AI configuration maintained in the app, export the current\nentity before editing so unrelated content and settings survive. Do not overwrite uncommitted\nconfiguration with an export; use a fresh temporary directory for inspection.\n\nRead the relevant reference before authoring YAML:\n\n- [CLI commands](references/cli-reference.md): flags, discovery, dbt, import/export, and deletion scope.\n- [Models and AI configuration](references/data-model-yaml.md): properties, joins, metrics, access,\n  workspace agent skills, and AI instructions.\n- [Explorations](references/explorations-yaml.md): cells, pipelines, filters, charts, variables, and layout.\n\nCLI configuration uses **snake_case keys**, with operation names such as `groupAggregate` unchanged.\nThe Supersimple SDK and GraphQL use camelCase (for example, YAML `metric_id` becomes SDK\n`metricId`). Preserve arbitrary user-defined property keys and app state.\n\n## Discover and edit models\n\n```bash\nsupersimple discover schemas\nsupersimple discover models --schema public -o ./discovered\n# Writes ./discovered/models/*.yaml. Review before copying into the project's model directory.\nsupersimple validate ./models --validate-sql\nsupersimple import ./models --validate-sql\n```\n\nUse `--connection <name>` for a named database connection. Discovery can prompt before replacing\nfiles, so use a fresh destination. Check cardinality and keys before adding a relation.\nDo not run `fix` on discovered/exported single-entity files: CLI 2.27.0 crashes on `model:` input.\nNamed access rules require `access_rules.yaml` in the same import, including subset validation.\nFor example: `supersimple validate ./models ./access_rules.yaml --validate-sql`.\n\nFor dbt:\n\n```bash\ndbt docs generate\nsupersimple dbt convert\nsupersimple validate supersimple-models.yml --validate-sql\nsupersimple import supersimple-models.yml --validate-sql\n```\n\nMaterialize the selected dbt models before generating matching artifacts. Opt models in with\n`config.meta.supersimple.enabled: true`. Treat the converter's output as generated; change the dbt\nannotations and regenerate. See the CLI reference for options and limitations.\n\n## Find and update explorations\n\n```bash\nsupersimple explorations list\nsupersimple export --exploration-ids <id> --stdout\n# Or export into a fresh directory for editing:\nsupersimple export --exploration-ids <id> -o ./sup-export\nsupersimple validate ./sup-export\nsupersimple import ./sup-export\n```\n\nFor cross-entity searches, export the relevant types into a fresh directory and search the files.\nModel/metric filenames use IDs; exploration and agent-skill filenames derive from names. Read the\nID inside a file before targeting it. `--force` overwrites existing export files; use it only when\nthat overwrite is intended. Export does not remove obsolete local files.\n\nExploration links: `https://app.supersimple.io/explore/<exploration-id>`.\n\nSet `folder: Sales` alongside `name` to choose an exploration’s folder. Omitted or null `folder`\nimports into the root. `visibility: personal` imports into the current user's personal space; omitted visibility defaults to `team`. Preserve both fields when\nediting an existing exploration. Model sidebar sections still use `labels.section`.\n\n## Keep data and instructions accurate\n\nFor categorical columns with a manageable set of values, consider `type: Enum` with\n`enum_options: { load: distinct_values }`, or a static list with friendly labels. Dynamic enums are\ncached (six hours by default) and capped at 1,000 values; they are not an exhaustive inventory for\nhigh-cardinality columns. Avoid blindly converting every string column to an enum.\n\nAI access to query results is controlled by account settings.\n\nWorkspace `agent_skills` and `ai_instructions` configure Supersimple's own AI. They are different\nfrom this coding-agent skill. Their export/import requires **Manage AI System Message** permission; export silently omits these\nsections without it. Import and validate also require **Manage Models**, even for exploration-only YAML.\n\n## Validate and sync deliberately\n\nAlways set the `*_id` in a single-entity file. In map form, the map key is the ID; do not repeat it\ninside the entry. Missing single-entity IDs trigger an interactive prompt and a source-file rewrite\nin both validate and import, which can hang unattended commands.\n\n`supersimple validate <paths...>` validates the proposed configuration against the existing account.\nUse `--validate-sql` when table mappings, columns, joins, or SQL need warehouse validation. Review the\nYAML diff before importing. After user-facing changes, open the affected exploration and check a\nspecific result, folder, filter, or chart that demonstrates the intended behavior. Use MCP\n`get_exploration_block_data` to check a specific changed value after import.\n\nNormal import updates the supplied entities. `--delete-dangling` can delete models and metrics\nacross the account even when importing only an exploration. Use it only for an explicitly intended\ncleanup from a complete source of truth; a restricted user’s export omits inaccessible models,\nmetrics, and hidden properties and is unsafe for this round trip. See the CLI reference for scope.\nEntity delete commands have no confirmation prompt: obtain explicit authorization before deleting.\n\nUse the installed command's `--help` and actual API validation when documentation disagrees with\nbehavior. Report drift instead of retrying with validation disabled.\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}