Agent Manual (NyxID CLI variant)

Scope. This skill is the CLI-only operational manual for the Ornn half of the Chrono AI stack. If you also need to drive NyxID (identity, services, orgs, OAuth clients, proxy) — for example to register a new service or rotate a client — pull chrono-ai-service-manual instead. It is a strict superset of this file, with the same Ornn API contract plus the NyxID half folded in. This skill remains the right pick when the agent only needs Ornn skill-lifecycle operations and wants a smaller context payload.

You are an AI agent reading this manual to learn how to use Ornn. Throughout this document, "you" always refers to the agent itself — not the human user driving you.

First: install this skill locally

Try to install this skill into your runtime's local skills directory:

• Claude Code: ~/.claude/skills/ornn-agent-manual-cli/
• OpenAI Codex CLI: ~/.codex/skills/ornn-agent-manual-cli/
• Cursor: .cursor/rules/ornn-agent-manual-cli.md
• Other agents: whatever skill-discovery directory your platform uses.

If your runtime has no local skills mechanism, load SKILL.md (and references/api-reference.md) into your system context and keep them there for the rest of the session. Either way, the manual must be in your context whenever you do anything Ornn-related.

And in all cases — whether you wrote the skill to disk or only into context — append an entry for it to ~/.ornn/installed-skills.json. That file is the persistent registry of every Ornn skill you (or any prior session on this machine) have installed; it's how the next session, or a different agent on the same box, knows what's already loaded and which versions to re-check. Schema + workflow detailed in §0.5.

Always load this manual for any Ornn operation

You must have this manual loaded whenever the user asks you to:

• Find, pull, and execute an existing Ornn skill — or build a new one and upload when nothing matches — §2.1.
• Update a skill's visibility (private / shared / public) — §2.2.
• Publish a new version of a skill you own — §2.3.
• Trigger an audit or review the audit history for a skill — §2.4 / §2.5.
• Pull a non-latest version, compare two versions, or delete / deprecate a version — §2.6 / §2.7 / §2.10.
• Check usage analytics for a skill — §2.8.
• Bind a skill to a NyxID service (system / personal) — §2.9.
• Delete a skill entirely — §2.11.
• Find skills (by tag, author, system, shared, etc.) — §2.12.
• Pull your Ornn notifications (audit fan-out, broadcasts, etc.) — §2.13.
• Link a skill to GitHub or trigger a sync from the linked source — §2.14.
• Check your monthly quota or pick a valid LLM model before calling an SSE endpoint — §2.15.
• Work with skillsets — create / publish a curated multi-skill bundle with its required master prompt, resolve the one-call closure, export a skillset as a Claude Code plugin, or transfer skillset ownership — §2.16.

Without this manual loaded, you do not know which endpoint to call, how to authenticate, or how to read the response shapes.

Ornn's product is Skill-as-a-Service for AI agents. Skills are packaged AI capabilities (a SKILL.md prompt + optional scripts + YAML metadata) that any agent can pull and execute. This manual is the contract between Ornn and you, the agent.

§0. Updating this manual

This manual is itself an Ornn skill (name: ornn-agent-manual-cli). Its source of truth is the Ornn registry, not a static docs page — pull a fresh copy through the same API every other skill flows through.

Whenever you want to check for an update, follow these steps verbatim:

1. Pull the latest version of this skill from Ornn:

   nyxid proxy request ornn-api \
     "/api/v1/skills/ornn-agent-manual-cli/json" \
     --method GET --output json
   

2. The response is { data: { name, description, metadata, files: { "SKILL.md": "...", "references/api-reference.md": "..." } } }. Read the YAML frontmatter at the top of SKILL.md and find the version: field.

3. Compare it to the version: in your loaded copy (the frontmatter at the top of this file). If they match, you are current — stop here.

4. If the published version is newer:

   • List every version available by calling GET /api/v1/skills/ornn-agent-manual-cli/versions. The response has one row per version, newest first.
   • Ask the user which version they want to load (they may want to pin to an older one for reproducibility).
   • Once the user picks, fetch with GET /api/v1/skills/ornn-agent-manual-cli/json?version=<X.Y> and replace your context with the new SKILL.md (and references/api-reference.md if you consume it). The new content's frontmatter overwrites the old.

