Every AI Tool Has Its Own Config Format
Claude Code has CLAUDE.md. Cursor has .cursor/rules. Codex has AGENTS.md. Gemini CLI has GEMINI.md.
Each tool invented its own way to tell an AI agent who to be and how to behave. Your carefully crafted instructions? Locked to one tool. Switch tools, start over.
We think agent identity should be portable.
Introducing Persona Protocol
Today we're publishing Persona Protocol — an open specification for persona.json, a manifest format that defines everything about an AI agent's identity in a single, portable file.
{
"$schema": "https://aiiware.com/schema/persona.v0.1.json",
"specVersion": "0.1",
"name": "aiiware/full-stack-engineer",
"version": "0.1.0",
"description": "Senior full-stack engineer with TDD methodology",
"author": { "name": "AiiWare" },
"instructions": "Use TypeScript strict mode. Write tests first. Prefer composition over inheritance.",
"soul": { "name": "engineer", "path": "./souls/engineer/" },
"skills": ["code-review", "tdd", "debugging"],
"hooks": {
"PreToolUse": [{ "matcher": "Write", "command": "./scripts/lint.sh" }]
},
"theme": "engineer-dark",
"agents": {
"aii": ">=0.14.6"
}
}One file. Installs anywhere. Carries everything.
Three Tiers of Complexity
Not every persona needs a full behavioral package. Persona Protocol supports three tiers — use only what you need.
Minimal — A String
For quick, project-scoped behavior:
{
"name": "quick-reviewer",
"version": "0.1.0",
"description": "Fast code review",
"author": { "name": "You" },
"instructions": "Review for bugs and security issues. Be concise."
}Five fields. No files. No dependencies. This is the lowest barrier to entry — if you can write a sentence, you can create a persona.
Lightweight — Structured Instructions
When you need more than a string but less than a full soul:
{
"specVersion": "0.1",
"name": "aiiware/reviewer",
"version": "0.1.0",
"description": "Structured code reviewer",
"author": { "name": "AiiWare" },
"instructions": {
"identity": "You are a senior code reviewer at a fintech company.",
"style": "Constructive, severity-based. Lead with what's done well.",
"workflow": "1. Read entire diff. 2. Identify patterns. 3. Severity-rank issues. 4. Write actionable feedback."
}
}Structured instructions render as semantic XML in the prompt — <identity>, <style>, <workflow> — giving the model clear separation between who it is, how it communicates, and what process it follows.
Full — Soul, Skills, Hooks, Theme
The complete package for teams and published personas:
{
"specVersion": "0.1",
"name": "aiiware/full-stack-engineer",
"version": "0.1.0",
"description": "Senior full-stack engineer persona",
"author": { "name": "AiiWare", "url": "https://aiiware.com" },
"soul": { "name": "engineer", "path": "./souls/engineer/" },
"skills": ["code-review", "tdd", "api-design"],
"hooks": {
"PreToolUse": [{ "matcher": "Write", "command": "./scripts/lint.sh" }]
},
"instructions": "TypeScript strict. TDD. Composition over inheritance.",
"theme": "engineer-dark",
"agents": { "aii": ">=0.14.6" },
"model": {
"providers": ["anthropic", "openai"],
"recommended": "claude-sonnet-4",
"minimumTier": "mid"
}
}The soul carries personality through SoulSpec files — identity, style, heartbeat, workflow, and calibration examples. Skills define methodology. Hooks enforce quality gates. The whole package installs with one command.
Designed for Portability
The agents field declares which tools a persona is tested against:
"agents": {
"aii": ">=0.14.6",
"other-tool": ">=1.0.0"
}Each entry is a canonical tool ID with a semver range. The format is intentionally simple — any tool can read persona.json and extract the instructions field, even without full protocol support. Graceful degradation is built into the design.
The model field specifies LLM requirements:
"model": {
"providers": ["anthropic", "openai"],
"recommended": "claude-sonnet-4",
"minimumTier": "mid"
}A persona designed for a large model won't silently fail on a small one. The tool can warn, suggest alternatives, or block activation.
Vendor Extensions
Persona Protocol is intentionally extensible. Any field prefixed with x-<vendor>- is reserved for tool-specific data:
{
"name": "my/persona",
"version": "0.1.0",
"description": "My persona",
"author": { "name": "Me" },
"instructions": "Be helpful.",
"x-aii-telemetry": { "trackUsage": true },
"x-acme-config": { "customSetting": true }
}Your data, your namespace. Other tools ignore what they don't recognize. No schema conflicts.
The Team Onboarding Problem
When a new engineer joins your team, they need to:
- Install the right skills manually
- Configure MCP servers for the team's infrastructure
- Set up hooks for quality standards
- Find the right soul for the project's communication style
- Read and internalize the team's conventions
This takes hours. Most engineers end up with incomplete, inconsistent configurations. Same prompt, different responses across the team.
With Persona Protocol, onboarding is one command:
git clone [email protected]:your-org/your-project.git
cd your-project
aii persona use your-org/full-stack-engineerThe new engineer gets the team's soul, skills, hooks, instructions, and theme — all in one package. Same configuration as everyone else. Consistent AI output from day one.
A persona published by the engineering manager becomes the team standard. Commit it to git. Every engineer who clones the repo gets the same setup. No wiki. No manual steps. No drift.
We Eat Our Own Dogfood
Starting with Aii CLI v0.14.6, our own built-in identities — Thinker, Doer, Coder — are persona packages. Not special-cased internals. Not legacy configurations. Actual persona.json manifests using the same format we offer to users.
aii persona listName Version Skills Soul Status
──────────────────────────────── ─────── ────── ────── ──────
[BUILT-IN]
aiiware/thinker 0.1.0 0 v0.4 —
aiiware/doer 0.1.0 0 v0.4 —
aiiware/coder 0.1.0 0 v0.4 —
[INSTALLED]
aiiware/code-reviewer 0.1.1 2 yes —
aiiware/full-stack-engineer 0.1.1 3 yes ACTIVE
aiiware/mentor 0.1.1 3 yes —Built-in and installed, side by side. Same format. If the format is good enough for our own product, it's good enough to standardize.
JSON Schema Published
The schema is published and versioned:
https://aiiware.com/schema/persona.v0.1.jsonAdd it to your persona.json for instant validation in any editor:
{
"$schema": "https://aiiware.com/schema/persona.v0.1.json",
"specVersion": "0.1",
"name": "my/persona",
...
}VS Code, JetBrains, and any JSON Schema-aware editor will give you autocomplete, type checking, and inline documentation.
Get Started
Create a persona in 30 seconds:
mkdir my-persona && cd my-persona
cat > persona.json << 'EOF'
{
"$schema": "https://aiiware.com/schema/persona.v0.1.json",
"name": "yourname/my-persona",
"version": "0.1.0",
"description": "My custom AI persona",
"author": { "name": "Your Name" },
"instructions": "Your rules here."
}
EOF
aii persona install ./my-persona
aii persona use yourname/my-personaOr try a built-in:
npm install -g @aiiware/aii
aii persona use aiiware/doerThe schema is at aiiware.com/schema/persona.v0.1.json. The reference implementation ships with Aii CLI v0.14.6.
One file. Portable identity. Open standard.