Skills

What a skill is

Rather than copy the same instructions and tool wiring into every agent that needs them, you factor them into a skill and grant it. An AgentClass names the skills it's allowed to use; at run time the agent can draw on exactly those, and no others. Because a skill is part of the definition, it rides along when the agent is packaged as a bundle — you don't wire it up again at each install.

Progressive disclosure

An agent doesn't carry every skill's full instructions in its context. Each granted skill contributes only a short description — a sentence or two — that's always present. When the agent judges a skill relevant, it pulls the full body on demand with a load_skill call. So you can grant many skills without drowning the prompt: the names and descriptions are cheap, and the detail is loaded only when it's needed. (A loaded skill body is treated as untrusted content, like any tool output.)

Where skills come from

Skills are materialized from a SkillSource (namespaced) or ClusterSkillSource (cluster-wide) — a declared, git-backed origin. You register one with oap skill source create <name> --repo <url> --ref <tag>; the controller clones the repo, finds every SKILL.md under it, and materializes one Skill per capability. The agent never gets a skill from a hand-edited blob.

Provenance: a skill can't claim an origin it doesn't have

A skill's name encodes its authority — the source it came from — and the controller enforces that binding. A skill claiming to come from a trusted origin must be backed by an actual SkillSource whose repository normalizes to that same authority. You can't hand the cluster a skill with a forged "from a trusted org" label and an attacker-supplied body; the name and the source have to agree, and the check fails closed if they don't.