From lynk-semantic-layer
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.
How this skill is triggered — by the user, by Claude, or both
Slash command
/lynk-semantic-layer:lynk-buildThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
**Never run a "lean" version of this skill.** Every step below is mandatory regardless of how mechanical, repetitive, or large the edit appears. Bulk pass-through edits (e.g. "add 30 fields from this source") feel mechanical but are exactly the situations where skipped doc reads or substituted sub-skill flows produce silently wrong artifacts — the user has no way to tell until something breaks....
Never run a "lean" version of this skill. Every step below is mandatory regardless of how mechanical, repetitive, or large the edit appears. Bulk pass-through edits (e.g. "add 30 fields from this source") feel mechanical but are exactly the situations where skipped doc reads or substituted sub-skill flows produce silently wrong artifacts — the user has no way to tell until something breaks. If you believe a step can be safely skipped in a given case, tell the user before the work which step, why, and what's lost by skipping; wait for explicit opt-in. Never confess the shortcut after the fact.
Mandatory — do not skip even for bulk pass-through edits. The vocabulary and primitive list below is what every later step assumes you know.
https://docs.getlynk.ai/concepts.md to understand the Core Vocabulary and Semantic Layer structure — what Lynk primitives exist: Entity, Feature, Metric, Relationship, Glossary, Domain, Context (knowledge / task-instructions / clarification policy / output format).For how to navigate the docs (the two anchor pages and walking from the index to leaf pages), see references/lynk-docs.md.
From the user's request, determine:
default unless stated otherwise.lynk/The current semantic layer:
! find ./.lynk -type f | sort
Identify which file(s) own the artifact the user mentioned by scanning the actual filenames and folder structure.
Mandatory — do not skip the docs index fetch or the entity-file reads below, even for bulk pass-through edits. A 30-field "just add these columns" request is exactly where re-reading the entity's knowledge file and task-instructions catches naming conventions, field-visibility rules, and existing groupings that the agent would otherwise miss.
Always fetch the docs index with https://docs.getlynk.ai/llms.txt to see what pages are available. This is the index of all Lynk docs that you can fetch. It also gives you a sense of how the docs are structured, so you can make informed decisions about which files to read for the most relevant context.
Consult the live Lynk docs via WebFetch — only fetch what you need.
Read the narrowest set of files that gives you enough context to act:
Users can ask to build or edit an entity, or ask about an entity's features, metrics, relationships, knowledge, task instructions, clarification policy, or output format. In all cases, the core files to read are:
In case the user request is referring multiple entities, read all of them, but avoid reading unrelated entities.
Read .lynk/config.json for an engine, dialect, or warehouse field (common values: bigquery, snowflake, postgres, redshift, databricks). If the field is missing, empty, or the file doesn't exist, ask the user via AskUserQuestion — do not guess. The dialect drives Rule 7 of references/content-rules.md: every SQL snippet you write must be valid in that engine.
When the user wants to add or extend an entity, model against the source's actual columns, description, and keys — never guesses. The catalog already holds all of this, so the default is to go get it, not to ask the user how. Open an AskUserQuestion about how to obtain columns only when the catalog genuinely can't answer (table still not found after a sync) or the user has said they'd rather paste — not as the opening move.
Delegate to lynk-sources to pull the source's description, keys, column count, and column list. Do this before planning — it's the grounding pass.
description (if any) and the column types/descriptions, so the model reflects what the data means, not just column names.sync (a table added since the last sync won't appear until then). Fall back to asking the user to paste columns only if it still can't be found.If the user says "I added fields to X" or "columns of X changed", delegate to lynk-sources to sync, refetch fields, and reconcile any field features whose source columns no longer exist.
Announce the source-fetch step for multi-field adds (≥5 fields). Before delegating to lynk-sources, tell the user explicitly: "Fetching current source columns via lynk-sources first — grounding against the live catalog so we don't model fields that no longer exist or miss ones that were just added." The user should see the workflow happen, not have to ask afterwards whether the skill grounded itself.
A keys is mandatory and must uniquely identify a row — see Rule 11 in references/content-rules.md for why a non-unique column is worse than none. Source it from real data, never fabricate it:
keys → use them as-is.keys is empty → derive a candidate (a single id-like column, or a composite for the grain) and verify it via lynk-sources: SELECT COUNT(*) AS rows, COUNT(DISTINCT <candidate>) AS distinct_rows FROM <table> (composite → count the distinct concatenation). Unique iff rows == distinct_rows and non-null. Narrate each attempt so the user sees the reasoning, not just a verdict.AskUserQuestion with the real options (a composite the user knows is unique, an upstream surrogate, or reconsidering the grain).Share a concise plan: which files you'll create or edit and the key decisions. Wait for the user to confirm before making any changes.
Before drafting the plan, apply every applicable rule in references/content-rules.md (the rule index is at the top) to the proposed change, and call out in the plan which rules bear on it and what each requires — build enforces the same rulebook evaluate audits. A few need action inside the plan, not just a mental check:
examples: entry / evaluations.yml case / SQL example, or setting an entity's keys:, that rule's procedure is binding (key verification runs in Step 5). State in the plan that you applied it.related_source, confirm the table is not (and won't become) its own entity and that you won't aggregate it; if either holds, model it as an entity + relationship instead. When you create a new entity, reconcile in the same edit: grep .lynk/ for that table used as a related_source elsewhere (! grep -rn "<table>" .lynk/) and convert any hit to a relationship + entity-sourced feature. Phased modeling is exactly where a table becomes an entity after another entity already bolted it on as a related_source — that drift is the failure Rule 12 catches.Write or edit one file at a time. Show the user what was written before moving to the next.
After each file is saved, run the per-file quick check (questions 1, 2, 4, 6, 7, 8, 10 from the bottom of references/content-rules.md — right place / clear / internally consistent / engine-compatible SQL / Lynk SQL syntax / domain on-topic / keys real). After all files in the edit are saved, run the cross-file pass (questions 3, 5, 9, 11 — appears once / references resolve / examples & evaluations valid / related-sources legit), since those checks need every edited file to be on disk first.
Fix or escalate to the user before considering the edit done. Don't silently advance past a failure: if a check fails because of a question only the user can answer (naming, contradicting definitions), surface it before continuing.
After-action summary (mandatory before Step 8). Once all files are saved and the cross-file pass is clean, produce a single structured recap so the user can see what happened without reconstructing it from per-file messages. Three sections, in this order, even if a section is empty (in which case say "none"):
inventory.yml: Product condition (5), Packaging condition (5), Bin/location flags (18)"). Cite file paths.This recap is the user's record of the work and the bridge into Step 8. Never skip it for "small" or "obvious" edits.
Announce the handoff explicitly before starting. Open this step with a sentence like "Now chaining into lynk-evaluate to surface content-quality issues beyond schema validity — description quality, cross-file consistency, placement, and Lynk SQL syntax." The user should see the phase change, not have to ask afterwards whether evaluate ran.
Once all edits are saved, run the lynk-evaluate flow targeted at the artifact you just edited (the entity, glossary, or domain file from Step 7) — not the full graph. Evaluate already chains the backend lynk-validate call and owns the fix-offer + re-evaluation loop (capped at 3 attempts). Just present whatever evaluate returns; do not run a parallel fix loop here.
Never substitute a raw API call for the full lynk-evaluate flow. Calling POST /semantics/builds directly (or via lynk-validate alone) only runs the backend schema + warehouse-probe check — it skips the content-rules layer (description quality, cross-file consistency, placement, Lynk SQL syntax, domain coherence) that lynk-evaluate adds on top. A "the edit was mechanical enough" reason is not sufficient grounds to substitute; the content-rules layer catches naming and placement issues that have nothing to do with how mechanical the change felt.
Skip this step only if the user explicitly opted out ("just add the field, don't evaluate it"). Inferring discretion from the size or apparent simplicity of the edit is not opting out.
Always respond clearly with the recommendations as bullet points, and use code blocks to show any file content. Give references from the docs to justify your decisions. If you make assumptions, state them explicitly.
references/content-rules.md on every edit. Surface out-of-scope misplacements or duplications you notice (Rule 3) — don't silently accept them.Searches MemPalace before answering questions about past work, people, projects, or prior decisions. Returns verbatim stored content instead of guessing from model memory.
Guides Payload CMS config (payload.config.ts), collections, fields, hooks, access control, APIs. Debugs validation errors, security, relationships, queries, transactions, hook behavior.
Implements vector databases with Pinecone, Weaviate, Qdrant, Milvus, pgvector for semantic search, RAG, recommendations, and similarity systems. Optimizes embeddings, indexing, and hybrid search.
npx claudepluginhub lynk-ai/build-agent --plugin lynk-semantic-layer