Persona Agents, Workflows, and Skills

A field-engineer / solutions-engineer guide to choosing and combining Aiden OS’s three main building blocks when delivering outcomes for customers.

Audience: SEs and field engineers configuring Aiden OS via the console, API, Terraform modules, or app manifests.
Goal: know which building block to reach for, why, and how they work together.

New term? Short definitions also live in the Glossary.

Mental model

Building block	What it is at runtime	Owns	Does not own
Persona Agent	An LLM worker with an identity, a system prompt (`persona`), tools, and governance (HITL, policies, models)	Who acts, which tools they may use, always-on behavioral boundaries	Multi-step orchestration; shared how-tos across roles
Workflow	A versioned execution plan: stages + bindings (order / DAG), triggers, budgets	Order, handoffs, which agent runs which step, when the plan runs	Tool implementations; deep procedure text (use skills or runbooks)
Skill	A reusable procedure pack (`SKILL.md` + optional companion files), discoverable and loadable on demand	Step-by-step how-to, tool literacy, ordering, guardrails	Identity, governance, stage graph control

One-line summary

Agent = who and what they are allowed to do
Workflow = when and in what order
Skill = how to do a specific job well

Naming trap: “workflow skill”

Aiden OS’s semantic router sometimes labels a workflow as a “workflow skill,” meaning “a selectable execution plan.” That is not the same as a Skill (SKILL.md). In this guide:

Workflow = multi-stage plan
Skill = procedure document loaded via load_skill / found via search_skill

How they compose

Customer outcome
    │
    ├─ Needs repeatable steps / triggers / handoffs?
    │       → Workflow (stages + stage_bindings)
    │              │
    │              └─ Each stage hires a Persona Agent
    │                     (or runs a deterministic action_type)
    │
    ├─ Needs a durable specialist with tools + governance?
    │       → Persona Agent
    │              │
    │              └─ Skills listed on the agent = available procedures
    │
    └─ Needs a reusable how-to shared across agents/stages?
            → Skill
                   │
                   └─ Also pin via stage skill_refs when the step
                      must follow that procedure (not discovery luck)

When to use what

Start from the customer outcome, not from the UI form or module you open first.

Decision tree

Is the work a repeatable multi-step process (handoffs, gates, schedules, webhooks, DAG fan-out/fan-in)?
→ Build a Workflow. Each stage hires an agent (or a deterministic action).
Is the work open-ended conversation with one specialist (chat, Slack Q&A, ad-hoc help)?
→ Configure a Persona Agent. Attach skills for procedures they may need.
Is the same how-to needed in more than one place (multiple agents, multiple stages, or future workflows)?
→ Extract a Skill. Do not paste that procedure into every persona.
Is the step deterministic (policy check, webhook call, run another workflow, no-op)?
→ Use a workflow stage with action_type — not an LLM agent.

Concrete scenarios

Scenario	Use	Why
Slack bot answers ops questions with Grafana tools	Agent (+ skills)	One role, interactive turns, no fixed stage graph
Every new alert must be labeled before humans see it	Workflow hiring a narrow agent	Same steps every time; trigger-driven; fail closed without chat
“How to query Datadog logs for this tenant” reused by triage and deep-dive	Skill	One procedure, many callers; update once
After investigation, call a policy gate then a remediation workflow	Workflow stages with `action_type` + `workflow_ref`	Deterministic control flow, not prompt hope
Customer wants “one agent that does everything”	Prefer several agents + a workflow	Clear tool scopes, smaller personas, measurable stages

Persona Agents

What an agent is

An agent is Aiden OS’s core runtime worker. Registration requires at least:

name — stable identity (DNS-compatible)
persona — system prompt: role, expertise, behavioral guidelines

Typically you also set:

tools / integrations — what the agent can call
auto_approve_tools / auto_deny_tools — HITL shortcuts and hard blocks
model_names / model config — which models run the role
skills — skill names (or locations) this agent may load
description / tags — help semantic discovery and routing
Policies, knowledge, platforms, HITL — governance around the role

Agents run in interactive chat and as hired workers inside workflow stages. In this repo, agent modules (for example aios-agent-*) create and wire these via Terraform.

Best practices

Keep the persona as role + boundaries, not a novel.
Put always-on rules in the persona (what this role never does, what it must always do). Put long procedures in skills. A persona that duplicates a 2,000-line skill burns tokens on every turn and drifts out of sync.

Size tools to the role.
A first-pass classifier should only see classify/persist tools. An investigator may need observability integrations, memory, and spawn tools. Broad tool lists on a narrow role create accidental deep investigations and noisy HITL.

Auto-approve only what is safe and frequent for that role.
Read-only probes, load_skill / search_skill, and role-specific completion tools are common auto-approve candidates. Mutating tools should stay behind HITL or policy unless the customer explicitly wants hands-free remediation.

