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:
- The directory specified by
OMICOS_TEMPLATES_DIR <workspace>/config/agents/(if it exists)- The cloud cache
~/.omicos/cloud-agents/agents/— this is the path real users go through - 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
.mdoverrides the cloud version, handy for iterating on a prompt temporarily. - For
community/plus/prousers, 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 clifor 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):
- The directories listed in
OMICOS_SKILL_ROOTS(colon- / semicolon-separated) (Plus+) - The cloud cache
~/.omicos/cloud-skills/skills/ <workspace>/skills/(Plus+)<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_skillsPython package, and the cross-project user-level~/.omicos/skills/. Skills now come from exactly two sources — the cloud catalog, or the workspace.~/.omicosonly 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=1disables 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.