Using Competencies

What you'll accomplish: Install competencies, understand how they attach to agents, and manage them once realised.

What is a competency?

A competency defines what an agent can do. It bundles a system prompt, required skills, permissions, and configuration settings into a single, self-contained package. Agents can carry multiple competencies — each adds domain expertise, tools, and behavioral instructions.

Install a competency

# From a local directory
hoziron-cli competency install ./my-competency/payload/

# From the catalog
hoziron-cli catalog search "claims"
hoziron-cli catalog install claims-intake

Installing puts the competency's definition into the CompetencyStore, ready to be referenced by an agent. It does not attach the competency to anything by itself.

Competencies attach to agents at agent install/hydrate — not via a runtime "equip" verb

There is no equip/unequip/reorder CLI command or API endpoint. A competency is realised into an agent, not equipped at runtime (ADR-044). Instead, a competency is declared in the agent's own package definition:

---
description: "..."
competencies:
  - claims-intake
  - client-facing-communication
  - pii-boundary
---

The list order in competencies: is the position order (earlier = more prompt weight). When the agent package is installed or upgraded, the platform realises every listed competency into it:

1. The competency's system prompt is folded into the agent's system prompt (position order, concatenated)
2. The competency's skills[] are attached to the agent's tool allowlist
3. A cron job is registered if the competency manifest declares a schedule
4. The competency's permissions[] are checked against what the agent grants — realisation fails the agent install/hydrate on any shortfall, it never silently skips a permission

To change which competencies an agent has, or their order: edit competencies: in AGENT.md, bump the package version, and reinstall (an upgrade, not a runtime call) — see Creating agents. A competency upgrade (new version of the competency package itself) automatically re-realises into every agent that declares it.

This is deliberate: an agent's configuration is always answerable from its definition version — "what competencies did this agent have when it made decision X" can't be mutated out from under a running agent by a live toggle.

Listing competencies

# All installed competency definitions
hoziron-cli competency list

# Which competencies a specific agent currently carries, in position order
curl http://localhost:4200/agents/{id}/competencies -H "Authorization: Bearer hzk_..."

Check dependencies

# See what skills are needed vs installed
hoziron-cli competency check-deps claims-intake

Configure settings

Competencies expose operator-tunable settings, scoped per agent×competency binding (the same competency equipped to two different agents can carry different setting values):

# View current values for a specific agent's binding of this competency
curl http://localhost:4200/agents/{agent-id}/competencies/{competency-id}/config \
  -H "Authorization: Bearer hzk_..."

# Update values (validated against the manifest's settings schema; rebuilds
# the agent's system prompt to reflect the new settings block)
curl -X PUT http://localhost:4200/agents/{agent-id}/competencies/{competency-id}/config \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer hzk_..." \
  -d '{"auto_escalate_threshold": "3"}'

hoziron-cli competency config <id> --set key=value targets /competencies/{id}/config, which returns 410 Gone — use the agent-scoped API endpoint above instead.

Schedule drift detection

Cron jobs registered from a competency's schedule field are real, live kernel cron jobs — an operator can independently pause or delete them without the platform's knowledge. To check for drift between what a competency's manifest declares and what's actually registered:

hoziron-cli competency check-schedules

# Reset one binding's schedule back to the manifest default
hoziron-cli competency reset-schedule --agent-id <agent-id> --competency-id <competency-id>

Multi-competency composition

When an agent has multiple competencies:

• System prompts are concatenated in position order (position 0 first — most prompt weight)
• Skills/tools are unioned — the agent can use any tool from any of its competencies. Duplicate tool names across competencies are rejected at realisation time (tool collision check)
• Permissions must all be satisfied — the agent must hold every permission required by every competency it declares
• Settings are scoped per competency binding — no conflicts between identically-named keys across different competencies

Per-invocation reordering is a separate, automatic mechanism

The static position order above is a floor, not the final word. For agents with 3+ competencies, a kernel-level Pre-Invocation Competency Manager (see the pre-invocation-competency-manager ADR) can dynamically reorder, reframe, or suppress competencies per invocation using a fast LLM call — invisible to the agent, logged as an audit event, and falls back to the static order on any failure. This only fires for non-scheduled, multi-competency invocations; it is not something you configure per call.

Lifecycle

Next steps

• Author your own competency
• Publish to the catalog
• Creating agents

Related:

• Competency authoring
• Publishing competencies
• Creating agents