Documentation / MCP & AI

Skills

Author versioned Markdown playbooks that teach AI agents how to work in your Nexus environment, alongside the image-baked system skills that guide pipeline, report, and site authoring — all pulled on demand and governed by RBAC and version control.

A skill in Nexus is a reusable Markdown playbook stored on your server that an AI agent pulls on demand to learn how to do something in your environment. Skills are for teams who connect an assistant (Claude, Copilot, or any MCP client) to Nexus and want it to follow your conventions, runbooks, and gotchas instead of guessing. This page covers what skills are, the built-in system skills Nexus ships with, and how to author your own. It assumes you've already read Connecting AI Agents.

What a skill is

A skill is on-demand reference text, not executed code. Think of it as a checklist, a runbook, a domain glossary, or a "how we do X here" guide. When an agent connected over MCP decides a skill is relevant, it fetches the Markdown by name and follows it.

It is Markdown, not code. Unlike pipelines (sandboxed Python) and reports (JSON the engine runs), a skill's content is plain text the agent reads and reasons about. Nexus never executes it.
It is pulled deliberately, never auto-injected. Agents fetch a skill by name only when they judge it relevant. That keeps the agent's working context focused and makes every retrieval an explicit, auditable act rather than an invisible prompt-stuffing step.
It is version-controlled. Every save is a commit in your tenant's git history, so you can view, diff, and roll back any revision — the same version-control substrate that holds pipelines, reports, and sites.

Skills come in two flavors that share one surface: the system skills Nexus ships with (first-party, read-only authoring guides baked into the image) and your own tenant skills (the playbooks your team writes). Both are retrieved the same way; they differ in who can write them and where they live.

Why skills instead of a bigger prompt

The alternative to skills is stuffing conventions into a system prompt the agent always carries. That degrades quickly: the context bloats, unrelated guidance dilutes the task at hand, and you can't tell after the fact which guidance actually informed an action. Nexus takes the opposite approach — a retrieval model:

The agent pulls only the skill relevant to the job, so its context stays sharp.
Each pull is a discrete, observable event, which makes an agent's behavior explainable ("it read the reconciliation runbook, then ran these two reports").
Guidance is edited in one governed place and versioned, not copy-pasted into every client's config.

The built-in system skills

Nexus ships a small set of first-party authoring guides, surfaced as skills but write-protected and baked into the server image, so they always describe the exact version you are running. When you update the image, the guidance rolls with it — an agent can never read documentation for a different server version than the one it's talking to, and there is no manual sync or drift to manage.

The master guide is named simply nexus: it is the directory an agent should pull first. It orients the agent to what Nexus is, the running version, the caller's capabilities, and a map of which tool or guide to reach for next. From there the agent pulls the specific guide it needs.

Skill	What it covers
`nexus`	The master directory: what Nexus is, the running version, your capabilities, and a map of which tool or guide to reach for. Pull this first.
`nexus-authoring-pipelines`	Writing a pipeline: the `async def run(ctx)` shape and the `ctx` SDK for adapters, secrets, HTTP, workspace, and files.
`nexus-authoring-reports`	The report definition schema: multi-query, joins, group-by, aggregation, parameters, and pushdown.
`nexus-authoring-skills`	How to author a good tenant skill (the meta-guide).
`nexus-building-sites`	Building a hosted Site: the publishing flow, the client SDK, and the content-security constraints.
`nexus-site-styling-guide`	Styling conventions so generated pages look deliberate.

The nexus name and the nexus- prefix are reserved. System skills are immutable to everyone — no role can edit or delete them — and a tenant skill cannot claim a reserved name. Together that guarantees first-party guidance can never be shadowed, overwritten, or tampered with by a tenant author or a compromised token.

Tenant skills: your own playbooks

Your team's skills live in your tenant's version-controlled repository, right alongside pipelines, reports, and sites, and are authored through the same unified surface. A tenant skill is the place to encode the things a general-purpose model can't know: your table conventions, the report that answers a recurring question, the field that's in cents not dollars, the step that silently fails if skipped.

Because they're versioned like code, you can review a change before it ships, diff two revisions to see what an agent's guidance was at a point in time, and restore a known-good version if an edit made things worse.

Authoring your own skill

Tenant skills use the single, unified authoring surface shared with pipelines, reports, and sites. The same verbs apply to every kind, keyed by (kind, id).

Validate without saving: uql_validate(kind="skill", content="<markdown>").
Save (create or update): uql_save(kind="skill", id="<name>", content="<markdown>", meta={"description": "one-liner"}). Each save auto-commits to your tenant's git history.
Read back: uql_get(kind="skill", id="<name>").
List, history, diff, restore, delete: uql_list, uql_history, uql_diff, uql_restore, uql_delete.

Rules to know:

Naming: lowercase letter to start, then letters, digits, _ and -, up to 64 characters. The name is the id; there is no rename (delete and recreate). Reserved: you cannot use nexus or the nexus- prefix.
Size: the body must be non-empty and at most 256 KiB.
Permissions: saving or deleting a skill requires a human sign-in plus the skill:manage permission; reading requires skill:read. These are ordinary RBAC permissions — grant them narrowly.

Example: a focused runbook

# Reconcile invoices against the warehouse ledger

Use this when asked to find invoices that don't match the warehouse
ledger for a given month.

## Steps
1. Run the saved report `invoices-by-month` with `{ "month": "<YYYY-MM>" }`.
2. Run the saved report `ledger-entries-by-month` with the same month.
3. Join on `invoice_number`; flag rows present in one source but not the
   other, and rows where `amount` differs by more than 0.01.

## Gotchas
- Ledger amounts are in cents; invoice amounts are in dollars.
- Exclude voided invoices or they show as false mismatches.

How an agent uses a skill

Retrieval is the agent's decision, informed by the skill's name and description:

The agent lists available skills (or recalls them from the nexus master directory) and reads the one-line descriptions.
When a task matches, it pulls that skill's body by name via the get/read tool.
It follows the steps, calling the concrete tools the skill names (execute_report, query_data, and so on), each of which is still authorized against the agent's identity per call.

Crucially, a skill grants no privilege. It's guidance, not authorization. If a runbook tells an agent to run a report the connecting identity isn't allowed to run, the call still fails closed at the RBAC layer. Skills make an agent better informed, never more powerful.

Tips for skills worth pulling

An agent decides whether to pull a skill from its name and description, so write both to earn the fetch.

Lead with a one-line H1 that reads as a useful description, and add a "Use this when…" sentence right after.
Be concrete and copy-paste-able. Exact report names, field names, and snippets beat prose.
Keep it scoped. One skill, one job. Split big topics into linked skills.
Encode the gotchas. The non-obvious field, the required order of steps, the thing that silently fails: that is the highest-value content.
Never embed secrets. Reference secrets by name. Skills are versioned and readable by any skill:read principal.

Limits and boundaries

Skills are read, not run. They cannot perform an action on their own; they instruct an agent that then calls governed tools.
They confer no permission. RBAC is unaffected by what a skill says.
System skills are immutable and reserved. Tenant skills can never shadow them.
They are versioned and readable. Assume any skill:read principal can see the text; keep secrets and sensitive specifics out of the body.

Treat retrieved skill text as guidance to reason about, not policy to execute blindly. Pulling on demand, version control, and the reserved first-party namespace together keep that boundary clear and auditable.