Using Competencies
What you'll accomplish: Install, equip, configure, and manage competencies on your agents.
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 equip multiple competencies — each adds domain expertise, tools, and behavioral instructions.
Install a competency
# From a local directory
hoziron competency install ./my-competency/
# From the catalog
hoziron catalog search "claims"
hoziron catalog install claims-intake
Equip a competency
hoziron competency equip claims-intake --agent my-agent
Equip:
- Validates that all required skills are installed
- Checks that the agent holds the required permissions — rejects if not
- Injects the competency's system prompt into the agent
- Adds the competency's skills to the agent's tool allowlist
Equipping multiple competencies
Agents can equip multiple competencies. Each adds its system prompt and tools:
hoziron competency equip policy-lookup --agent my-agent
hoziron competency equip claims-intake --agent my-agent
hoziron competency equip compliance-check --agent my-agent
Competencies are ordered by position — earlier equipped = more prompt weight. System prompts are concatenated in position order. Skills/tools are unioned across all equipped competencies.
Reordering competencies
# Move a competency to a specific position (1-indexed)
hoziron competency reorder claims-intake --agent my-agent --position 1
Unequipping
hoziron competency unequip claims-intake --agent my-agent
Listing equipped competencies
# See all competencies on an agent (in position order)
hoziron competency list --agent my-agent
Check dependencies
# See what skills are needed vs installed
hoziron competency check-deps claims-intake
# Auto-install missing skills
hoziron competency install-deps claims-intake
Configure settings
Competencies expose operator-tunable settings:
# View all settings
hoziron competency config claims-intake --list
# Change a setting
hoziron competency config claims-intake --set auto_escalate_threshold=3
# Get a specific value
hoziron competency config claims-intake --get require_clue_report
Lifecycle
| Command | Description |
|---|---|
competency install <path> | Install from local directory |
competency list | List all installed competencies |
competency list --agent <id> | List competencies equipped to an agent |
competency equip <id> --agent <id> | Equip a competency to an agent |
competency unequip <id> --agent <id> | Remove a competency from an agent |
competency reorder <id> --agent <id> --position <n> | Change position order |
competency check-deps <id> | Check skill dependencies |
competency install-deps <id> | Install missing skill dependencies |
competency config <id> --list | View settings |
competency config <id> --set key=value | Change a setting |
competency info <id> | Show detailed information |
How multi-competency composition works
When an agent has multiple competencies equipped:
- System prompts are concatenated in position order (position 1 first)
- Skills/tools are unioned — the agent gets access to all tools from all equipped competencies
- Permissions must all be satisfied — the agent must hold every permission required by every equipped competency
- Settings are scoped per competency — no conflicts between identically-named keys
Next steps
Related: