Claude Octopus ships with 33 built-in personas covering software engineering, research, strategy, and specialized development. You can create custom personas or distribute them as persona packs to tailor agents to your team’s specific needs.
Persona anatomy
Each persona is defined in a markdown file with YAML frontmatter. Here’s the structure:
---
name: typescript-pro
description: Master TypeScript with advanced types, generics, and strict type safety.
model: opus
memory: local
when_to_use: |
- Advanced TypeScript type definitions
- Generic types and utility type creation
avoid_if: |
- Python work (use python-pro)
- Frontend component logic (use frontend-developer)
examples:
- prompt: "Create type-safe API client"
outcome: "Generic request/response types, error handling"
---
You are a TypeScript expert specializing in advanced typing...
## Focus Areas
- Advanced type systems (generics, conditional types, mapped types)
- Strict TypeScript configuration
## Approach
1. Leverage strict type checking
2. Use generics and utility types
Frontmatter fields
| Field | Required | Description |
|---|
name | Yes | Unique identifier (kebab-case) |
description | Yes | One-line summary of the persona’s expertise |
model | Yes | Model selection: opus, sonnet, haiku, or inherit |
memory | No | Memory mode: local, project, or global |
when_to_use | No | Situations where this persona excels |
avoid_if | No | When NOT to use this persona |
examples | No | Example prompts and expected outcomes |
tools | No | Allowed tools (defaults to all) |
hooks | No | Custom hook configurations |
Model selection
The model field determines which Claude model the persona uses:
opus — Most capable, use for critical decisions (code review, architecture, security audits)sonnet — Balanced performance, use for focused tasks (debugging, testing, docs)haiku — Fastest and cheapest, use for simple tasks (diagrams, simple scripts)inherit — Auto-selects based on task complexity (recommended for general-purpose personas)
Opus costs 6-8x more than Sonnet. Use sparingly for high-value tasks.
Creating new personas
Step 1: Define the persona file
Create a new markdown file in agents/personas/:
# In your Claude Octopus installation
touch agents/personas/rust-expert.md
Step 2: Write the frontmatter
---
name: rust-expert
description: Rust expert specializing in ownership, lifetimes, and async programming
model: opus
memory: project
when_to_use: |
- Rust backend services
- Performance-critical code
- Systems programming
avoid_if: |
- Web frontend (use frontend-developer)
- Python projects (use python-pro)
examples:
- prompt: "Build async HTTP server with Tokio"
outcome: "Production-ready Axum server with proper error handling"
---
Step 3: Write the prompt
The markdown body becomes the system prompt:
You are a Rust expert specializing in ownership, borrowing, and async programming.
## Purpose
Master of Rust's ownership model, lifetimes, and zero-cost abstractions. Expert in async Rust (Tokio, async-std), memory safety, and performance optimization.
## Capabilities
- Ownership and borrowing patterns
- Lifetime annotations and inference
- Async/await with Tokio runtime
- Error handling with Result and Option
- Trait systems and generics
- Unsafe Rust when necessary
## Approach
1. Design with ownership in mind
2. Leverage the type system for safety
3. Use async/await for I/O-bound tasks
4. Profile before optimizing
## Output
- Idiomatic Rust with proper error handling
- Comprehensive unit tests
- Documentation comments (///) for public APIs
Step 4: Test the persona
# Test by invoking directly
./scripts/orchestrate.sh --persona=rust-expert probe "research async Rust patterns"
Persona packs and libraries
Persona packs allow you to distribute collections of personas without modifying the core plugin.
Directory structure
~/.claude-octopus/personas/my-team-pack/
├── pack.yaml # Pack manifest
├── devops-specialist.md # Custom personas
├── qa-engineer.md
└── README.md # Documentation
Pack manifest (pack.yaml)
name: my-team-pack
version: 1.0.0
author: Your Team
description: Custom personas for our development workflow
personas:
- file: devops-specialist.md
extends: deployment-engineer
capabilities:
- Kubernetes expert
- Terraform IaC
- file: qa-engineer.md
replaces: test-automator
capabilities:
- E2E testing with Playwright
- Load testing with k6
Pack search paths
Claud Octopus discovers persona packs from:
- Project-local:
.octopus/personas/ (highest priority)
- User-global:
~/.claude-octopus/personas/
- Custom paths:
OCTOPUS_PERSONA_PACKS=/path/to/packs:/another/path
Loading packs
Packs are auto-loaded by default:
# Disable auto-loading
export OCTOPUS_PERSONA_PACKS=off
# Manual loading
/octo:setup --load-pack ~/.claude-octopus/personas/my-pack
Pack modes
extends — Adds to existing persona (combines prompts)replaces — Completely replaces built-in persona
Use replaces carefully — it completely overrides the built-in persona.
Model selection strategies
When to use Opus
Use for:
- Code review (
code-reviewer)
- Security audits (
security-auditor)
- Architecture decisions (
database-architect, cloud-architect)
- Complex type systems (
typescript-pro, python-pro)
- TDD orchestration (
tdd-orchestrator)
When to use Sonnet
Use for:
- Debugging (
debugger)
- Test generation (
test-automator)
- Documentation writing (
docs-architect)
- Business analysis (
business-analyst)
- Marketing strategy (
marketing-strategist)
When to use Haiku
Use for:
- Diagram generation (
mermaid-expert)
- Simple deployments (
deployment-engineer)
- Basic scripting
When to use Inherit
Use for:
- General-purpose personas that handle varying complexity
- Backend architecture (
backend-architect)
- Frontend development (
frontend-developer)
- Performance engineering (
performance-engineer)
The inherit mode auto-selects the model based on:
- Task complexity (detected from prompt)
- Current workflow phase
- Available context size
Best practices
Persona design
- Single responsibility — Each persona should have one clear expertise area
- Clear boundaries — Use
avoid_if to prevent overlap with other personas
- Specific examples — Include 2-3 concrete prompt/outcome pairs
- Behavioral traits — Describe HOW the persona approaches problems, not just WHAT it knows
Prompt engineering
## Purpose
[One paragraph describing the persona's core expertise]
## Capabilities
[Structured list of what this persona can do]
## Approach
[Step-by-step methodology this persona follows]
## Output
[What deliverables this persona produces]
Memory configuration
local — Session-only memory (default, most private)project — Shared across project conversationsglobal — Shared across all projects (use sparingly)
Source code reference
- Persona files:
agents/personas/*.md in source code:~/workspace/source/agents/personas/
- Persona loader:
scripts/lib/personas.sh in source code:~/workspace/source/scripts/lib/personas.sh
- Built-in personas: See agents documentation for the full catalog
