| name | ctx-onboarding |
| description | Onboard a Context Engine tenant: confirm a model + embedder are configured, connect data sources (GitHub/GitLab/Jira/… repos + credentials) and ingest, then immediately show what CTX understood about each repo (what it is, stack, what it does, what it talks to) with a live semantic-search demo and an invitation to ask questions — and kick off the slower enrichment agents that build the service/dependency graph as a follow-on. Use for "set up / onboard / get started with CTX", "connect repos", or "what does CTX know about my system".
|
| allowed-tools | Bash(ctx-cli:*), Bash(curl:*) |
CTX onboarding
Prerequisites: requires ctx-cli installed and authenticated against the target
tenant. If it isn't, or you haven't run the once-per-session version check, see the
ctx skill first — it's the single source of truth for install/auth.
The flow is: check readiness → connect & ingest → show what CTX understood (fast) → deepen the graph (follow-on).
The model (agent LLM) and embedder are configured by the operator in the CTX web UI
(provider + cloud credentials — Vertex/Bedrock/keys; environment-specific), so the skill
checks them but does not set them. Everything else — connecting repos, ingesting,
running the agents that build the graph, and reporting what landed — the skill does.
AUTH=(-H "Authorization: Bearer $CTX_API_KEY")
Write rules: read current state first (idempotent / resumable); confirm before each
POST; never echo secrets (credentials never return data; runner-environments echoes
envVars — show only name/provider/isActive).
1. Check readiness (model + embedder)
Read-only. Verify the two operator-configured prerequisites; if either is missing, tell the
user to set it in the web UI → Settings and stop there for that capability.
curl -s -o /dev/null -w '%{http_code}\n' "${AUTH[@]}" "$CTX_API_URL/api/ai-settings/status"
curl -s "${AUTH[@]}" "$CTX_API_URL/api/runner-environments"
curl -s "${AUTH[@]}" "$CTX_API_URL/api/embedding-models/active"
- Model (agent LLM): no active runner environment → agents can't run (they fail
Not logged in · Please run /login). Step 3 needs this. → "configure it in Settings → AI."
- Embedder: all scopes
modelId:"default" (and find_entities 500s with "Semantic
search is not available") → no embedder; code/semantic search won't work. → "store an
OpenAI key in Settings." (Structural ingestion in Step 2 still works without it.)
Report a one-line readiness verdict, then proceed with whatever is available.
2. Connect data sources & ingest
Create the credentials and data sources, then sync. Read existing state first and skip
anything already connected.
curl -s "${AUTH[@]}" "$CTX_API_URL/api/credentials/meta/types"
curl -s "${AUTH[@]}" "$CTX_API_URL/api/credentials"
curl -s "${AUTH[@]}" "$CTX_API_URL/api/data-sources"
curl -s "${AUTH[@]}" -H 'Content-Type: application/json' -X POST "$CTX_API_URL/api/credentials" \
-d '{"name":"GitHub PAT","type":"github_pat","data":{"token":"ghp_..."}}'
curl -s "${AUTH[@]}" -H 'Content-Type: application/json' -X POST "$CTX_API_URL/api/data-sources/discover" \
-d '{"credentialId":"<cred-id>","owner":"my-org"}'
curl -s "${AUTH[@]}" -H 'Content-Type: application/json' -X POST "$CTX_API_URL/api/data-sources" \
-d '{"name":"ctx","type":"github","config":{"credentialId":"<cred-id>","owner":"codota","repo":"ctx","events":["push","pull_request"]}}'
curl -s "${AUTH[@]}" -X POST "$CTX_API_URL/api/data-sources/<id>/sync"
Credential type must match the source type (github→github_pat, gitlab→gitlab_pat,
jira/confluence→atlassian_api_token, servicenow→servicenow_basic_auth,
bitbucket→bitbucket_app_password, jfrog_*→jfrog_access_token) — the mismatch is
caught at sync (Credential type mismatch), not create. Bulk-connect by looping over the
discover results (confirm the set first). Omitting GitHub events fails validation
(expected array, received undefined); unfamiliar providers — confirm config shape from
an existing source via GET /api/data-sources.
Verify by data, not sync-status (which can stay null on the immediate-analysis path):
curl -s "${AUTH[@]}" "$CTX_API_URL/api/code-search/status"
3. Show what CTX read & understood (fast — this is the reveal)
The instant a repo finishes indexing (Step 2), CTX can already tell the user what their
system is and does — without waiting on the enrichment agents (Step 4), which are slow
and may not be seeded with the tier-1 composites on a fresh tenant. You (the agent
running this skill) produce this from the repo's own signal. For the first 1–2 ingested
repos:
3a. Pull the essence (cheap, fast).
3b. Write the precise profile — in plain language, this is the "smart system" moment:
- What it is — one or two sentences ("an MCP server that gives an AI long-term memory
via DuckDB").
- Type ▸ service / library / CLI / MCP server / infra …
- Stack ▸ languages + key frameworks/libs (from the manifest deps)
- Does ▸ its main capabilities (from the README / entry file)
- Talks to ▸ external systems (DBs, clouds, APIs, other services)
- Shape ▸ N files · N lines · top languages (from
RepositoryStats)
Drop generic metrics — raw counts as a headline and code-complexity scores don't read
as understanding; they read as noise.
3c. One live semantic hit — run a natural-language code_search and show it landing on
the right file. Proof CTX searches by meaning, not keywords:
🔍 "how does it authenticate?" → src/auth/credential.ts:22 (sim 0.70)
Render each repo as a compact card, e.g.:
📂 yonidavidson/brain-mcp
What it is ▸ an MCP server giving an AI long-term memory (last 2 conversations in
DuckDB; local / S3 / GCS backends)
Stack ▸ TypeScript · DuckDB · OpenAI SDK · node-cron
Does ▸ exposes MCP tools to store/recall conversation context
Talks to ▸ OpenAI · DuckDB · S3 / GCS
Shape ▸ 6 files · 1.6k lines · TypeScript 72%
🔍 "where is a memory persisted?" → src/index.ts:145
3d. Offer questions. Close by inviting the user to ask about their system, and answer
via ctx-search (code_search / find_entities). Suggest 3–5
grounded examples keyed to what you just profiled ("what external services does X depend
on?", "where would I add a new MCP tool?"). That's the hand-off into everyday use — and
it's available now, not after the slow agents.
4. Deepen the graph — enrichment agents (follow-on, slower)
Step 3 gives per-repo understanding immediately. To answer cross-service questions
("what depends on X", blast radius, flows), the service / dependency / flow graph has to
be built by enrichment agents — run these as a background follow-on, not a gate on the
Step-3 reveal. (Requires the model from Step 1; if it's not configured these fail
Not logged in.)
curl -s "${AUTH[@]}" "$CTX_API_URL/api/agent-kinds" \
| jq -r '.[] | "\(.id)\t\(.name)"' | grep -E 'service-discovery|dependency|package-linker|runbook|team'
curl -s "${AUTH[@]}" -H 'Content-Type: application/json' -X POST "$CTX_API_URL/api/agent-runs" \
-d '{"agentKindId":"<kind-id>","dataSourceId":"<ds-id>"}'
curl -s "${AUTH[@]}" "$CTX_API_URL/api/agent-runs/<run-id>"
Good builders from code sources: service-discovery-agent, then
service-dependency-deriver / service-package-linker. They're slow (multi-turn
LLM, minutes per repo) and time out on large repos — so kick them off and let the graph
fill in behind the Step-3 reveal; don't make the user wait on them. Surface failures plainly
(a Not logged in / token error → the agent model isn't usable, back to Step 1).
Once the graph is built, cross-service questions become answerable via
ctx-investigate (investigate_service, blast_radius,
understand_flow) and ctx-security (CVE / SAST inboxes). Until
then, stay on the Step-3 per-repo understanding rather than touring a bare service graph.
Tool availability is seed-dependent — ctx-cli mcp list may lack query_entities /
investigate_service / code_search ("Tool not found"). List first; for code search
fall back to REST (POST /api/code-search); prefer the tools that are listed
(find_entities, traverse_edges, get_entity_by_id).
