build-context

name

build-context

description

Create and bulk-fill Nekt Context documents for an agency's clients (or a single company's business domains) so that agents querying that data give accurate, well-scoped answers instead of generic ones. Use this whenever the user wants to generate, create, organize, or set up context documents for their clients or domains, mentions clients without context, or asks to document their clients in Nekt — e.g. "gere os documentos de contexto para meus clientes", "criar contexto para todos os clientes", "organize meus clientes no Nekt", "quais clientes estão sem contexto", "set up context docs for all clients". Works through the Nekt MCP (list_tables, get_semantic_context, create_context_document, generate_sql).

Context Organizer

Agencies keep many clients' data in one Nekt workspace — often paid media (Google / Meta / TikTok) consolidated with CRM; companies keep revops/ops/product data in one place. An agent reading that data over MCP can't tell which data belongs to whom or what each entity is about — so answers come out generic. Nekt's Context documents fix this, but writing them by hand is slow. This skill creates one document per client (or domain) and auto-fills everything derivable from the data, leaving only judgment calls for a human.

Respond in the user's language (pt-BR or English). Examples below are pt-BR because Nekt's user base is Brazilian — mirror whatever the user writes.

Prerequisite

The Nekt MCP must be connected (it provides list_layers, list_tables, get_table_preview, get_relevant_tables_ddl, get_semantic_context, generate_sql, execute_sql, create_context_document). If those tools aren't available, tell the user to connect the Nekt MCP and stop.

Splitting a shared multi-company table (step 1) additionally uses create_query / create_notebook, with list_layers and get_pipeline_status. These are optional — if they're not exposed, fall back to ask_about_nekt guidance and the Nekt web app.

Note: this server has no list_sources / get_source_details — sources are managed in the Nekt web app and can't be enumerated over MCP. Discovery therefore works from tables (list_tables), which carry the layer and output folder of the source that produced them.

Reference files (read when you reach the relevant step)

• ../manage-context-template/references/response-style.md — how to talk to the user (brevity, summaries-not-dumps, one checkpoint, lean reports). Read first.
• references/client-discovery.md — how to group sources into clients/domains. Read before step 1.
• ../manage-context-template/references/client-context-template.md — the default field set + a worked example. Read at step 2.
• ../manage-context-template/references/context-doc-authoring.md — naming convention, annotation grammar, layer-name rules. Read before step 3.

The template and authoring rules are owned by the manage-context-template skill (single source of truth) — read them there; this skill consumes them.

Workflow

Read ../manage-context-template/references/response-style.md first — it governs how you talk to the user at every step (right-size to the question, summaries not dumps, one checkpoint, lean reports). A status question like "quais clientes estão sem contexto?" gets a one-line answer — don't run the whole flow for it.

1. Discover entities and detect existing docs — one checkpoint

Read references/client-discovery.md first. Ignore the Sample data layer throughout — Nekt auto-creates it in new workspaces as mock data for testing, so it's never the agency's real data; drop any table whose layer is Sample data (case-insensitive) before grouping.

1. Call list_tables and paginate (follow page_token until exhausted). Capture each table's slug/name, layer (display name), database_name, output folder, description, and any tags (when present).
2. The MCP can't list sources, so derive entities from tables: table names encode both client and connector, and the order varies. Nekt's recommended agency convention is client-first (clienteX_google_ads_*, acme_meta_ads_*), so the leading segment is usually the client — don't assume it's the connector. Group by that client segment and/or by shared output folder, and detect the connector by matching its token anywhere in the name (google_ads, meta_ads, hubspot…). Never group by the opaque table slug alone. A table may also carry tags; a tag that names the client/domain is the preferred grouping signal — stronger than the slug — so group by it when present and fall back to segment/folder otherwise.
3. Watch for one table, many companies. A table that doesn't resolve to a single client and has a company/tenant discriminator column (company, empresa, cliente, account, tenant…) is likely a shared table spanning clients. Confirm with get_table_preview or a GROUP BY <col> count; at the checkpoint, recommend splitting it per company with a Nekt notebook (create_query / create_notebook) instead of forcing it under one client. Detail + create flow: references/client-discovery.md → One table, many companies.
4. For each entity, probe get_semantic_context("<Nome> contexto perfil visão geral") and treat a doc as existing only when a returned documents[].name normalizes-equal to the expected name (Cliente — <Nome> / Client — <Name> / Domínio — <Nome>). Vector search returns near-matches, so the name match is what counts — a different doc coming back does not mean this entity has one.

Then present one combined message: the grouping as Entidade → [tabelas / pasta] with a (sem doc) / (já tem doc) tag per row, and ask the user to confirm, merge, split, or rename — "Vou criar para os N sem doc. O agrupamento está certo?" Surface any multi-company table here too, with its split recommendation — don't fold it into a single client. If the workspace looks like a single company (folders/tables describe tools/domains, not clients), offer to organize by domain instead. Create nothing until this is confirmed; entities that already have a doc are skipped.