Attach skills for availability; do not assume they are already “in the brain.”
Listing a skill on an agent makes it discoverable/loadable for that agent. The full SKILL.md body is pulled when the agent calls load_skill (or when a workflow stage injects a load directive — see below).

Prefer focused agents over one mega-agent.
Split “classify” vs “investigate” (or “plan” vs “execute”) into separate agents and wire them with a workflow. Smaller personas are easier to govern, test, and explain to customers.

Fill description and tags when discovery matters.
If a stage omits agent_ref, Aiden OS can auto-resolve an agent by matching stage text to personas/descriptions. Non-interactive runs (schedule / webhook) should still set an explicit agent_ref — auto-resolve can fail closed when matches are missing or ambiguous.

Anti-patterns (agents)

Pasting an entire runbook into persona
One agent with every integration “just in case”
Relying on persona text alone for multi-step orchestration that needs durable handoffs
Leaving agent_ref empty on scheduled or webhook-driven stages

Skills

What a skill is

A skill is a reusable procedure document following the agentskills.io layout:

YAML front matter (name, description, …)
Markdown body with steps, tool choices, ordering, and guardrails
Optional companion files (scripts, references, assets)

Skills are stored, vectorized for search, and loaded on demand:

search_skill — find relevant skills by meaning
load_skill — pull the full procedure into the session
unload_skill — drop a loaded skill when switching procedures

Skills can come from git skill sources, manual create/update in the console/API, or app bundles (skills in an app manifest). Flagged skills (security scanner findings) cannot be loaded.

Best practices

One skill = one procedure.
Name it in lowercase kebab-case (grafana-alert-scoping, not Helper). Put a clear description in front matter — that text drives discoverability.

Write imperative, tool-literal steps.
Say which tool to call, in what order, what “done” looks like, and what to do when a plane is blind or a query returns empty. Vague advice (“investigate thoroughly”) belongs nowhere.

Attach on the agent for catalog access; pin on the stage when the step must follow it.

Attachment	Effect
Agent `skills: [...]`	This agent may search/load these skills during chat or stage work
Stage binding `skill_refs: [...]`	Runtime injects a prompt directive: call `load_skill` for each listed skill before starting; treat them as the authoritative procedure for that stage

Stage injection sends names and a load directive, not the full skill body — keeping the prompt small. The agent still calls load_skill.

Runbook beats skill when both are on a stage.
If a stage has runbook refs and skill refs, the attached runbook is the procedure of record. Skills fill gaps the runbook does not cover.

Prefer a skill over a new integration when the customer needs a how-to, not a new MCP surface. Prefer an integration when they need new tools/APIs.

Skills are not tools.
Never put skill names in create_agent tool_names. Skills are loaded with load_skill; tools are callable functions (MCP, built-ins). The platform will correct this mistake, but your designs should not rely on that.

Anti-patterns (skills)

One mega-skill that is really three procedures
Skill body that only restates the persona
Expecting agent-attached skills to auto-inject full text every turn without load_skill / skill_refs
Using a skill to implement control flow that belongs in a workflow DAG

Workflows

What a workflow is

A workflow is a versioned plan made of:

stages — discrete steps (stage_id, description, optional note)
stage_bindings — who runs each stage, dependencies, optional overrides

Each binding can:

Hire a primary agent via agent_ref
Run parallel_agents alongside the primary
Declare depends_on for DAG fan-out / fan-in (otherwise linear order of bindings)
Pin skill_refs / runbook_refs
Set action_type for deterministic stages (policy_check, evidence_gate, webhook, workflow_ref, noop, or tenant-registered actions)
Attach spawn_contracts for controlled create_agent delegation

Workflows also carry triggers, selection mode, knowledge-base scoping, output contracts, and runtime metadata (planner caps, middleware overrides).

How a stage differs from chat: a workflow stage is a bounded execution with injected stage context (description, note, skill/runbook directives), predecessor outputs, budgets, and a path to the next stage or completion. Chat is open-ended turns with one agent.

Best practices

One stage = one outcome.
“Classify the alert” and “Investigate root cause” are different stages (often different agents). Do not hide a pipeline inside one stage note.

Write stage description / note as operator expectations.
Expected outcome, why the step matters, hard constraints (“do not call memory tools”). Leave detailed how-to in skills.

Always set agent_ref for non-interactive runs.
Schedules, webhooks, and API-triggered pipelines should name the agent. Omitting agent_ref relies on persona auto-resolve, which can fail closed (no match) or fail ambiguous (multiple matches) outside interactive approval.

Use the DAG for real parallelism.
depends_on models fan-out/fan-in. parallel_agents runs additional agents in the same stage. Spawn contracts constrain how the primary may create sub-agents. Do not encode all of that as persona prose.

