Spawn subagents with personas from a local workspace library or the Emblem persona marketplace. Use when a task needs a different voice, expertise, or operating style; when the user says "use persona X", "spawn as Y", or "have a specific character do this"; when you need shared org context such as a foundation doc injected into every persona spawn; or when offloading a bounded task to a persona-preserving subagent is better than changing the current agent's own identity. Not for trivial tasks, changing your own persona in-place, or bypassing local subagent policy.
Use this skill to ensure the local persona library exists, assemble a deterministic persona prompt, and spawn a subagent without letting workspace persona files override the requested persona.
Keep personas in the current workspace:
<workspace>/personas/
├── config.json
├── index.json
├── the-mandalorian/
│ ├── SOUL.md
│ ├── IDENTITY.md
│ └── persona.json
└── <custom-persona>/
├── SOUL.md
├── IDENTITY.md
└── persona.json
personas/config.json is the shared org-context config. Put docs there that every persona spawn should inherit, such as Kru foundation rules, brand standards, or execution rules.
Read references/api-endpoints.md only when importing or validating marketplace data.
Read references/soul-guide.md only when authoring a new custom persona.
Before resolving personas, ensure the local library exists:
python3 <skill_dir>/scripts/ensure-personas.py <workspace> <skill_dir>
If the workspace has no local persona library yet, this bootstraps bundled starter personas and creates personas/config.json.
Create or edit:
{
"context_files": [
"../_System/Motoko-Kru-Foundation.md",
"../Resources/Coding-Subagent-Contract.md"
]
}
Rules:
context_files as either an array or a comma-separated string.personas/config.json.Before spawning, follow the current workspace policy.
If local AGENTS.md or system rules require asking before spawning subagents, ask first.
Do not use this skill to bypass local governance.
Run:
python3 <skill_dir>/scripts/ensure-personas.py <workspace> <skill_dir>
Then read <workspace>/personas/index.json.
Read:
<workspace>/personas/<handle>/SOUL.md<workspace>/personas/<handle>/IDENTITY.md<workspace>/personas/<handle>/persona.jsonIf the persona is not installed locally, import it first with the bundled importer.
Use the bundled builder:
python3 <skill_dir>/scripts/build-persona-prompt.py \
<workspace> \
<handle> \
--task-file <task.txt>
This assembles the prompt in this order:
personas/config.jsonThe override directive tells the spawned agent to ignore conflicting workspace-injected SOUL.md / IDENTITY.md for persona and tone, while still obeying higher-priority system, developer, safety, and governance instructions.
Use the normal OpenClaw subagent path with the assembled prompt. Preferred shape:
{
"task": "<assembled prompt>",
"runtime": "subagent",
"mode": "run",
"label": "persona:<handle>",
"runTimeoutSeconds": 300,
"cleanup": "delete"
}
Model guidance:
The subagent reports back automatically.
bash <skill_dir>/scripts/import-persona.sh <handle> <workspace>/personas
bash <skill_dir>/scripts/import-persona.sh --all <workspace>/personas
bash <skill_dir>/scripts/import-persona.sh --no-index <handle> <workspace>/personas
python3 <skill_dir>/scripts/rebuild-index.py <workspace>/personas
After adding, removing, or editing personas:
python3 <skill_dir>/scripts/rebuild-index.py <workspace>/personas
When deploying a persona into a live channel (CW room, Discord, Telegram group), use --channel:
python3 <skill_dir>/scripts/build-persona-prompt.py \
<workspace> \
<handle> \
--channel \
--task "You are in a chatroom. Respond to the conversation batch below."
This adds channel_context_files from personas/config.json between org context and persona soul:
{
"context_files": ["../governance.md"],
"channel_context_files": ["./channel-guardrails.md"]
}
Channel context files carry social behavior rules, safety guardrails, anti-spam norms, and liveliness guidance that apply to all personas in live channels — not persona-specific flavor.
The output expectations also change: instead of "complete the task fully", channel mode instructs the agent to behave as a natural chat participant.
context_files for shared org doctrine and execution standards.