Skills
A skill is a reusable capability you can grant an agent — a packaged bundle of instructions and the tools that go with it. Skills are part of the agent definition: they install with the agent, they're allowlisted by name, and they carry provenance so a skill can't lie about where it came from.
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.
Skills published inside a Claude Code plugin
Many skills ship as one part of a Claude Code plugin, and their instructions hand work to the plugin's own
subagents ("launch the bug-hunter agent"). When a discovered skill sits at <plugin>/skills/<name>/SKILL.md
next to a <plugin>/.claude-plugin/plugin.json, the controller also captures the plugin's name and its
agents/*.md onto the Skill. When the skill is staged into a sandbox, Claude Code loads it as part of that
plugin, so the agents it names are actually there, under the <plugin>:<agent> names the plugin expects.
Only the plugin's name and its agent definitions travel. The plugin's hooks, MCP servers, commands, settings
and its other skills never do, and agent settings that would add hooks, MCP servers or a looser permission mode
are removed before staging, so a plugin can't reach past the sandbox's tool controls. Set
disablePluginAgents: true on the source to stage every skill on its own instead.
A plugin captures at most 64 agents (256 KiB in total); past either limit the controller keeps the first ones by
name and reports the rest on the source's status. If two skills enabled for the same agent name the same plugin
but carry different agents — two unrelated sources that both called their plugin review, say — neither gets
the other's agents: both are staged on their own, without any.
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.