ktx-analytics

What it does

The skill is a data-analytics workflow for answering questions that require data from a ktx-connected database. It instructs the agent to follow a multi-step process: discover data across wiki pages, semantic-layer sources, metrics, dimensions, raw tables, and columns; inspect top hits in parallel by type (wiki, semantic-layer sources, tables, columns); resolve business values via dictionary lookups; plan the analysis with a pre-written exact output column list; perform a query using the semantic layer when possible and raw SQL when necessary; validate results and explain the source tables or semantic-layer objects used; and capture durable learnings with memory ingestion. It mandates using read-only SQL and emphasizes tracing types, validating types before comparing, sampling data for encoding, and building queries incrementally with pre-aggregation and proper grain. It also provides a detailed example of canonical SQL parsing and caution against naïve casting, plus guidance on canonicalizing URL paths and join strategies to avoid data inflation. The workflow relies on tools like discover_data, wiki_read, sl_read_source, entity_details, sql_execution, and sql_dialect_notes, and enforces that memory_ingest be used when beneficial. The skill’s scope includes license information (Apache-2.0) and emphasizes using the semantic layer as the preferred source of truth for measures.

How it works

• Start with Discover: call discover_data to enumerate wiki pages, semantic-layer sources, metrics, dimensions, raw tables, and columns (returns refs only).
• Inspect top hits: for each promising ref, perform wiki_read for wiki refs, sl_read_source for semantic-layer sources, measures, or dimensions, and entity_details for tables or columns; sample rows via entity_details and a small sql_execution sample to verify encoding, nulls, and enum values.
• Resolve business values: if the user mentions specific values, run dictionary_search to locate the corresponding column holding that value.
• Plan the analysis: enumerate the exact output-column list first, as the contract for the final SELECT; determine grain, metrics, dimensions, filters, time window, and row limits before querying.
• Query: prefer sl_query when the semantic layer covers the question; use sql_execution for questions not covered by the semantic layer. Before raw SQL, run sql_dialect_notes to learn engine conventions. Write SQL with incremental, deterministic window ordering and full-precision calculations, matching grain to the question.
• Validate: perform a completeness check against the question, ensuring all requested outputs and derived values are included; state the source tables or semantic-layer objects used.
• Memory: call memory_ingest when a turn yields durable learnings.

When to use it

Triggers even if the user does not say "analytics"; apply whenever the answer requires querying a configured ktx connection.

What it can touch

• Tools: claude-code, codex.
• References to commands: discover_data, wiki_read, sl_read_source, entity_details, sql_execution, sql_dialect_notes, dictionary_search, sl_query, and memory_ingest.

Caveats

• The workflow emphasizes using the semantic layer as the preferred source of truth for measures and requires validating types and encodings through sampling before filtering or joining.
• All steps assume read-only queries; writes are rejected by the server.
• Results depend on correct grain and proper pre-aggregation as described in the rules; misalignment can lead to inflated counts or incorrect aggregations.