Persona Spawn

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.

Files

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.

First use

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.

Shared org context config

Create or edit:

{
  "context_files": [
    "../_System/Motoko-Kru-Foundation.md",
    "../Resources/Coding-Subagent-Contract.md"
  ]
}

Rules:

• Accept context_files as either an array or a comma-separated string.
• Resolve relative paths from personas/config.json.
• Use shared context for durable org rules, not persona-specific flavor.

Workflow

1. Respect local policy first

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.

2. Ensure local personas exist

Run:

python3 <skill_dir>/scripts/ensure-personas.py <workspace> <skill_dir>

Then read <workspace>/personas/index.json.

3. Resolve the persona

Read:

• <workspace>/personas/<handle>/SOUL.md
• <workspace>/personas/<handle>/IDENTITY.md
• <workspace>/personas/<handle>/persona.json

If the persona is not installed locally, import it first with the bundled importer.

4. Build the persona prompt deterministically

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:

1. Override directive
2. Org context files from personas/config.json
3. Persona SOUL.md
4. Persona IDENTITY.md
5. Task

The 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.

5. Spawn the subagent

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:

• Use the caller's default model unless the user requests another one.
• Use a fast model for writing, brainstorming, or stylistic tasks.
• Use a stronger model for analysis, security review, or planning.

6. Return the result

The subagent reports back automatically.

• If the user asked for the persona's voice, preserve it.
• Otherwise summarize in your own voice and mention which persona was used.

Import personas

Import one

bash <skill_dir>/scripts/import-persona.sh <handle> <workspace>/personas

Import all

bash <skill_dir>/scripts/import-persona.sh --all <workspace>/personas

Batch without rebuilding every time

bash <skill_dir>/scripts/import-persona.sh --no-index <handle> <workspace>/personas
python3 <skill_dir>/scripts/rebuild-index.py <workspace>/personas

Rebuild the local index manually

After adding, removing, or editing personas:

python3 <skill_dir>/scripts/rebuild-index.py <workspace>/personas

Guardrails

• Do not change your own persona in-place. Spawn another agent instead.
• Do not spawn for trivial one-liners.
• Do not mix multiple personas in one subagent.
• Do not add tone instructions that conflict with the persona.
• Prefer local personas after import.
• Prefer context_files for shared org doctrine and execution standards.
• If import fails, report the failure cleanly and suggest nearby installed personas when possible.