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.

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

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