Competency System Internals

How competencies are installed, equipped, and enforced at runtime — including skill dependency validation, permission checks, tool filtering, and system prompt composition.

Object Relationships

Key constraint: Multiple competencies per agent with operator-controlled ordering. Tool collision detection prevents two competencies from providing the same tool name. The system prompt is built by concatenating each competency's prompt in position order with --- Competency: {id} --- separators.

Equip Operation

Equipping a competency is the central action that configures an agent's runtime behavior. It's a multi-phase, all-or-nothing operation:

Phase 1: Skill Dependency Validation

The competency's required_skills list is checked against the installed skill registry:

# COMPETENCY.toml
required_skills = ["document-ocr", "postgresql-connector", "email-skill"]

Each required skill must be installed. If any are missing, the equip fails with a comprehensive error listing all missing skills (not just the first one).

Phase 2: Permission Validation

The competency's required_permissions are matched against the agent's declared permissions:

# COMPETENCY.toml
required_permissions = ["database:read", "database:write", "api:claimcenter:write"]

Matching is done by exact equality — for pattern-based permissions (FileRead, NetworkConnect, etc.) the pattern string must match exactly. If any required permission is absent from the agent's permission set, the equip fails with an enumeration of all missing permissions.

Kernel Manifest Updates

On successful validation, three changes are applied to the agent's kernel manifest:

  1. Skills — the agent's skills field is set to the competency's required_skills
  2. Tool allowlist — all tools provided by the required skills are collected and set as the agent's tool_allowlist. The agent can only invoke these tools.
  3. System prompt — the competency's agent system prompt is appended to the agent's existing prompt (separated by \n\n)

Unequip Operation

Unequipping reverses the equip:

  1. Clears the agent's tool_allowlist (empty = no tool access)
  2. Clears the agent's skills list
  3. Removes the competency's system prompt from the agent
  4. Deactivates the competency instance in the registry
  5. Clears the equipped_competency reference in agent metadata

Tool Allowlist Resolution at Runtime

The tool allowlist is not just set at equip time — it's re-resolved at every message execution:

This means if you install a new version of a skill that adds tools, the agent sees them on the next message without re-equipping.

Competency Manifest Structure

id = "claims-intake"
name = "Claims Intake"
description = "FNOL processing"
category = "Insurance"
required_skills = ["document-ocr", "postgresql-connector"]
required_permissions = ["database:read", "database:write"]
schedule = "0 */6 * * *"
integrations = ["guidewire-claimcenter"]

[agent]
name = "claims-intake-agent"
description = "Processes first notice of loss"
system_prompt = "You are a claims intake specialist..."

[[settings]]
key = "auto_escalate_threshold"
label = "Auto-Escalate Severity"
setting_type = "Select"
default = "4"

[[metrics]]
label = "Claims Processed"
memory_key = "claims_processed_count"
format = "number"

Categories

The category field determines classification in the catalog. Valid values: Insurance, Security, Productivity, Development, Communication, Data, Finance, Research, Operations, Other

Settings at Runtime

Settings are operator-configurable parameters exposed via CLI and API:

  • Select — choose from predefined options
  • Text — free-text input
  • Toggle — boolean on/off

Agents access their competency's current settings through the memory system (settings are injected as memory KV entries).

Skill ↔ Tool Relationship

Each skill provides one or more tools (must have at least 1 — validated at install time). The skill's manifest declares:

  • Tool name
  • Tool description
  • JSON schema for input parameters
  • Runtime type (Python, WASM, Node, Shell, Native)

Competency Status Lifecycle

  • Installed — competency is registered but not active
  • Active — competency is equipped to an agent and processing
  • Paused — temporarily stopped (agent continues to exist)