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.
An agent can declare multiple competencies. Each competency contributes its system prompt, tools, and behavioral constraints — composed together by position order at the agent's own install/hydrate time. This lets you build complex agents from focused, single-responsibility building blocks rather than monolithic definitions.
Competencies are declarative (defined in COMPETENCY.md), 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. Attaching a competency to an agent is definition-driven, not a runtime toggle — the agent's AGENT.md frontmatter lists the competencies it wants, and they're realised into it (prompt folded in, skills attached, cron registered, permissions checked) when the agent package is installed or upgraded. See Using competencies for the full model.
What you'll find here
| Guide | Description |
|---|---|
| Using competencies | Install competency definitions, declare them on an agent, configure, and manage them |
| Authoring | Write your own competency: manifest format, system prompts, testing |
| Publishing | Package and distribute competencies through the catalog |
Common tasks
- Attach a competency to an agent → Using competencies § Competencies attach to agents at agent install/hydrate
- Understand multi-competency ordering → Using competencies § Multi-competency composition
- See which competencies an agent currently has → Using competencies § Listing competencies
- Write a COMPETENCY.md from scratch → Authoring § Minimal example
- Test a competency locally before publishing → Authoring § Testing locally
- Publish a competency to the catalog → Publishing
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 — all resolved when the agent's package is installed or upgraded.
Multi-competency composition
- Position matters — the order competencies are listed in
AGENT.md; earlier gets more prompt weight - Tools union — the agent can use any tool from any of its competencies
- Permissions accumulate — the agent must satisfy all permissions from all competencies, checked at realisation time (agent install/hydrate fails on a shortfall)
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.