lynk-semantic-layer

Answer questions about the Lynk semantic layer — what's in `.lynk/` (instance lookups) and Lynk concepts themselves (primitives, file types, placement). Read-only: never edits, never calls the backend. Use this skill for any question about Lynk or `.lynk/`, even simple ones. Lynk distinguishes primitives that general analytics vocabulary blurs — e.g. a *metric* under `metrics:` is not a *feature of type metric* under `features:`. Don't answer from prior knowledge; run this skill so the answer is doc-grounded. Instance triggers: "does the player have a metric for total games played?", "what metrics does X have?", "list features of X", "where is Y defined?", "what's the SQL for X?", "how many entities do I have?". Concept triggers: "what is a knowledge file?", "metric vs. metric feature?", "formula vs. metric feature?", "where should glossary terms go?", "what is a clarification policy?". For edits use `lynk-build`; for quality `lynk-evaluate`; for backend checks `lynk-validate`; for sources `lynk-sources`.

Build and edit the Lynk semantic layer — add or modify entities, metrics, features, relationships, knowledge files, glossary, task instructions, clarification policy, output format, and domains in `.lynk/`. Use this skill whenever the user asks to add, create, edit, update, define, review, improve, enhance, or optimize any semantic layer artifact. Trigger even when "semantic layer" isn't mentioned — phrases like "add an entity", "edit a metric", "update the glossary", "write task instructions", "change the clarification policy", "add a feature to X", "model this table", "help me define Y in Lynk", "improve the knowledge file", "enhance the player entity", "optimize the glossary", or any request to improve/fix a file inside `.lynk/` all mean this skill should run.

Evaluate the Lynk semantic layer in `.lynk/` — judge whether it is good enough for the AI agent to use, not just whether the YAML parses. Checks description quality, cross-file consistency, content placement, reference integrity, and SQL dialect compatibility against the user's warehouse engine. Use this skill whenever the user asks to evaluate, audit, review, assess, or diagnose the semantic layer or any part of it. Trigger on phrases like "evaluate the semantics", "is this good enough for the agent", "audit my entities", "check description quality", "any contradictions in my context", "will my SQL run on Snowflake", "will this work on BigQuery", "review the glossary", "check my evaluations against instructions", "evaluate player", "is the semantic layer well structured", or any request to assess the quality of files inside `.lynk/`.

Inspect the Lynk data catalog via the API, reconcile entity YAMLs when source columns change, and execute ad-hoc Lynk SQL against the semantic layer: list registered schemas, list sources (tables), fetch a source's columns, sync the catalog against the warehouse, clean up entity field features whose source columns were dropped, and run Lynk SQL queries. Use this skill whenever the user asks to: list schemas, see what tables/ schemas exist, model a new table (fetch its columns first), sync sources, refresh source columns after a warehouse schema change, clean up entity fields after a source update, or run / test a Lynk SQL query. Trigger phrases: "list schemas", "what schemas do I have", "add the orders table", "sync sources", "I added fields to orders", "the source columns changed", "what fields does the orders table have", "clean up after the inquiries table dropped column referrer_id", "run this query", "test this SQL", "does this lynk SQL execute". This skill is read-and-API-only on the catalog side. It hands off to `lynk-build` for any `.yml` edits it surfaces (e.g., removing field features whose source column was dropped).

Run the Lynk backend's **semantics build** (`POST /api/semantics/builds`) to confirm the semantic layer in `.lynk/` on a committed branch is valid and ready for the AI agent to use. Returns a build object with `status: valid|invalid` and any issues — schema errors, broken source-field references, warehouse-query rejections, or other server-side validity problems. Use this skill whenever the user asks to validate the layer, run a backend check, or confirm a build succeeded. The endpoint is named `builds`, so users may also call it "the semantics build", "the build", or "the latest build" — trigger on those just as readily as on "validate". Trigger phrases: "validate the semantic layer", "run lynk validate", "is my .lynk valid", "check against the backend", "validate on branch X", "validate on dev", "are there any schema errors", "validate inquiries branch", "did the build pass", "is the latest build green", "run the semantics build", "build my semantics", "rebuild on branch X", "force a rebuild", "is the semantic layer ready to use". For local content quality (description quality, cross-file contradictions, dialect compatibility), use `lynk-evaluate` instead — this skill only runs the backend build.