13. Advanced (2): Agents / Skills / Memory

Official agents and skills sync from the cloud catalog. You can add your own skills on Plus and above, and your own agent templates on Lab and above, in the conversation workspace.

13.1 Subscription Tiers

omicOS layers its features by subscription tier, compared internally with a rank value:

Tier rank
community 0
plus 1
pro 2
lab 3
enterprise 4

The following tiers unlock workspace and agent features.

  • rank ≥ 2 (pro): can open the Agent2Agent endpoint (see Chapter 9).
  • Plus and above includes custom skills.
  • Lab and above includes custom agents.

Core verifies the signed subscription token. If the panel asks for fresh credentials, reconnect the account and rescan.

13.2 Agent Templates

An Agent is an assistant with a specific role, toolset, and system prompt. The template format is YAML frontmatter + a Markdown body:

---
id: my_lab_qc
name: My Lab QC
description: Lab-specific QC agent
tier: lab
toolsets:
  - python_interpreter
  - file_manager
  - omicverse_lookup
skills:
  - qc_basic
---

You are a QC specialist...
(the rest of this is the full system prompt body)

Common fields: id, name, description, toolsets, instructions, tier, skills, category, use_when, example_prompts.

Where Agents Are Loaded From

The base roster is taken from the first usable directory, in this priority order:

  1. The directory specified by OMICOS_TEMPLATES_DIR
  2. <workspace>/config/agents/ (if it exists)
  3. The cloud cache ~/.omicos/cloud-agents/agents/ — this is the path real users go through
  4. The fallback <workspace>/.omicos/ (usually empty — in that case it degrades to a placeholder default agent, so a configuration problem is exposed rather than silently swallowed)

On top of that, lab tier and above users can layer a workspace override: <workspace>/agents/ (or the legacy location <workspace>/.omicos/agents/).

Rules for How Local Overrides Take Effect

  • New id → appended to the end of the roster (adds a new agent).
  • Same id → the local .md overrides the cloud version, handy for iterating on a prompt temporarily.
  • For community / plus / pro users, even a file that exists is silently ignored — the cloud catalog is the only source.
  • After editing a file, you must restart omicos serve / omicos cli for it to take effect; the web app's "refresh" only re-pulls cloud content, it doesn't re-read local files.

An Agent's Skill Allowlist Semantics

An agent's skills field controls which skills it can see:

  • Empty / omitted = all skills visible (backward compatible — this does not hide everything).
  • ["*"] = explicit wildcard, all visible.
  • A named list = only the listed skills are visible.
  • Agents can use workspace skills that the account is entitled to load.

13.3 Skills

Use a custom skill in your workspace

A Skill is a reusable unit of capability. The root directories where skills are discovered, in priority order (earlier wins on a name collision):

  1. The directories listed in OMICOS_SKILL_ROOTS (colon- / semicolon-separated) (Plus+)
  2. The cloud cache ~/.omicos/cloud-skills/skills/
  3. <workspace>/skills/ (Plus+)
  4. <workspace>/.omicos/skills/ (Plus+, legacy location)

Directories that don't exist are silently skipped.

Two sources that used to exist have since been removed: the skill directory bundled with the kernel environment's omicverse_skills Python package, and the cross-project user-level ~/.omicos/skills/. Skills now come from exactly two sources — the cloud catalog, or the workspace. ~/.omicos only holds the cloud cache now.

Cloud sync does hash comparison and cleanup, and carries the subscription token for tier filtering. OMICOS_SKILLS_OFFLINE=1 disables sync and uses the local cache only.

13.4 Memory (Long-Term Memory)

Memory lets an agent remember things across conversations. It's just a set of plain .md files under ~/.omicos/memory/ (no frontmatter needed; the title is taken from the first non-empty line), synced to the cloud by process token.

ls ~/.omicos/memory

Expected output:

project-conventions.md    rnaseq-pipeline-notes.md
  • Tools: memory__list / memory__view / memory__create / memory__edit / memory__delete.
  • Slug naming rules: [a-zA-Z0-9_-], length 1–64; body capped at 64 KiB.
  • Write policy: local write first, cloud sync best-effort. OMICOS_MEMORY_OFFLINE=1 disables cloud sync.
  • The storage location can be changed with OMICOS_MEMORY_CACHE_DIR — note that's where the memory files themselves live, not a separate copy.

13.5 Sync Cadence

Content Variable Default Description
Agent / skill / model catalog OMICOS_CATALOG_SYNC_SECS 600 seconds Values below 30 are not clamped to 30 — they're discarded and fall back to 600
Memory OMICOS_MEMORY_SYNC_SECS 3600 seconds Memory normally syncs instantly via cloud push; this interval is just a fallback poll. Values below 60 are likewise discarded and fall back to the default

Cloud content changes push proactively, so editing an agent / skill in the admin panel doesn't require restarting a running omicos to pick it up.

13.6 Workspace-Extension Gating, Summarized

Capability Who can use it
Use cloud agents / skills All users (filtered by subscription tier)
Workspace custom skills Plus, Pro, Lab, Enterprise
Workspace custom agents Lab, Enterprise
Use / write memory All users
Open the Agent2Agent endpoint pro and above (rank ≥ 2)

If you're on community / plus / pro and find that a local agent you dropped in doesn't take effect, that's expected — workspace custom agents require lab tier.

results matching ""

    No results matching ""