Skip to main content
Sub-agents live in your harness’s native format - a Markdown file per role, with YAML frontmatter describing it and a body that is its system prompt. Karta discovers those files; you do not redeclare them anywhere else.

​
The format

.claude/agents/billing.md

​
Frontmatter fields

​
name
string
required
The sub-agent’s identifier. This is the key you route to (app.agents["billing-specialist"], agent="billing-specialist").
​
description
string
A short summary of what the sub-agent does. Used for routing and display.
​
model
string
Optional model override for this sub-agent (e.g. claude-sonnet-4-6). Falls back to the harness/platform default if omitted.
​
temperature
number
Optional sampling temperature.
​
tools
object
Optional map of tool name -> enabled. Controls which tools this sub-agent may use.
​
permissions
object
Optional permission rules - for example, allowing or denying specific skills with permissions.skill.
​
type
string
default:"primary"
primary or auxiliary. Karta preserves this metadata for the harness and routing UI.
The body (everything after the frontmatter) is the sub-agent’s prompt.

​
Single vs. multiple sub-agents

  • One sub-agent -> it is selected automatically; app.default_agent is it.
  • Multiple sub-agents -> route explicitly by name, or set a default. For OpenCode, the default is declared in .opencode/opencode.jsonc as "default_agent": "name". If Karta cannot resolve a default, startup fails with a configuration error instead of guessing.

​
Handing off between sub-agents

Routing chooses a sub-agent per message; handoff changes the current sub-agent for the rest of a session:

Skills

Reusable capabilities agents can invoke.

Sub-agents

Routing, handoff, and runtime authority.