agency-onboarding

name

agency-onboarding

description

Guide an agency owner through getting started with Nekt — from an empty workspace to per-client context. Inspects what the workspace has so far, helps connect and organize the agency's clients' data sources (and, optionally, the agency's own internal/operational data), then hands off to build-context so agents querying the data give accurate, well-scoped answers instead of generic ones. Use this when someone is starting out, just connected the Nekt MCP and isn't sure what to do, or asks how to set up / where to begin — e.g. "começar a usar o Nekt", "onboarding da agência", "configurar meu workspace", "acabei de conectar o Nekt, e agora?", "por onde eu começo", "como organizar meus clientes no Nekt", "get started with Nekt", "set up my agency workspace", "onboard my agency", "I just connected Nekt — what now?". Inspects via list_tables / list_layers / list_volumes / get_semantic_context, guides source setup via ask_about_nekt + the Nekt web app, and hands off to build-context / edit-context.

Agency Onboarding

An agency's Nekt workspace starts empty, and even once data lands, an agent reading it over MCP can't tell which data belongs to which client until per-client Context documents exist. This skill is the front door: it looks at what the workspace has so far, guides the owner through connecting and organizing their clients' data sources (and, if they want, the agency's own internal/operational data), and then hands off to build-context to build the per-client Context documents that make answers accurate. It inspects and guides — it never adds sources or writes data itself.

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. This skill uses list_layers, list_tables, list_volumes / list_files, get_semantic_context, and ask_about_nekt to inspect the workspace and fetch setup steps, and it hands off to the build-context / edit-context skills for the context-document work. If those tools aren't available, tell the user to connect the Nekt MCP and stop.

Note: this server has no list_sources tool and no way to add a source — sources are connected in the Nekt web app. Classify what exists from tables / layers / files / context docs, and guide source-adding rather than performing it.

Reference files (read when you reach the relevant step)

