Operational skills workflow

ModusBrain operational skills follow a structured, five-phase lifecycle. This workflow ensures that agent actions are safe, conformant to policies, and fully auditable. The following guide walks through a real-world refund handling scenario to demonstrate how agents and operators interact with these phases.

Phase 1 — Compile

The compilation phase reads your unstructured company documentation—such as markdown wikis, support policies, and ticketing procedures—and compiles them into a versioned, static draft skill.

# Optional: Ingest the raw markdown policy document into the brain first
modusbrain capture --file ./docs/refund-policy.md

# Compile the policy into a versioned draft skill runbook
modusbrain opskill compile "refund handling" \
  --risk-tier high_stakes \
  --owner support-lead

Every compiled operational skill version captures three core layers:

Prose Judgment — Semantic, context-aware guidelines extracted from natural language text to steer agent behavior in complex scenarios.
Structured Policy Rules — Executable logic constraints (e.g. if amount < 500 => auto_approve) parsed from documentation to enforce strict boundaries.
Lineage and Provenance — A secure mapping back to the source files, compiler identity, and timestamps.

Phase 2 — Approve

When an operational skill is newly compiled, it is held in a draft status. Active agents are restricted from executing draft skills until an owner promotes them:

# Display the details and version history of the compiled skill
modusbrain opskill show refund-handling

# Approve the draft version, making it the active version for runtime execution
modusbrain opskill approve refund-handling --by alice@company.com

Approval Tokens

For high-stakes tasks that fall below the automatic confidence threshold, operators can issue a temporary 1-hour approval token to safely override the gate:

modusbrain opskill approve-token refund-handling

Phase 3 — Execute (with Gating)

During agent runtime, the agent requests the execution of an active operational skill. ModusBrain evaluates the request against the active policy parameters and calculates a confidence score:

modusbrain opskill execute refund-handling \
  --task "Process $300 refund for order #4521" \
  --context '{"amount":300}'

The execution query is allowed or blocked based on its risk tier threshold:

Risk Tier	Confidence Threshold	Action if Below Threshold
`informational`	0.50	Warnings are logged for analysis, and execution is permitted to proceed.
`low_stakes`	0.70	Execution is blocked unless a force flag is set.
`high_stakes`	0.85	Hard-blocked; execution is refused unless a valid human approval token is provided.

Phase 4 — Audit

ModusBrain logs all execution attempts and outcomes to a secure, queryable audit ledger. This allows organizations to monitor compliance and debug agent decisions:

modusbrain opskill audit --slug refund-handling --json

Audit entries record the executing agent’s identifier, the specific skill version used, calculated confidence scores, parameters evaluated, and the final output.

Phase 5 — Feedback Loop

If an agent action is incorrect or needs refinement, operators submit corrections. This writes feedback files back to the database, which influences subsequent skill compilations:

modusbrain opskill correct refund-handling \
  --original "auto_approve" \
  --correction "Amounts over $400 require manager sign-off" \
  --by bob@company.com

Conflict Handling

If multiple source documents contain contradicting instructions, ModusBrain flags the conflict in the review queue to prevent execution issues:

# Flag a conflict manually for owner review
modusbrain opskill flag-conflict refund-handling \
  --description "Policy docs disagree on the $500 threshold" \
  --sources wiki/policies/refund-policy,wiki/policies/old-refund

# Resolve the conflict and trigger automatic re-compilation of a new draft
modusbrain opskill resolve 1 --by alice@company.com --note "Use the newer $400 threshold"

Product Overview

Use Cases

Developer Platform