Competencies
A competency is the unit of capability in Hoziron. It gives an agent the ability to act — to understand a domain, follow specific procedures, use tools, or enforce constraints. Without competencies, an agent is just a bare LLM conversation. With them, it becomes a specialist.
Agents can equip multiple competencies simultaneously. Each competency contributes its system prompt, tools, and behavioral constraints — composed together by position order. This lets you build complex agents from focused, single-responsibility building blocks rather than monolithic definitions.
Competencies are declarative (defined in COMPETENCY.toml), portable (distributed as packages), and composable (ordered by position, prompts concatenated, tools unioned). They encapsulate system prompts, skill requirements, permissions, and configuration into a versioned, testable artifact.
What you'll find here
| Guide | Description |
|---|---|
| Using competencies | Install, equip, configure, and manage competencies on your agents |
| Authoring | Write your own competency: manifest format, system prompts, testing |
| Publishing | Package, sign, and distribute competencies through the catalog |
Common tasks
- Equip a competency to an existing agent → Using competencies § Equip a competency
- Equip multiple competencies → Using competencies § Equipping multiple competencies
- See which competencies an agent currently has → Using competencies § Listing equipped competencies
- Write a COMPETENCY.toml from scratch → Authoring § Minimal example
- Test a competency locally before publishing → Authoring § Testing locally
- Version and publish an update → Publishing § Version bumps
The competency model
A single competency bundles everything needed to perform a specific role. Multiple competencies compose on an agent — prompts concatenate in position order, tools union, permissions accumulate.
Multi-competency composition
- Position matters — earlier competencies get more prompt weight
- Tools union — the agent can use any tool from any equipped competency
- Permissions accumulate — the agent must satisfy all permissions from all competencies
Design principles
- Single responsibility — one competency, one domain. Compose multiple competencies for complex agents rather than building monolithic ones.
- Testable in isolation — every competency should be verifiable without a full platform deployment.
- Configuration over code — use the configuration schema to make competencies adaptable across environments without forking.
- Composable prompts — write system prompts that work alongside other competencies, not prompts that assume exclusive control.