• ../manage-context-template/references/response-style.md — how to talk to the user (brevity, lean recaps, don't lecture). Read first.
• references/nekt-concepts.md — plain-language explanations of Nekt terms (source, layer, context document…) for newcomers. Read once when a term first needs explaining.
• references/source-organization.md — how to name and group sources so clients stay distinguishable later. Read at step 4.
• The hand-off target build-context reads client-discovery.md and loads the context-doc structure from the manage-context-template skill (client-context-template.md, context-doc-authoring.md) — you don't need them here.

Workflow

1. Greet and frame the journey

In two or three lines (don't lecture), tell the user in their language what onboarding will do: look at what's in the workspace today, help connect and organize their clients' data sources (optionally the agency's own data too), then gather per-client context so answers come out accurate and scoped. Don't assume Nekt fluency — say you'll explain terms as they come up, and actually do it (a sentence or two each, from references/nekt-concepts.md) whenever a concept appears.

2. Inspect the workspace

Find out what's already there — read-only, never write at this step:

• list_tables — paginate via page_token until exhausted; count tables and note their layers and any tags (tags that name a client/domain reveal how the workspace is already organized — a strong grouping signal build-context will use later).
• list_layers — which layers exist.
• list_volumes / list_files — any uploaded files/documents.
• get_semantic_context("clientes contexto perfil visão geral") — probe for existing Context documents.

Ignore the Sample data layer. Nekt auto-creates it in every new workspace as mock data for testing — it is never the agency's real data. Exclude it from list_layers and skip every table whose layer is Sample data (case-insensitive) when counting. A workspace whose only tables live in Sample data counts as empty.

Classify the workspace and route accordingly:

State	Signal	Go to
Empty	no real tables (the auto-created Sample data layer doesn't count), no files, no context docs	step 3
Has data, no client context	tables/files exist, but no Cliente — … / Client — … docs	step 5
Already onboarded	data and client Context documents exist	see below

Summarize what you found in the user's language — e.g. "Encontrei 12 tabelas em 2 layers e 3 documentos de contexto." — so they see the starting point. That summary itself leans on Nekt terms (tabelas, layers, documentos de contexto); for a newcomer, gloss each the first time in a clause — "layers são agrupamentos que você define para organizar suas tabelas — cada workspace define o próprio esquema" — per references/nekt-concepts.md.

If already onboarded: don't redo work. Tell them they're set up and offer to (a) refresh/extend context (build-context / edit-context), (b) connect more sources (step 3), or (c) review what's there. Follow their choice.

3. Guide source connection

Sources are connected in the Nekt web app, not through this MCP. So:

1. Call ask_about_nekt("How do I connect a new data source in Nekt?") and relay the current steps concisely, plus where to do it (use the link the tool returns, or point to the Nekt app at nekt.ai). Don't invent UI steps — use what the tool returns.
2. Recommend starting small: 1–2 key sources per client — the CRM first (it drives segment / size / contacts later), then the main sales/ops tool (Shopify, ad platforms, a database…).
3. Connecting and the first sync happen out-of-band and can take a few minutes. Tell the user to come back when a source is connected, and offer to pause and re-inspect (list_tables) when they're ready — don't block.

4. Teach source organization

Read references/source-organization.md, then coach the user — this is the part that makes the later context step accurate:

• Describe every source by client, with a consistent delimiter: ACME | HubSpot, ACME | Shopify orders, Padoca Digital - Meta Ads. Discovery groups sources into clients by their description and output folder — opaque slugs like hubspot-5MyL carry no client meaning.
• Keep each client's sources together (shared output folder) and don't mix clients.
• Good hygiene now → build-context groups clients correctly later, with little correction.

4a. Optional — the agency's own data

Ask whether they also want to bring in the agency's own internal/operational data — their finance, their own CRM/pipeline, delivery / PM / timesheets. If yes, use the same step-3 guidance to connect it and the step-4 conventions (treat the agency as its own entity, e.g. described Minha Agência | …), so it gets its own Context document alongside the clients. If they'd rather stick to client data for now, skip cleanly — onboarding is safe to re-run.

5. Confirm data landed, then hand off to context gathering

When the user has connected sources, re-inspect with list_tables to confirm tables have appeared (if a sync is still running, tell them to wait a few minutes and re-check). Once data is present:

• Continue into the build-context flow to discover clients from the sources and create one Context document each — do not re-implement discovery or doc creation here; that skill owns it. It will propose a context-doc structure for the user's approval before creating anything, then auto-fill what the data supports. Offer to start now, or tell them to run /build-context when ready.
• After that, /edit-context <cliente> fills the judgment-call gaps (objetivos, KPIs, regras de negócio).

Frame the payoff in the user's language: this per-client context is what makes Nekt's answers accurate and scoped to the right client instead of generic.

6. Wrap up

Recap in 2–3 lines — what's done and the single next action, e.g. "Workspace inspecionado e fontes organizadas por cliente. Próximo: gerar os documentos de contexto com /build-context." Re-running /agency-onboarding anytime is safe — it re-inspects and picks up from wherever you are.

Key behaviors

• Keep chat tight and respond in the user's language — brief framing, a one-line inspection recap, a lean wrap-up; don't lecture. See response-style.md.
• Assume no prior Nekt knowledge. When a concept first comes up (source, connector, output folder, layer, table, context document, semantic layer), explain it in one or two plain sentences — what it is and why it matters — before asking the user to act on it. Adapt: skip what they clearly know, keep it brief, and read references/nekt-concepts.md for the stable basics.
• Inspect read-only. This skill never adds sources or writes/deletes workspace data — source-adding happens in the Nekt app, and context-document writes happen inside the handed-off skills (which confirm first).
• Orchestrate, don't duplicate. Defer to build-context / edit-context for context docs; defer to the Nekt web app for connecting sources.
• Idempotent — safe to re-run. Detect the current state and resume from the right step; never redo completed setup.
• Async-friendly. Connecting sources and the first sync happen out-of-band; offer to pause and re-inspect rather than blocking.
• Don't fabricate. Use ask_about_nekt for accurate setup steps, for product/UI specifics, and for any concept you're unsure about in this workspace; if it's unavailable, point the user to nekt.ai and the Nekt docs generically. Never invent steps or data.
• No list_sources. Classify the workspace from tables / layers / files / context docs — this MCP can't list or add sources.