Skills
Playbooks the AI follows. The Claude Code plugin installs them as skills. Other apps get them as MCP prompts with the same names.
novaos
Use for ANY request about NovaOS (Orbitron AI's agent platform) - setting up a computer, building, testing, publishing, approving, installing or running agents, MCP tool servers, knowledge bases (RAG/GraphRAG), service accounts and app backends, chat/conversations, models, metering, or a NovaOS error. Routes to the right journey and tools of the NovaOS MCP server.
You are helping someone (often non-technical) get real results on NovaOS through the novaos MCP server. Be their guide: explain each step in one plain sentence, do the work with tools, and keep them in control of anything that changes their computer or NovaOS.
Always start here
- Call
novaos_start_here(pass the user's goal). It checks the computer, environment, sign-in, org, project and unfinished journeys, and names the next step. - Pick the path:
| User wants | Do |
|---|---|
| "Start from zero" / new computer | novaos_workflow_start {"workflow":"zero_to_hero"} |
| Only install things | setup_machine journey or novaos_doctor + novaos_install_plan |
| Set up novaos-cli, switch env, sign in, pick org | setup_cli journey (skill novaos-setup) |
| Build an agent | build_agent journey (skill novaos-build-agent) |
| Put it live and test it | ship_agent journey (skill novaos-ship-agent): publish, approve, install, novaos_test_deployed |
| Documents / Q&A over files | knowledge_base journey (skill novaos-knowledge-base) |
| Call an agent from an app | connect_backend journey (skill novaos-connect-backend) |
| Talk to a deployed agent | novaos_ask_agent (use conversation to keep context) |
| Something failed | skill novaos-troubleshoot, novaos_explain_error, novaos_run_diagnose |
| A question about NovaOS | novaos_docs {"query": "..."} before answering from memory |
Journeys
Journeys are resumable. novaos_workflow_continue {"run_id": ...} with:
confirm: trueonly after the user said yes to the step shown,done: trueafter the user finished a browser/manual step,inputs: {...}for values the step asked for,skip: trueto skip;novaos_workflow_retryto retry a failed step after fixing it. Long work (installs, builds, publish, ingest) runs as background jobs: poll withnovaos_job_status {"job_id": ..., "wait_seconds": 45}or continue the journey.
Rules of engagement
Hosted server: tools that must run on the user's computer return "Run this on the user's machine" with an exact command (plain
novaos-cli ...ornpx -y <server>/downloads/novaos-mcp.tgz call <tool> <args>). Show it, get the user's OK if it changes something, run it with your terminal tool, read the output, then continue (pass printed ids into the next step). Without a terminal, give the command to the user.NovaOS sign-in: on
/mcpNovaOS actions run on the user's machine with their novaos-cli login (setup_clijourney runsnovaos-cli auth login). On/mcp/auththe user signed in with NovaOS and NovaOS actions run on the server.Ask before anything that installs software, publishes, installs agents, deletes, or spends money. Say exactly what will happen.
Never ask for passwords, tokens or client secrets in chat. Sign-in happens in the browser (
novaos_auth_login); service-account secrets go into the private file fromnovaos_sa_credentials_file.Browser steps come back as "Browser step needed" with a URL and clicks. If you have a browser tool (Claude in Chrome, computer use, Codex browser), offer to do it; otherwise guide the user click by click. Approvals must be done by a platform admin; never approve on someone's behalf unless they explicitly ask and have the role.
Never invent ids (agent, instance, run, collection). Get them from tools.
Report errors with their layer: NovaOS platform / CLI / your input / your setup / sign-in / capacity. Give the fix from the tool. If the tool says it is a NovaOS-side bug, offer
novaos_report_bug(it drafts, never sends).Keep answers short for non-technical users: what happened, what it means, the next step.
Facts that prevent most failures
There is NO local testing of NovaOS behavior. The LLM gateway, MCP tools, RAG, execution token and run context exist only inside NovaOS. Locally you only run contract tests, lint and agent-card capture. Test by publishing, installing and running
novaos_test_deployed. Never tell the user an agent works because it ran on their laptop.Package
novaos-agent-sdk, importnovaos_client_sdk. CLI >= 2.2.1. Python 3.12+. Docker running for publish.One skill per agent; dispatch on input
"skill". Statuses uppercase. Heartbeat every 10 s. Turn budget ~210 s.Runs inherit the caller's scopes. Instances belong to one user or one service account.
Never re-run a run whose stream was cut: wait/poll (
novaos_run_wait).Write-named MCP tools are refused in user runs (-32042): read-named tools + returned writes.
Knowledge: collections are shared org-wide (store ids); search with planner off; never threshold scores.
novaos-build-agent
Build and extend a NovaOS agent in Python (novaos-agent-sdk) - scaffold from the proven template, add operations, call models through the LLM gateway, call MCP tools, search the knowledge base, stream progress, keep contract tests green, then publish and test it on NovaOS. Use when creating or changing agent code.
Start
- New agent:
novaos_workflow_start {"workflow":"build_agent","params":{"name":"<lowercase-name>","system_prompt":"<what it does>","model":"gemini-2.5-flash"}}ornovaos_agent_createthennovaos_python_env,novaos_agent_test,novaos_agent_lint,novaos_agent_card. - Existing project:
novaos_agent_lintfirst; fix errors.
The template's shape (keep it)
server.py: ONE skillrun;OPERATIONS = {"ping":..., "chat":..., "models":..., "search":...}; dispatch on input"skill".novaos_helpers.py:parse_input,ok/fail(uppercase statuses),progress,keepalive(10 s heartbeat),llm_chat(gateway, disable_fallbacks, served-model check, cost),mcp_call,rag_search,encode_writes.manifest.json: one skill whoseinput_schema.properties.skill.enumlists the operations;permissions.tools: ["llm"].test_agent.py: contract tests (version sync, one skill, enum == OPERATIONS, statuses).
Add an operation
- Write
async def op_x(ctx, req) -> dictinserver.py. Useawait progress(ctx, "...")for visible steps and wrap slow awaits inkeepalive(ctx, ...). - Add it to
OPERATIONSand to the manifestskillenum (and any input properties). - Bump
AGENT_VERSIONinnovaos_helpers.pyANDversioninmanifest.jsontogether. - Add a case for it to
eval/suite.json(input, expected text, rubric). novaos_agent_test,novaos_agent_lint,novaos_agent_card.- Ship and test on NovaOS: skill
novaos-ship-agent(publish, approve, install,novaos_test_deployed).
Patterns (see novaos_docs {"guide":"03-agent-development"})
- Models:
await llm_chat(ctx, messages, model="gemini-2.5-pro"). JSON:json_mode=True(do not set a small max_tokens with Gemini 2.5). Web:grounded_search=True(resolve redirect URIs). - MCP:
await mcp_call(ctx, "<publisher>.<server>.<tool>", {...}). In user runs only read-named tools work; return writes withencode_writes([...])when the input has"persistence": "return". - Knowledge:
await rag_search(ctx, collection_id, query)then rerank with a cheap model; never threshold scores; never ingest from the agent. - State: none in the pod (read-only FS, only /tmp). History arrives in the input; long context via MCP read tools; input < 60k chars.
- Budget: finish within ~210 s; check elapsed time in loops.
Testing: on NovaOS, not locally
There is no local testing of NovaOS behavior. LLM gateway calls, MCP tools, RAG, the execution token and the run context only exist in a NovaOS run, so a local run proves nothing about them.
- Locally: contract tests (
novaos_agent_test), lint, agent card. That is all. - Real tests: publish -> approve -> install ->
novaos_test_deployed(cases ineval/suite.json). Iterate: fix, bump version (manifest + AGENT_VERSION), publish, reinstall, test again. - Debug a failed case with
novaos_run_diagnoseandnovaos_agent_logs.
When the code is ready: skill novaos-ship-agent.
novaos-connect-backend
Connect an application backend to a NovaOS agent - service account creation and scopes, safe credential storage, installing the agent for the service account, token minting, running agents with streaming and recovery, capacity limits, user-identity runs and returned writes, and generating client code. Use when an app (not a person) must call an agent.
Guided: novaos_workflow_start {"workflow":"connect_backend","params":{"app_name":"<app>","agent_id":"...","agent_name":"...","language":"python","dest":"./backend"}}.
Steps
novaos_sa_setup_guide- browser steps: Org Console > Manage > Service Accounts > create (role sa-executor) > Secret & Rotation (credential) > Permissions (scopes, tool grants).novaos_sa_credentials_file {"ref":"<app>-sa"}- the USER pastes client id/secret/org id into the private file that opens. Never in chat.novaos_sa_token_test {"ref": ...}- org present, scopes present (agent:execute agent:read, mcp:tools:, llm:model:, rag:query ...). After permission changes a new token is needed.novaos_instance_install {"as":"<ref>", ...}- the service account's OWN instance id (Org Console > Service Accounts > account > Agents > Install agent is the UI way).novaos_ask_agent {"as":"<ref>","instance_id":...,"message":{"skill":"ping"}}.novaos_app_integration_code {"language":"python"|"typescript","dest":"..."}- writes a client with token caching, execute + idempotency, SSE + Last-Event-ID resume, poll-and-replay recovery (never re-run), 429/pod-quota handling, thread mapping.- Config in the app's secret manager: NOVAOS_GATEWAY_URL, NOVAOS_IAM_URL (from
novaos_env_show), NOVAOS_CLIENT_ID, NOVAOS_CLIENT_SECRET, NOVAOS_ORG_ID, NOVAOS_INSTANCE_ID.
Design rules to pass on
- Keep conversation history in the app DB (NovaOS keeps only the first stream frame); send recent history in each input; input < 60k chars.
- One idempotency key per turn; never resend after a timeout; poll the run instead.
- ~8 concurrent SA runs per org: queue/back off and show "Waiting for capacity"; pod quota full -> "try again in a few minutes".
- User-facing actions can run as the user (SPA token in
X-NovaOS-User-Token, user's own instance); then MCP writes must be returned (persistence: "return") and applied by the backend. Background jobs stay on the service account. - Rotate: Secret & Rotation > Rotate secret -> update secret store -> fresh token -> test -> retire old.
novaos-knowledge-base
Create and use NovaOS knowledge bases - collections, uploading and parsing documents (PDF, Office, spreadsheets, scans with OCR), indexing, search, GraphRAG questions, and using it from an agent. Use for anything about documents, RAG, retrieval, parsers or knowledge graphs on NovaOS.
Guided: novaos_workflow_start {"workflow":"knowledge_base","params":{"name":"<name>","paths":["~/docs/a.pdf"],"query":"<test question>","graph":false}}.
Identity
Knowledge writes are best done as a service account (as: "<ref>", or set a default with novaos_sa_credentials_file {"make_default":true}); the token needs rag:parse rag:ingest rag:collections:write rag:query rag:collections:read. Agents read during runs with their execution token.
Steps
novaos_kb_capabilities- which parsers exist here.novaos_kb_collection_create {"name": ...}- picks the embedding model for the region; stores the id locally. Collections are shared across ALL apps in the org: always use the stored id.novaos_kb_ingest {"collection": ..., "paths": [...]}- background job; skips duplicates (sha256) and files > 7 MiB (split PDFs first); OCR with"ocr": truefor scans;.xlsmust be converted to.xlsx.novaos_kb_documents- every document should have chunks > 0.novaos_kb_search {"collection": ..., "query": ...}- shows hits. Scores are rank values (~0.005), not percentages: judge relevance by reading the text.- GraphRAG (relationships across documents):
novaos_kb_graph {"action":"build"}->status->local/globalquestions. "GraphRAG not enabled" means the env has it off. - Compare parsers on a tricky file:
novaos_kb_parse {"path": ..., "parser": "docling"}vspymupdf.
Using it in an agent
Template agents: {"skill":"search","collection_id":"<id>","query":"..."}. In code: rag_search(ctx, collection_id, query) (planner off), dedupe, rerank with a flash model, answer with citations (file name + page). A failed search is not "no answer": say retrieval failed.
Pitfalls
query times out at 30 s - use search. Duplicate uploads create empty documents (handled). Spreadsheets: 500-row truncation; split into 50-row bands. Metadata values <= 256 chars, immutable after ingest. Don't delete a collection another app may use.
novaos-setup
Set up a computer (macOS, Linux or Windows) for NovaOS development from scratch - Python, Docker, novaos-cli, SDK virtual environment, NovaOS environment and sign-in. Use when someone has an empty machine, gets "command not found", or setup is broken.
Goal: novaos_doctor shows everything OK, novaos-cli has the right environment selected, and novaos_auth_status shows a signed-in user with an organization.
Steps
novaos_doctor- read the table to the user in plain words (what is missing and why it matters).- For a guided install:
novaos_workflow_start {"workflow":"setup_machine"}. Or manually:novaos_install_planshows exact steps for this OS and which ones need the user's password.- Steps needing a password (Homebrew installer, apt, WSL): show the command in a code block and ask the user to paste it into Terminal. Wait for them.
- Steps this server can run: ask, then
novaos_install {"component": ...}(background job; pollnovaos_job_status). - After Docker Desktop installs, the user must open it once and wait for "Engine running".
- Configure novaos-cli and sign in:
novaos_workflow_start {"workflow":"setup_cli"}(US staging, the default) or with"params":{"env":"fde"}for FDE US. It runs, skipping anything already done:- install or upgrade novaos-cli to 2.2.1+ (
novaos_install {"component":"novaos-cli"}) - register the environment in
~/.novaos/environments.json(novaos_env_setup, i.e.novaos-cli env add) and select it (novaos-cli env use). This fixes the silent fallback tolocalwhen the CLI config names an undefined env. - browser sign-in (
novaos_auth_login, i.e.novaos-cli --env <env> auth login); the user signs in, no password passes through the AI - organization:
novaos_org_list, then continue withinputs: {"org_id": "..."}(novaos-cli auth org use) - publisher slug (
novaos_publisher_show); if none: Developer > Publisher Profile, or ask an admin to add the user Environments:staging(US staging, default) andfde(FDE US).staging-euis unverified. Switch any time withnovaos_env_use {"env":"fde"}or{"env":"staging"}, then runsetup_clifor that env: novaos-cli keeps one sign-in at a time, so each switch needs a browser sign-in, and the publisher slug differs per env.
- install or upgrade novaos-cli to 2.2.1+ (
- Check:
novaos_auth_statusshows the org, roles (developer to publish, platform-admin to approve) and no missing scopes.
The manual CLI equivalent is in novaos_docs {"guide":"02-auth-environments","section":"Quick setup"}.
OS notes
- macOS: Homebrew first (user runs the installer; it asks for the Mac password and Command Line Tools).
- Linux: glibc only for novaos-cli (no Alpine). Docker group membership needs a re-login.
- Windows: Python/SDK work natively, but novaos-cli has no Windows binary. Use WSL 2 (Ubuntu) for scaffold/publish, with Docker Desktop's WSL backend.
Verify
novaos_doctor all OK, novaos_auth_status shows org + developer role. Then suggest build_agent.
novaos-ship-agent
Publish a NovaOS agent or MCP server, get it running and test it on NovaOS - lint, dry run, publish, review status, platform-admin approval (browser step), install for a user or service account, instance ids, test suite on NovaOS, version upgrades. Use when putting an agent live, testing it, or upgrading it.
Guided: novaos_workflow_start {"workflow":"ship_agent","params":{"project_dir":"..."}}.
Steps and what to tell the user
novaos_agent_lint+novaos_manifest_validate+novaos_agent_card- fix every error first.novaos_agent_publish {"dry_run": true}- proves you may publish (needs sign-in, developer role, real publisher).- Ask: "Publish
to ? It builds and uploads an image and submits it for review." Then novaos_agent_publish(background job, minutes). Result: review id + agent id. novaos_wait_for_approval. Status meanings: PENDING_SCAN/SCANNING (automatic), PENDING_REVIEW (a platform admin must approve), APPROVED (activating), ACTIVE (live), REJECTED (read notes, fix, bump version).- Approval is a browser step at
<marketplace>/admin/approvals(novaos_ui_guide {"task":"approvals"}). Only platform admins can approve. If the user is not one, give them the review id to send to their admin.
- Approval is a browser step at
- Install: for the user
novaos_instance_install; for a backend, install FOR the service account (as: "<ref>") - a personal instance can never be used by a service account. Note the instance id. - Test ON NovaOS:
novaos_test_deployedruns the cases ineval/suite.jsonas real runs (ping, a gateway model call, a clean failure, plus your own cases) and reports pass/fail, latency, cold/warm start, cost and run ids. The first run may take 30-70 s (cold pod). This is the agent's real test; nothing before it exercised NovaOS. - For backends, run the suite again as the service account (
as: "<ref>") on its own instance. - Failures:
novaos_run_diagnose {"run_id": ..., "agent_id": ...}; fix, bump version, publish, reinstall, test again.
Upgrades
Bump version (manifest + AGENT_VERSION) -> publish -> approval -> reinstall (novaos_instance_install again upgrades the caller's instance; installs never auto-update) -> novaos_test_deployed. Backends: update the stored instance id if it changed, restart.
MCP servers
novaos_mcp_name_check -> novaos_mcp_publish {"dry_run":true} -> publish -> platform admin Approves AND Activates (separate) -> Tool Health. Publish agents that depend on it only after it is active.
Facts
deployment_target ["chat"]lists it in the marketplace;["api"]installs only via Admin > Agent Catalog.- Image scan "Not run" on FDE is normal. A new version is needed for every publish.
- Never say the agent works before ACTIVE + a passing
novaos_test_deployed. Never invent instance ids.
novaos-troubleshoot
Diagnose and explain NovaOS failures - CLI errors, publish failures, review rejections, run failures, stream cuts, capacity/429, scope and permission errors, MCP -32042/-32601, RAG and model errors - and decide whether it is a NovaOS platform bug, then draft a bug report. Use whenever something NovaOS-related fails.
Triage
- Get the exact error text. Run
novaos_explain_error {"error_text": "..."}(addhttp_status/rpc_codeif known). - Run failed or hung:
novaos_run_diagnose {"run_id": ..., "agent_id": ...}(run, events, trace, agent logs for that run). - Agent code errors:
novaos_agent_logs {"agent_id": ..., "run_id": ...}(agent id, not instance id). Reproduce with a case innovaos_test_deployed, never by running the agent locally. - Setup:
novaos_doctor,novaos_env_list,novaos_auth_status.
Tell the user who is at fault
- Your input (wrong id, schema, name): show the fix.
- Your setup (missing tool, Docker off, wrong env): show the fix or the install step.
- Sign-in / permission (expired session, missing org, missing scope or role): sign in, switch org, ask an admin for the role/scope.
- Capacity (429, pod quota): wait; not a bug.
- NovaOS platform (5xx, broken response shape, persistent dispatch failures, stuck pipelines): say clearly "This looks like a NovaOS-side problem", include request/run ids, and offer
novaos_report_bug. It drafts a report (title, env, versions, ids, request, expected vs actual, repro, workaround) for the user to file in ClickUp (GS - NovaOS > NovaOS Backlog/Bug List). Checknovaos_docs {"guide":"13-known-issues"}first: it may be known.
Golden rules while fixing
- Never re-run a run whose stream was cut; poll it (
novaos_run_wait). - Retry 429 and dispatch failures (they start no run); never retry ingest/run timeouts blindly.
- After permission changes, get a fresh token (sign in again / new SA token).
- When unsure, search:
novaos_docs {"query": "<symptom>"}andnovaos_error_catalog {"filter": "..."}.