elizaOS Character Builder

Turn a role description or existing character into a small, version-correct configuration. Personality text does not grant permissions; parsing does not prove an agent is operational.

1. Identify the contract

Read the project's AGENTS.md, manifest, lockfile, entry point, and installed @elizaos/core exports/types. Identify the destination: a core Character, a host configuration's narrower character subsection, or a published 1.x project with its own CLI and loader. Read contracts.

The researched source is a 2.x develop snapshot, not npm's latest release. Public tutorials still show older APIs. Prefer the target's installed types, schema and loader. Do not install a global CLI, upgrade packages or rewrite a loader merely to match this skill. Preserve existing IDs and unrelated work.

2. Design the persona

Infer role, audience, voice and boundaries from the request and code. Ask only about a missing decision that changes implementation. Read persona and evaluation. Start with the matching asset: core character or host subsection.

Use a short bio, useful topics, consistent style and examples for normal help, uncertainty, out-of-scope requests and actions requiring authorization. Examples illustrate behavior; they are not training runs or permission grants. Never invent real qualifications, customer facts, integrations or capabilities.

For current core TypeScript, use import type { Character } from '@elizaos/core' and satisfies Character against the installed package. Prefer the canonical bio: string[] and messageExamples: [{ examples: [...] }] form. Do not put plugins, settings or documents into a host character subsection just because those fields are valid in a core character.

3. Wire capabilities separately

Read capabilities and secrets. Reuse the host's existing, explicit composition of compatible storage, model and feature plugins. A package name in JSON does not install a dependency, register a model, ingest documents or grant connector access. Do not assume bootstrap/sql/model plugins are always implicit, or a generic settings.model selects a provider.

Keep credentials in approved host secret storage. Use names, not live values, in examples. Review document paths and sharing: current input normalization treats document strings as paths, not biography facts. Do not enable public connectors, scheduling, wallets, device access or autonomy as a side effect of persona authoring. Prompt rules are not a runtime authorization mechanism.

4. Validate in layers

Run from the installed skill directory, or use an absolute script path:

python3 scripts/check_character.py --input /path/to/character.json --target core
python3 scripts/check_character.py --input /path/to/host-character-subsection.json --target host

The helper reads JSON only, with no project-code imports, network or writes. It checks a conservative authoring subset and common credential field names. Exit 0 is preflight passed, 1 is authoring issues, 2 is unreadable/invalid JSON. It is not the elizaOS schema, a secret scanner, plugin resolution or a runtime test. Advanced content/templates/settings still need the installed authoritative schema. Review warnings even when exit 0 is returned.

Then run the project's typecheck and exact loader/schema validation. Current core validateCharacter(input) returns { success, data?, error? }, not .valid or .errors. parseCharacter(object) additionally normalizes; it does not load a filename. Do not print entire inputs or secret-bearing validation payloads. Importing arbitrary character.ts executes code; review it before execution.

5. Verify behavior and hand off

Use an isolated local agent and approved model/backend, with finite call/token budgets and no real outbound messages or wallet operations. Evaluate actual replies against the persona scenarios and authorization boundaries. A static fixture or desired answer is not live evidence. Report unavailable credentials, models and storage as untested, not passed.

Report target version/commit, character location, identity changes, plugin and environment names only, document sharing decisions, exact checks/outcomes, live versus static evidence and remaining prerequisites. Do not deploy or publish unless asked.

References

• Contracts and migration: read before choosing shapes or migrating.
• Persona and evaluation: read before designing voice and tests.
• Capabilities and secrets: read before wiring settings/documents/plugins.
• Pinned sources: official implementation and documentation differences.