2. Settle the structure — inline, not a separate gate

Read ../manage-context-template/references/client-context-template.md. Every doc shares one structure (keeps clients comparable) — but always as one document per client, never a single shared doc, even when the structure is identical for everyone. In one line, say you'll use the standard template — naming the sections inline (Imersão no Negócio — modelo de negócio · produtos & ofertas · forças & fraquezas · avatar · indicadores & KPIs · Análise de Mercado — concorrência · tendências · oportunidades & ameaças · Diagnóstico de Marketing — redes sociais · mídia paga · reputação digital · website) — and offer an opt-out: "Sigo com o template padrão — quer ajustar algum campo antes?" Default to proceeding; iterate only if they ask. For deep field changes or saving a reusable [Template] Client Context, point them to the manage-context-template skill.

3. Auto-fill from available data

Read ../manage-context-template/references/context-doc-authoring.md — its reference, don't duplicate rule governs this step (table-backed facts become pointers, not copied values; see the reference for why). Fill each entity in three tiers:

• Reference (do confidently): the entity's key tables → @table::<LayerDisplayName>::<table> (from list_tables; use get_relevant_tables_ddl when you need columns), wired into the data‑bearing sections — ad accounts into Mídia Paga, subscriber/revenue/business metrics into Indicadores & KPIs and Modelo de Negócio. Use the layer display name in annotations (Raw, Trusted, Gold…), not the database name. List the entity's connectors in prose (inferred from table-name tokens — Google Ads, Meta Ads, HubSpot…); add @source::<slug> only if you actually know the slug from the Nekt web app, since it can't be read over MCP. Cadastral / demographic attributes (segment, size, industry, audience profile) when the entity has a CRM (hubspot, salesforce, pipedrive, rd_station) or an orgs/base table: reference them into Modelo de Negócio / Avatar — find which field holds each (via get_relevant_tables_ddl / get_table_preview) and write a @field::/@table:: pointer — do not copy the value into the doc. If a split transformation produced this entity's table (one table, many companies — see step 1), also link it with @transformation::<slug> (the slug create_query / create_notebook returns).
• Knowledge from the data (formulas, not values): for paid media (google_ads, meta_ads, tiktok_ads, ga4), capture the metric definitions/normalization in Mídia Paga (and business‑metric definitions/targets in Indicadores & KPIs), each with a reusable canonical query. Each platform names spend differently (Google cost · Meta spend · TikTok total_cost) — normalize it. Query (get_semantic_context → generate_sql → execute_sql, sanity-check via get_table_preview) to confirm field names and normalization, but the doc stores the formula and the query referencing those fields — never the current numbers.
• Unknown / judgment: leave > TODO (preencher com /edit-context <Nome>) — for the strategy sections not in any table (Forças & Fraquezas, Avatar, Concorrência, Tendências, Oportunidades & Ameaças, and qualitative findings in Redes Sociais / Reputação Digital / Website).

Compose each document per the authoring rules: summary sentence first, then the template sections, ~1200–1800 tokens.

4. Preview once, create in bulk, and report

create_context_document previews by default and must only be committed with confirm=True after the user has seen the content. To honor that without asking N times:

1. Show one representative document in full (pick the most complete, so the user sees real output quality), plus a one-line-per-entity summary for the rest (nome · campos preenchidos · N TODOs). Don't pre-dump every doc — offer "posso mostrar o texto completo de qualquer outro, é só pedir."
2. Get one explicit approval, then loop create_context_document(name=…, content=…, confirm=True) for each entity, capturing every returned doc_id. (If the user prefers to review each one, fall back to per-doc preview → confirm.)
3. Close in 2–4 lines — what was auto-filled, what's still > TODO (knowledge not in the data), and the next action:

Criei 7 docs. Auto: fontes, tabelas e campos-chave de todos; segmento/contatos referenciados no CRM de 4. Falta (não está nos dados): objetivos/KPIs e regras de negócio.
Preencher agora, ou depois com /edit-context <cliente>?

If the user says "agora", invoke the edit-context flow for the first entity.

Key behaviors

• Keep chat tight. Compact summaries and diffs, not full-doc dumps; collapse adjacent gates into one checkpoint; lean 2–4 line reports — see response-style.md.
• Reference, don't duplicate. Table-backed facts become pointers, not copied values — see context-doc-authoring.md.
• Confirm before writing. The grouping (step 1) and the create batch (step 4) are explicit checkpoints.
• Idempotent. Re-running skips entities that already have a doc (by name match), so it's safe to run repeatedly as new clients are added.
• One entity per document. Never blend clients/domains.
• Don't invent data. A confident > TODO is better than a wrong segment or size.