feat(dataapp-developer): add semantic-layer-usage skill (AI-3520)

[jordanrburger]

Summary

Adds a new semantic-layer-usage skill to the dataapp-developer plugin (AI-3520, part of AI-3518 / SUPPORT-16901).

Why: In SUPPORT-16901 Kai built a dashboard "from the semantic layer" and wrote SQL using the semantic-model field names directly — never calling get_table to check the physical schema of the out.c-nyc-aggregations-duckdb.rpt_* tables. The names didn't match the physical columns, every query failed, and the dashboard rendered empty even though the container was "running". The skill encodes the fix: the semantic layer is a logical model; its names are not guaranteed to equal physical Storage identifiers, so they must be resolved before any SQL is written.

What the skill teaches:

• Logical (semantic) entity/metric/field names ≠ physical bucket/table/column identifiers.
• A pre-SQL verification loop. Step 1 is conditional (only when a semantic model exists): read the definition via search_semantic_context → get_semantic_context. Steps 2–4 are the floor and always apply, including for a bare Storage table or a plain business-language request: resolve to physical Storage (get_buckets → get_tables → get_table for exact columns + fully_qualified_name), confirm columns, then probe with query_data SELECT … LIMIT 1 before committing app/transformation code.
• Use the fully-qualified physical identifier exactly as returned by get_table (ties into the existing FQN guidance in dataapp-development/references/storage-access.md).
• A worked example modelled on the failure.

Files

plugins/dataapp-developer/skills/semantic-layer-usage/SKILL.md   (new)
plugins/dataapp-developer/.claude-plugin/plugin.json             1.3.0 → 1.4.0
.claude-plugin/marketplace.json  (dataapp-developer entry)       1.3.0 → 1.4.0
plugins/dataapp-developer/README.md                              new skill + version + structure
README.md                                                        dataapp-developer feature line

claude plugin validate . passes.

Review updates

• 6d6f19f — per @davidesner, made the loop degrade gracefully: step 1 is now explicitly gated on a semantic model being present, steps 2–4 are the always-on floor, and validate_semantic_query is only suggested when the query started from a model.

Note on where this lives / next step for Kai

The ticket originally proposed a local baked skill in keboola/ui (packages/kai-agent-sandbox/skills/). Per direction from Jordan this instead lives in keboola/ai-kit, alongside the companion dataapp-development skill. Heads-up: kai-agent-sandbox's scripts/vendor-external-skills.ts currently vendors only the single dataapp-development subpath, so this standalone skill will not automatically ship into Kai's E2B sandbox yet. To reach Kai at runtime, either extend that vendor script to also pull semantic-layer-usage, or fold the guidance into dataapp-development (which is already vendored). Leaving that ui-side change out of scope here as requested — flagging so it can be a follow-up.

Open question from the ticket

The ticket asked whether get_semantic_context already returns the physical mapping. The plugin's own dataapp-development/references/dev-workflow.md documents get_semantic_context as returning the metric's SQL, dataset identifier, and join paths — i.e. logical definitions, not guaranteed physical column names — so the skill's "always resolve to physical via get_table" guidance holds regardless.

Release Notes

Justification, description

Documentation/skill-only change: adds guidance so agents (and Kai) resolve logical semantic-layer names to physical Storage identifiers before writing SQL, preventing empty/broken semantic-layer-backed apps (SUPPORT-16901).

Plans for Customer Communication

N/A

Impact Analysis

N/A — no runtime code; adds a Markdown skill and bumps plugin/marketplace versions.

Deployment Plan

N/A

Rollback Plan

N/A

Post-Release Support Plan

N/A

Link to Devin session: https://app.devin.ai/sessions/8bdc15f5a0fa4109a4c814dd9a30bc94
Requested by: @jordanrburger

[linear-code]

AI-3520

AI-3518

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[davidesner]

It seems fine in general. Just one side note that should not be handled in this PR -> I am still struggling with the AI kit structure. The semantic layer usage skill is kind of a general Keboola skill. We should have imo one plugin Keboola expert with all relevant skills eventually (that would contain also everything the MCP llm context serves).

[davidesner]

@jordanrburger I only wonder whether we should mention explicitly a fallback verification process without the semantic layer -> basically just loosen the "## Mandatory verification loop — before writing ANY SQL/query" steps saying `If semantic layer is available do this (step 1), otherwise at least verify against storage (steps 2-4). Did you try how this works if the sem layer is not present?

[devin-ai-integration]

Good call — done in 6d6f19f. Reworded the loop so step 1 (read the semantic definition) is explicitly conditional on a semantic model being present, and steps 2–4 (resolve to physical → confirm columns → probe query_data) are called out as the floor that always applies, including for a bare Storage table or a plain business-language request. If search_semantic_context returns nothing relevant, the skill now says to declare that and go straight to steps 2–4 against raw tables, and validate_semantic_query is only suggested when you actually started from a model.

On "did you try it without the semantic layer present" — I haven't runtime-tested skill activation in Kai (didn't spin up an E2B sandbox for a docs-only skill). Behaviorally the no-semantic-layer path now mirrors what dataapp-development/references/dev-workflow.md already prescribes (grounding in get_table + query_data), so it degrades to the existing storage-verification guidance rather than dead-ending. Happy to validate live in a sandbox if you'd like before merge.

[devin-ai-integration]

@davidesner on the structure point — agreed, and noted as out of scope for this PR. It lines up with Jordan's note about eventually unifying with sl-toolkit/sl-builder: this skill is the consume side (resolve logical → physical before querying) while sl-toolkit is the author side (inspect/validate/build/CRUD), and a single "Keboola expert" plugin that also carries the MCP LLM-context material would be the endpoint. I can file a follow-up Linear issue to track that consolidation (plus the kai-agent-sandbox vendoring gap noted in the description) so it doesn't get lost — will do unless you'd rather own it.