Pin skill_refs when discovery must not be left to chance.
If stage success depends on a specific procedure, list it in skill_refs. Do not hope search_skill finds the right document under time pressure.

Choose selection mode deliberately.

explicit — apps, APIs, and operators name the workflow (common for product pipelines)
auto (+ triggers / example queries) — intent routing should pick the plan from events or free text

Use action_type for gates and glue.
Policy checks, webhooks, and child workflow calls should not be “ask the LLM to remember to call X.”

Anti-patterns (workflows)

Single stage with a multi-thousand-token note that is really three skills
Workflow that is only a thin wrapper around chat with no stage outcomes
Missing agent_ref on automated triggers
Treating a workflow and a skill as interchangeable (“just make it a skill” when you need order, triggers, and handoffs)

Using them together

Recommended design order

Write the customer outcome in one sentence (“Every firing alert gets a criticality label within one minute”).
Sketch the workflow stages — each stage a verb + noun (“classify”, “investigate”, “remediate”).
Hire an agent per stage — match tool scope and persona boundaries to that stage’s outcome.
Extract shared procedures into skills — anything two agents/stages would otherwise copy-paste.
Wire attachments
- Agent skills = catalog of procedures that role may use
- Stage skill_refs = must-load list for that step
Govern — auto-approve / deny / policies sized per agent; keep mutating paths behind approval unless the customer opts in. See Writing Rego policies.
Validate with a real run (see checklist below). Prefer a demo scenario when one already matches the pitch.

Worked example (pattern, not a full product spec)

A common incident-response shape:

Piece	Role
Agent `…-classifier`	Narrow persona: label only; few tools; one classify skill
Workflow `…-classify-alert`	One stage bound to the classifier; triggered on ingest
Agent `…-investigator`	Broader persona: always-on gates; many observability skills; integrations
Workflow `…-investigate-alert`	One (or more) investigate stages; stage notes state expected RCA outcome; skills carry procedures
Skills	Platform how-tos (`…-observability-knowledge`), method packs (`…-investigation`), synthesis packs

What this gets you:

Classification stays cheap and constrained
Investigation can evolve via skills without rewriting the workflow graph
Field changes usually touch one layer (skill wording, agent tools, or stage binding) instead of all three

Runnable demos that illustrate this shape (among others) live under examples/scenarios/ — start from the SE playbook.

Anti-patterns checklist

Use this before a customer demo or production cutover.

Quick validation (field)

Agent

Open chat (or the customer’s channel) with the agent.
Confirm it only offers the intended tools.
Confirm HITL behavior: approved tools pass; denied tools block; everything else asks when HITL is on.
Ask it to search_skill / load_skill for an attached skill and confirm the body matches what you authored.

Skill

Confirm the skill appears in the tenant skill list and is not flagged.
From an agent that lists it, search_skill with a natural-language query related to the description — it should rank near the top.
load_skill and verify steps, tool names, and guardrails.
Edit the skill once and re-run — callers should pick up the new procedure without persona edits.

Workflow

Run the workflow with a representative input (manual run or test webhook).
Confirm each stage shows the expected agent_ref (or action_type).
If skill_refs are set, confirm the stage prompt/context directs the agent to load those skills before work.
Confirm handoff: predecessor output is available to the next stage; DAG stages wait on depends_on.
For non-interactive triggers, confirm a missing/ambiguous agent does not silently pick a random worker — fix bindings before go-live.

Cheat sheet

If you need…	Reach for…
A specialist the customer can talk to	Persona Agent
The same specialist every time an event fires	Workflow → stage → that Agent
A how-to shared across roles	Skill
A how-to that must run for a specific step	Stage `skill_refs` + Skill
Ordered steps, gates, child plans	Workflow (+ `action_type` when deterministic)
New APIs / vendor tools	Integration (not a skill)
Always-on “never do X” rules	Agent `persona`
Long “do X then Y then Z” procedures	Skill (or runbook)

Glossary — Agent, Workflow, Skill, Integration
SE playbook — prospect question → runnable scenario
Architecture — how modules layer foundation → integrations → agents
Writing Rego policies — governance around tools
Enterprise deployment profile — post-PoC rollout including skills sync
Skills sync — skill source + skillsync (apply does not upload card bodies)

Persona Agents, Workflows, and Skills

Mental model

Naming trap: “workflow skill”

How they compose

When to use what

Decision tree

Concrete scenarios

Persona Agents

What an agent is

Best practices

Anti-patterns (agents)

Skills

What a skill is

Best practices

Anti-patterns (skills)

Workflows

What a workflow is

Best practices

Anti-patterns (workflows)

Using them together

Recommended design order

Worked example (pattern, not a full product spec)

Anti-patterns checklist

Quick validation (field)

Agent

Skill

Workflow

Cheat sheet

Related