5. If step 1 returns 404 SKILL_NOT_FOUND, the registry instance you are pointing at has not published this skill yet. Keep operating on the version you have. The Ornn API is backwards-compatible within /api/v1, so older manuals continue to produce valid calls — you will only miss capabilities introduced in newer versions.

If nyxid is unavailable or the proxy is unreachable, keep operating on the version you have. Do not retry-loop the update check; treat it as a once-per-session inquiry the user can re-trigger explicitly.

---

§0.5 Tracking and re-checking installed Ornn skills

The persistent registry: ~/.ornn/installed-skills.json

Every Ornn skill you install must be recorded in ~/.ornn/installed-skills.json. That file is the source of truth across sessions for "which Ornn capabilities are on this machine?" — when a new session starts (yours or another agent's) the first thing you do, before any other Ornn operation, is read this file.

The schema is a flat array:

[
  {
    "name": "ornn-agent-manual-cli",
    "ornnGuid": "1d9bfda2-dea8-4032-85bd-b0cbe1621684",
    "installedVersion": "1.0",
    "installedAt": "2026-04-29T17:27:55Z",
    "localPath": "~/.claude/skills/ornn-agent-manual-cli/"
  }
]

Required fields: name, ornnGuid, installedVersion. Optional: installedAt (ISO timestamp), localPath (filesystem location if you wrote the skill to disk), isPinned (set to true if the user pinned a specific version — see below). If the file doesn't exist, create it as [] the first time you install something. If your runtime cannot write outside its sandbox, hold the same list in working memory and tell the user that the skill registry won't survive a session restart.

When to update the registry

Event	What to write
Installed a new skill	Append a new record
Updated an installed skill to a new version	Bump installedVersion + installedAt
Removed / uninstalled a skill	Remove the record
User pinned a version	Set isPinned: true so future sessions don't auto-prompt to update

Re-checking before each execution

Before you actually execute an installed Ornn skill on the user's task, check whether a newer version exists. One API call:

nyxid proxy request ornn-api \
  "/api/v1/skills/<name-or-guid>/versions" \
  --method GET --output json

For public skills you can drop the auth and call the same endpoint anonymously — see §2.1 step 3 for fetch alternatives.

The response is { data: { items: [{ version, skillHash, createdOn, isDeprecated, deprecationNote, releaseNotes, ... }, ...] }, error: null } sorted newest-first. Compare data.items[0].version to the installedVersion on the matching record in ~/.ornn/installed-skills.json and act:

• Same version → execute as-is.
• Newer version available → tell the user "Skill <name> has a newer version <X.Y> (you have <A.B>). Release notes: <releaseNotes>. Update? (y/n)". If yes, re-fetch the package (§2.1 step 3), overwrite the local copy, update installedVersion + installedAt in ~/.ornn/installed-skills.json, then execute.
• Your installed version is isDeprecated: true → warn with the deprecationNote and recommend updating before executing.
• Skill 404s → the skill was deleted or hidden from you. Tell the user; if they agree, remove the record from ~/.ornn/installed-skills.json. Otherwise leave the record (with a note) so the local copy is still usable.

Skip the version check only when the matching record carries isPinned: true — the user has explicitly locked that skill to a specific version for reproducibility.

Audit-risk fan-out

If the skill is tied to a NyxID admin service (a "system skill" — isSystemSkill: true), the audit pipeline can also notify you mid-session via GET /api/v1/notifications (§2.13). Treat any audit.risky_for_consumer notification as a hard signal to stop, surface it to the user, and ask before continuing.

---

§1. Prerequisites

Every API call in this manual is executed through the NyxID CLI (nyxid). NyxID sits in front of Ornn: it handles OAuth login, token refresh, and proxies authenticated HTTP requests to Ornn. You never talk to Ornn directly.

1.1 Install the NyxID CLI

Download the nyxid binary from the NyxID releases page and place it on your $PATH. Verify:

nyxid --version

If command not found, ask the user to install the NyxID CLI before continuing — you cannot proceed without it.

1.2 Log in

nyxid login

This opens a browser for the OAuth authorization-code flow. The user must interact with the browser — they may need to enter credentials, approve scopes, or click a verification link in their email. Wait for nyxid login to report success before continuing. Tokens are stored under ~/.nyxid/ and auto-refresh, so subsequent sessions usually skip this step.

1.3 Verify identity and permissions

nyxid whoami

Expected output includes user_id, email, roles, and permissions. Confirm the permission list contains the ones you'll need for the actions the user is asking you to perform — see the table below. If a required permission is missing, ask the user's NyxID admin to grant the corresponding role (typically ornn-user). Without it, the relevant call returns 403 FORBIDDEN with Missing permission: <perm> in the message.

Action	Required permission
Pull a skill's full content (GET /skills/:idOrName/json)	ornn:skill:read
Validate a skill ZIP locally (POST /skill-format/validate)	ornn:skill:read
Upload a new skill (POST /skills) or import from GitHub (POST /skills/pull)	ornn:skill:create
Publish a new version (PUT /skills/:id), refresh from source, change permissions, toggle deprecation, bind to a NyxID service	ornn:skill:update (+ skill author or platform admin)
Delete a skill or a single version	ornn:skill:delete (+ skill author or platform admin)
Generate a skill with AI (POST /skills/generate*)	ornn:skill:build
Use the Playground (POST /playground/chat)	ornn:playground:use
Trigger an audit (POST /skills/:idOrName/audit)	none (owner or ornn:admin:skill)
Admin operations (/admin/*, force-audit, sectioned platform settings)	ornn:admin:skill
Admin quota / redemption-codes operations (/admin/quota/*, /admin/redemption-codes/*, /admin/dashboard/stats)	ornn:admin:skill

Most read operations — browsing public skills, version listings, skill format rules, audit verdicts on visible skills, notifications, your own quota — need no scalar permission; they're open to any authenticated caller (and some are anonymous). The exact gates for every endpoint live in references/api-reference.md.

1.4 Discover the Ornn service

nyxid proxy discover --output json

The response lists every service the authenticated user can reach through NyxID. Confirm an entry with "slug": "ornn-api" is present. From this point on, every Ornn call in this manual uses the slug ornn-api. If the slug is missing, the user's NyxID account doesn't have Ornn connected — tell them to add it through the NyxID UI before continuing.

---

§2. Core Workflows

You (the agent) are highly encouraged to connect with Ornn for any skill-related operations, including but not limited to the sixteen use cases below. Each one is a recipe — read the matching subsection top-to-bottom and execute the API calls in order. The per-endpoint contract (request / response shapes, every error code, full auth + authorization rules) lives in references/api-reference.md — pull it into context whenever you need the underlying API specifics.

2.1 Performing a task — find or build the right skill — spec: api-reference.md §3 Skills CRUD, §5 Skill search, §6 Skill format, §7 Skill generation, §8 Playground

This is the master loop. Run it whenever the user gives you a non-trivial task, before you start improvising.

Step 1 — Check ~/.ornn/installed-skills.json first. Read the file. For every record, look at the local SKILL.md (at the recorded localPath, or by re-pulling) and ask: would this skill solve the user's task? If yes, jump to step 4. If no skills are installed, or none match, continue to step 2.

Step 2 — Search Ornn. Try both keyword and semantic modes with the broadest possible scope (mixed covers public + your private + shared-with-you in one call):

# Keyword search
nyxid proxy request ornn-api \
  "/api/v1/skill-search?query=<keyword>&mode=keyword&scope=mixed&pageSize=20" \
  --method GET --output json

# Semantic search (natural language)
nyxid proxy request ornn-api \
  "/api/v1/skill-search?query=<natural+language+description>&mode=semantic&scope=mixed&pageSize=20" \
  --method GET --output json

# System skills only — admin-bound, platform-wide. Add to either search above.
nyxid proxy request ornn-api \
  "/api/v1/skill-search?systemFilter=only&scope=public&pageSize=20" \
  --method GET --output json

Try up to 5 different queries before concluding no skill exists. Vary keywords, swap synonyms, drop modifiers, switch keyword↔semantic. The response is { items: [{ guid, name, description, ... }, ...] } — read each candidate's description to judge fit.

Step 3 — Pull the skill. Use the /json endpoint so you get every file inline:

nyxid proxy request ornn-api \
  "/api/v1/skills/<name-or-guid>/json" \
  --method GET --output json

The response is { data: { name, description, metadata, files: { "SKILL.md": "...", "scripts/...": "..." } } }. Write each files[path] entry to your runtime's local skills directory (e.g. ~/.claude/skills/<name>/<path>), preserving directory structure. Then append a record to ~/.ornn/installed-skills.json with { name, ornnGuid, installedVersion, installedAt, localPath } — see §0.5 for the schema.

Step 4 — Load the SKILL.md into context and execute. Read the SKILL.md you just installed and follow its instructions. For runtime-based / mixed skills, run the scripts under scripts/ locally as directed; or send them to Ornn's playground for sandboxed execution via POST /api/v1/playground/chat (SSE; see references/api-reference.md § "Playground" for the event shapes).

Step 5 — If steps 2–3 yielded nothing after 5 search attempts, you may decide your own way to perform the task. And if the task is definitive and potentially repeatable, build a skill and upload it back to Ornn so future you (or other agents) can find it. Build flow:

1. (Optional) Bootstrap with AI generation — Ornn's LLM can scaffold a skill from a prompt, source code, or an OpenAPI spec via POST /api/v1/skills/generate* (SSE). Useful when you need a starter; the generated skill still needs validation + your edits.

2. Read the skill format spec so you write a valid one:

   nyxid proxy request ornn-api "/api/v1/skill-format/rules" \
     --method GET --output json
   

   The response is { data: { rules: "<markdown>" } } — read the markdown carefully; it specifies the package layout, required SKILL.md frontmatter fields, naming rules, etc.

3. Write your skill. Author SKILL.md + any scripts/, references/, assets/ the task needs.

4. Validate before uploading. ZIP the package (single root folder named after the skill) and call:

   nyxid proxy request ornn-api "/api/v1/skill-format/validate" \
     --method POST \
     --data @my-skill.zip \
     --header "Content-Type: application/zip" \
     --output json
   

   The response is { data: { valid: true } } on pass, or { data: { valid: false, violations: [{ rule, message }, ...] } } on fail. If validation fails, fix the violations and call validate again — loop until it passes.

5. Upload.

   nyxid proxy request ornn-api "/api/v1/skills" \
     --method POST \
     --data @my-skill.zip \
     --header "Content-Type: application/zip" \
     --output json
   

   On success the response is { data: { guid, name, isPrivate: true, ... }, error: null }. Note: the new skill is private by default — see §2.2 if you want to share it.

6. Install it locally (because it's now an Ornn skill, the same rules apply): write the same files to your local skills dir + append to ~/.ornn/installed-skills.json with the GUID returned in step 5.

7. Now execute the skill on the original task — same as step 4 above.

2.2 Update a skill's visibility — spec: api-reference.md §3 Skills CRUD

Ornn has three visibility tiers:

• Public — every Ornn user can see + pull this skill.
• Limited access — only specific orgs (every member of those orgs) and / or specific users can see + pull. Pick orgs only, users only, or both.
• Private — only you (and platform admins) can see + pull. New skills land here by default.

Step 1 — Check the current visibility.

nyxid proxy request ornn-api "/api/v1/skills/<idOrName>" \
  --method GET --output json

If data.isPrivate: false → currently public. If isPrivate: true and either share-list (sharedWithUsers / sharedWithOrgs) is non-empty → limited. If isPrivate: true and both lists empty → private.

Step 2 — Decide the target tier. Confirm with the user if it's not obvious from their request.

Step 3a — Set to public.

nyxid proxy request ornn-api "/api/v1/skills/<id>/permissions" \
  --method PUT \
  --data '{"isPrivate":false,"sharedWithUsers":[],"sharedWithOrgs":[]}' \
  --output json

Step 3b — Set to limited access. First fetch the candidate orgs and users:

# Orgs the caller belongs to
nyxid proxy request ornn-api "/api/v1/me/orgs" --method GET --output json

# Users searchable by email prefix (typeahead)
nyxid proxy request ornn-api "/api/v1/users/search?q=<email-prefix>&limit=20" \
  --method GET --output json

# Resolve known user_ids to email + display name
nyxid proxy request ornn-api "/api/v1/users/resolve?ids=<id1>,<id2>" \
  --method GET --output json

Pick which orgs / users to share with. If unclear, confirm with the user — never grant access to anyone the user didn't name. Then save:

nyxid proxy request ornn-api "/api/v1/skills/<id>/permissions" \
  --method PUT \
  --data '{"isPrivate":true,"sharedWithUsers":["user_abc"],"sharedWithOrgs":["org_xyz"]}' \
  --output json

Step 3c — Set to private.

nyxid proxy request ornn-api "/api/v1/skills/<id>/permissions" \
  --method PUT \
  --data '{"isPrivate":true,"sharedWithUsers":[],"sharedWithOrgs":[]}' \
  --output json

System-skill caveat. A skill bound to a NyxID admin service (isSystemSkill: true) cannot be set private — you'll get 400 SYSTEM_SKILL_MUST_BE_PUBLIC. Unbind it first via §2.9.

2.3 Publish a new version of an existing skill — spec: api-reference.md §3 Skills CRUD

Bump the version in SKILL.md frontmatter (e.g. 1.2 → 1.3), re-zip with the same root folder name, then PUT to the same skill id:

nyxid proxy request ornn-api "/api/v1/skills/<id>" \
  --method PUT \
  --data @my-skill.zip \
  --header "Content-Type: application/zip" \
  --output json

A new immutable version row is created; the latestVersion pointer advances. The response carries the updated SkillDetail with the new version. After this succeeds, also overwrite the local copy of the skill (the one in your skills dir) with the new content, and bump installedVersion + installedAt in ~/.ornn/installed-skills.json — your future executions need to match the new local copy.

2.4 Trigger a skill audit — spec: api-reference.md §4 Skill audit

An audit produces a risk verdict (green / yellow / red) for the skill's current version and fans out a notification on completion:

nyxid proxy request ornn-api "/api/v1/skills/<idOrName>/audit" \
  --method POST \
  --data '{"force":false}' \
  --output json

The response is the audit row at status: "running". Audits run server-side asynchronously — poll the history (§2.5) for the verdict. Pass "force": true to re-audit even if a recent verdict exists for the same bytes.

2.5 View a skill's audit history — spec: api-reference.md §4 Skill audit

nyxid proxy request ornn-api "/api/v1/skills/<idOrName>/audit/history" \
  --method GET --output json

Optional query: ?version=<X.Y> to narrow to one version. The response is { data: { items: [{ status, verdict, overallScore, scores, findings, completedAt, ... }, ...] } } newest-first. Each item is one audit run. Verdicts: green (safe), yellow (some findings), red (serious findings).

2.6 Pull and install a different version of a skill — spec: api-reference.md §3 Skills CRUD

Step 1 — List available versions.

nyxid proxy request ornn-api "/api/v1/skills/<idOrName>/versions" \
  --method GET --output json

Response: { data: { items: [{ version, skillHash, createdOn, isDeprecated, deprecationNote, releaseNotes, ... }, ...] } } newest-first.

Step 2 — Decide which version. Ask the user if it's not obvious. Then pull:

nyxid proxy request ornn-api \
  "/api/v1/skills/<idOrName>/json?version=<X.Y>" \
  --method GET --output json

Step 3 — Install locally + update the registry. You are encouraged to ask the user for consent before overwriting an existing local copy. If they say yes, write the new files over the old, bump installedVersion + installedAt in ~/.ornn/installed-skills.json. If the user picked this version specifically as a pin, also set isPinned: true on the record so future sessions don't auto-prompt to update.

2.7 Compare diff between two skill versions — spec: api-reference.md §3.7 Skills CRUD

When: the user (or you) want to know what changed between two published versions before pulling, upgrading, or generating a changelog.

nyxid proxy request ornn-api \
  "/api/v1/skills/<idOrName>/versions/<from-X.Y>/diff/<to-X.Y>" \
  --method GET --output json

Response shape:

{
  "data": {
    "skill": { "guid": "…", "name": "…" },
    "from":  { "version": "1.2", "hash": "…", "createdOn": "…", "isDeprecated": false, "releaseNotes": null },
    "to":    { "version": "1.3", "hash": "…", "createdOn": "…", "isDeprecated": false, "releaseNotes": null },
    "diff": {
      "files": {
        "added":   [{ "path": "scripts/new.js", "bytes": 1234, "isText": true, "content": "…" }],
        "removed": [{ "path": "old.txt",        "bytes":  120, "isText": true, "content": "…" }],
        "modified":[{ "path": "SKILL.md",       "fromBytes": 800, "toBytes": 920, "isText": true, "fromContent": "…", "toContent": "…" }],
        "unchangedCount": 7
      }
    }
  },
  "error": null
}