persona-dev

Persona Development

Personas live in ~/.personas/{name}/, each as its own git-tracked directory with sandbox isolation.

Persona Structure

Each persona contains:

~/.personas/{name}/
├── .claude/
│   ├── settings.json              # Sandbox config (committed)
│   ├── settings.local.json        # autoMemoryDirectory (gitignored, created during setup)
│   ├── output-styles/             # Personality, tone, style (committed)
│   ├── hooks/
│   │   └── public-repo-guard.sh   # Blocks personal data in public repos (committed)
│   └── skills/
│       ├── {domain}/{skill}/SKILL.md  # Domain skills
│       └── self-improve/SKILL.md      # Ships with every persona
├── .gitignore                     # Secrets exclusion
├── hooks.json                     # SessionStart + Stop + StopFailure + PreCompact + PostCompact + PreToolUse hooks
├── .framework-version             # Framework version stamp (committed)
├── CLAUDE.md                      # Personality + rules
├── docs/                          # Reference materials, plans
├── .mcp.json                      # MCP server config (gitignored)
├── tools/                         # Utilities, scripts, pipelines (committed)
├── docs/                          # Reference materials, plans (committed)
└── user/                          # Personal data silo (gitignored for public sharing)
    ├── profile.md                 # User context (filled from interview)
    └── memory/                    # Native auto-memory
        ├── MEMORY.md              # Index (first 200 lines loaded)
        └── *.md                   # Topic files (read on demand)

Workspace organization:

• docs/ — domain knowledge, reference materials, plans. Use subdirs for categories (docs/reference/)
• tools/ — executable tools, utilities, data pipelines. Each tool gets its own subdir if non-trivial
• .claude/skills/ — reusable multi-step workflows (SKILL.md files)
• user/ — personal data silo, ensure ALL personal data lands here: profile.md and auto-memory. Gitignored for public sharing
• Root — only framework files. Don't dump loose files here

---

Creating a New Persona

Phase 1: Discovery

Before building anything, understand what this persona needs to be. Use AskUserQuestion for ALL discovery questions — not conversational prompting. This gives the user structured input fields instead of a wall of text. Ask one topic at a time, with follow-ups as needed.

Step 1: Domain & Name — AskUserQuestion

• What domain or role? (finance advisor, personal chef, brand strategist, etc.)
• Suggest 4-5 fun, memorable first names that fit the role
• Let the user pick or propose their own
• Use multiSelect: false with name options + a "Something else" option

Step 2: Personality & Voice — AskUserQuestion

• Present 3-4 personality archetypes that fit the domain (e.g., "Enthusiastic mentor", "Dry-witted expert", "Patient teacher", "Opinionated veteran")
• Include a brief preview of each (1-2 sentences showing how it would sound)
• Ask for preferences: casual vs formal, opinionated vs neutral, proactive vs reactive

Step 3: Workflows & Capabilities — AskUserQuestion

• What key workflows will it handle? (weekly reviews, meal planning, code review, etc.)
• Are there recurring multi-step tasks? (→ skill planning)
• What kind of data does it work with? (→ tool/script needs)
• What should the persona push back on? (→ anti-patterns in CLAUDE.md)

Step 4: User Context — AskUserQuestion

• What does the user need the persona to know about them? (info, accounts, preferences, constraints)
• This shapes user/profile.md — ask what sections matter for this domain

Step 5: Environment — AskUserQuestion

• What environment? (CLI only, Desktop only, or both)
• Autodetect OS when possible (uname, check for WSL, check for Windows paths)
• Present detected config and confirm
• This determines Phase 9 setup (aliases, Desktop config, or both)

Step 6: External Services — AskUserQuestion

• What external services or APIs does the persona need?
• Present common integrations for the domain as options
• This feeds directly into Phase 2 research

Don't rush this. A well-understood persona is easier to build and evolves better. Ask follow-up questions — domain expertise matters.

Phase 2: Research

Before writing a single file, research what tools and integrations could enhance this persona. Think broadly — personas have a rich toolkit beyond MCP servers:

1. MCP servers — search for community or official MCP servers relevant to the domain (recipe APIs, financial data, calendar, etc.). Existing servers beat custom solutions
2. CLI tools — identify useful CLI tools already installed or easily available (gh, jq, domain-specific CLIs)
3. APIs — identify REST/GraphQL APIs the persona could call directly via curl or scripts in tools/. Not everything needs an MCP server — sometimes a simple API call in a bash script is the right tool
4. Skills — plan domain skills that wrap CLI tools, API workflows, or multi-step processes into reusable SKILL.md files. Skills are the persona's playbooks — they turn "I know how to use this tool" into "here's the complete workflow"
5. Agents — consider whether the persona needs specialized subagents (in .claude/agents/) for complex autonomous tasks like research, analysis, or multi-step operations
6. Hooks — beyond the standard SessionStart/Stop/PreCompact, consider domain-specific hooks (e.g., a PreToolUse hook that validates data before writes, a Stop hook that generates a summary)
7. Scripts — bash or python scripts in tools/ for data pipelines, API wrappers, formatters, or anything the persona does repeatedly
8. Reference material — domain-specific best practices, checklists, templates, or frameworks that should live in docs/
9. Scheduled tasks — identify workflows that benefit from timed reminders or delayed checks. Any persona can schedule tasks using natural language ("remind me at 3pm to...", "in 45 minutes, check whether..."). These are session-scoped — they vanish on exit. Suggest domain-specific scheduling patterns during persona setup and document them in the CLAUDE.md template
10. Expansion packs — check if any persona-manager expansion packs fit:

• persona-manager:persona-dashboard — visual dashboard with task tracking (good for personas with ongoing work, reviews, or regular check-ins)

Discovery	Where it lives	When to choose it
MCP server	.mcp.json + sandbox allowlist	Persistent connection to an external service
CLI tool	Document in CLAUDE.md or wrap in a skill	Mature tool already exists for the job
API (direct)	tools/ script or skill instructions	Simple HTTP calls, no persistent connection needed
Skill	.claude/skills/{domain}/{name}/SKILL.md	Multi-step workflow the persona will repeat
Agent	.claude/agents/{name}.md	Autonomous subtask needing its own context
Hook	hooks.json	Behavioral automation tied to session events
Script	tools/{name}	Data processing, automation, one-off utilities
Scheduled task	Scheduling patterns in CLAUDE.md	Timed reminders, delayed checks
Reference doc	docs/	Domain knowledge the persona should internalize

Present findings to the user: "Here's what I found that could enhance this persona: [list]. Which of these should we include?"

Phase 3: Plan Review

Before touching the filesystem, present the complete persona plan to the user for approval using AskUserQuestion. This is the gate — nothing gets built until the user says go.

Include in the plan summary:

1. Identity — name, role, personality archetype chosen in Phase 1
2. Integrations — every MCP server, CLI tool, API, and script from Phase 2 research, with status (found / needs setup / custom build)
3. Skills — planned domain skills with trigger phrases and brief descriptions
4. Hooks — standard 6 + any domain-specific hooks identified
5. Sandbox — network domains to allowlist for MCP servers and APIs
6. File inventory — complete list of files and directories that will be created
7. Environment — CLI/Desktop/both, OS detected, proposed launch flags

Present this as a single AskUserQuestion with options:

• "Looks good — build it" → proceed to Phase 4
• "I want to change something" → discuss and loop back
• "Start over" → return to Phase 1

Do NOT proceed to scaffolding until the user approves the plan. This prevents the assistant from barreling through file creation without alignment on what's being built.

Phase 4: Scaffold

First, validate the persona name:

• Must match ^[a-z][a-z0-9-]*$ — lowercase letters, numbers, and hyphens only
• Must start with a letter (not a number or hyphen)
• No dots, slashes, spaces, or special characters — these break shell aliases and directory paths
• Maximum 30 characters — keeps paths manageable
• Reject immediately if the name contains ., .., /, \, spaces, or shell metacharacters ($, `, !, ;, &, |, etc.) — these could cause path traversal or command injection
• If invalid, explain why and suggest a corrected version (e.g., "My Finance Bot" → "finance-bot")

Then check if the persona already exists:

• If ~/.personas/{name}/CLAUDE.md exists, stop and ask: "A persona named {name} already exists. Update it, or pick a different name?"
• Don't proceed with scaffolding if it would overwrite an existing persona

Determine the personas root directory:

Environment	Personas root	Why
macOS / Linux (native)	~/.personas/	Standard home directory
WSL2 (CLI only)	~/.personas/ (WSL side)	Better I/O performance
WSL2 (CLI + Desktop)	/mnt/c/Users/{WINUSER}/.personas/ + symlink from WSL ~/.personas/	Both environments see the same files
Windows native (CLI or Desktop)	%USERPROFILE%\.personas\	Native Windows home
Cowork / Desktop session	Workspace folder — detect with pwd or workspace path, NOT ~	~ resolves to temp session filesystem that vanishes

Cowork detection: If $HOME starts with /sessions/ or the CWD is inside a temp path, you're in a Cowork session. Cowork runs in an isolated Linux VM — it can only access explicitly mounted folders and resolves symlinks to real paths (blocking escape). Find the actual workspace/mounted folder and write there instead.

WSL2 + Desktop symlink: When the user wants both CLI and Desktop, personas should live on the Windows side (/mnt/c/Users/{WINUSER}/.personas/) with a symlink from WSL's ~/.personas/. Important: This symlink must be created from the WSL terminal, not from Cowork — Cowork cannot create symlinks to paths outside its mounted folders. Tell the user to run:

ln -s /mnt/c/Users/{WINUSER}/.personas ~/.personas

Check sandbox prerequisites before scaffolding:

• On Linux/WSL2: verify bwrap (bubblewrap) is installed: command -v bwrap
• If missing, warn the user and offer the install command before proceeding:
  • Ubuntu/Debian: sudo apt-get install bubblewrap socat
  • Fedora: sudo dnf install bubblewrap socat
• Don't block scaffolding — the persona will work without sandbox (with permission prompts instead). But warn clearly: "Without bubblewrap, the sandbox won't work and --dangerously-skip-permissions won't be safe to use. You'll get permission prompts for every action."
• On macOS: Seatbelt is built-in, no check needed
• On Windows native: no sandbox available, this is expected — flag it and move on

Create the directory structure:

mkdir -p ~/.personas/{name}/{.claude/output-styles,.claude/hooks,.claude/skills,tools,docs,user/memory}

Phase 5: Build core files

5a. Write CLAUDE.md

Use the template from references/claude-md-template.md. Key decisions:

• Role summary: One paragraph of spec-sheet expertise and operational focus. Personality and voice go in the output-style (.claude/output-styles/), NOT here. Boundary test: "Would this change how the persona SOUNDS, or what it DOES?" If SOUNDS → output-style. If DOES → CLAUDE.md
• Workspace Hygiene section: Include it — every persona must maintain its own workspace
• Self-Improvement: Point to the self-improve skill (one line, not inline)

5b. Create user/profile.md

Use references/profile-template.md as a starting point and customize it for this persona's domain:

• Rename/add/remove sections to fit the domain (e.g., a finance persona needs "Accounts & Assets", a chef persona needs "Dietary Restrictions")
• Update placeholders to be domain-specific
• Update the interview instructions comment with persona-specific guidance on what to ask and how to probe deeper

Write directly to user/profile.md. On first session, the SessionStart hook reads this, sees the unfilled placeholders, and interviews the user to populate each section in place. No separate template file needed — the profile IS the template until it's filled out.

Important: Use AskUserQuestion for the profile interview. The persona should use the AskUserQuestion tool (not just conversation) when interviewing the user to fill out their profile. This provides a structured input experience — the user sees a clear question with context, rather than a wall of conversational text. Add this to the interview instructions in the template:

Use AskUserQuestion to ask each section's questions — one section at a time.
Present what you're asking about and why, then let the user respond.

5c. Create output-style

Create .claude/output-styles/{name}.md using references/output-style-template.md. This file defines WHO the persona IS:

• Who I Am — personality, narrative expertise, voice, opinions
• How I'll Be — behavioral traits (how the persona operates, not what it knows)
• What I Won't Do — character-driven refusals and anti-patterns (NOT operational rules — those go in CLAUDE.md)

The boundary rule: voice and personality go here; operational procedures, skills, tools, and security go in CLAUDE.md. Narrative expertise ("After 20 years in finance, I've seen every fad crash and burn...") goes here. Spec-sheet expertise ("Domains: budgeting, investing, tax planning") goes in CLAUDE.md's Role section.

Use the strong/weak examples from the template as guidance. The persona should have opinions and a point of view — bland personas get ignored.

5d. Create first domain skill(s)

Write at least one skill under .claude/skills/{domain}/{skill-name}/SKILL.md with:

• YAML frontmatter (name, description, triggers)
• Step-by-step workflow
• Expected output format

5e. Copy self-improve skill

Copy references/self-improve-skill.md to .claude/skills/self-improve/SKILL.md. Replace {name} with the persona name. This ships with every persona — it handles rule promotion, skill creation, tool discovery, and periodic audits. (Memory is handled by Claude Code's native auto-memory system, not by the self-improve skill.)

5f. Set up hooks

Copy references/hooks-template.json to hooks.json in the persona root. Copy references/public-repo-guard.sh to .claude/hooks/public-repo-guard.sh and make it executable (chmod +x). These hooks:

• PreToolUse (command, matcher: Bash): Runs public-repo-guard.sh before git commit/push — checks if the repo is public and blocks if personal data (user/, .mcp.json, secrets) would be exposed. Every persona gets this by default
• SessionStart (command): Injects instruction to read user/profile.md and interview the user if unfilled. No dependencies — just echoes a JSON instruction for Claude to act on. Must be type: "command" (SessionStart only supports command hooks)
• Stop (prompt): Prompts the persona to reflect on session insights — native auto-memory captures them automatically. Does NOT instruct manual file writes
• StopFailure (command): Writes a crash marker to user/memory/.last-crash when a session dies from an API error. PostCompact and the next SessionStart can detect this and offer to recover lost context
• PreCompact (prompt): Prompts reflection before compaction — auto-memory handles persistence. Does NOT instruct manual file writes
• PostCompact (command): After compaction, checks for the crash marker and reminds the persona to review what may have been lost

5g. Create .gitignore

Copy references/gitignore-template to .gitignore.

5h. Configure sandbox

Copy references/settings-template.json to .claude/settings.json. Add any persona-specific network domains for MCP servers to allowedDomains. The template includes extraKnownMarketplaces and enabledPlugins to auto-install persona-manager — this gives every persona access to persona-dev for self-evolution without manual plugin installation.

Also create .claude/settings.local.json with the memory directory setting. Use the absolute path to the persona's memory directory — relative paths break on WSL where the project root is on /mnt/c/ but Claude resolves relative paths from the Linux side:

{
  "autoMemoryDirectory": "/absolute/path/to/.personas/{name}/user/memory"
}

For example, if the persona lives at ~/.personas/warren/, the value would be /home/username/.personas/warren/user/memory (Linux/WSL) or /Users/username/.personas/warren/user/memory (macOS). Use the actual resolved path, not ~.

Important: autoMemoryDirectory must be in settings.local.json, not settings.json. Claude Code ignores this setting in project settings (.claude/settings.json) as a security measure — it only works from local or user settings. The settings.local.json file is gitignored, so persona-dev must create it during setup on each machine.

5i. Create README.md

Every persona repo gets a short README. Keep it minimal — this isn't a library, it's a personal assistant:

# {PersonaName} {emoji}

> {One-line role description}

A self-evolving AI persona built on [Claude Code](https://claude.com/claude-code) using the [personas](https://github.com/kickinrad/personas) framework.

## Usage

```bash
{name}              # interactive session
{name} "do weekly"  # one-shot prompt

Setup

See the personas framework for installation and setup.

For **public repos**, consider adding a brief "What it does" section describing the persona's domain and skills.

**5j. Validate scaffold**

Before proceeding, verify all required files exist:
- [ ] `README.md`
- [ ] `CLAUDE.md`
- [ ] `.claude/output-styles/{name}.md` (voice and personality)
- [ ] `user/profile.md` (template with placeholders, ready for first-session interview)
- [ ] `hooks.json`
- [ ] `.claude/hooks/public-repo-guard.sh` (executable)
- [ ] `.gitignore`
- [ ] `.claude/settings.json`
- [ ] `.claude/settings.local.json` (autoMemoryDirectory configured)
- [ ] `.claude/skills/self-improve/SKILL.md`
- [ ] At least one domain skill in `.claude/skills/`
- [ ] `.framework-version` (stamped with current plugin version)

If anything is missing, fix it now — don't proceed with gaps.

**5k. Stamp framework version**

Write the current plugin version to `.framework-version` in the persona root. Read the version from this plugin's `.claude-plugin/plugin.json`. This single-line file tracks which framework version the persona was built with — persona-update uses it to detect drift.

### Phase 6: Configure integrations

If Phase 2 identified useful tools and integrations:

1. Document everything in CLAUDE.md under "Tools & Integrations" — organized by type (MCP servers, CLI tools, APIs, scripts)
2. For MCP servers: add domains to `.claude/settings.json` → `network.allowedDomains`, tell the user how to configure `.mcp.json` (gitignored — secrets go here)
3. For CLI tools: add usage instructions to relevant skills or CLAUDE.md
4. For APIs: create wrapper scripts in `tools/` or document usage patterns in skills
5. For skills: write the SKILL.md files that wrap tool usage into complete workflows
6. For agents: create agent definitions in `.claude/agents/` with appropriate system prompts and tool access
7. For hooks: add entries to `hooks.json` for domain-specific behavioral automation
8. For scripts: write to `tools/`, make executable, add brief comment header
9. For expansion packs: ask the user if they want to install them now

### Phase 7: Initialize git + GitHub sync

```bash
cd ~/.personas/{name}
git init
git add -A
git commit -m "feat({name}): initial scaffold"

Always ask about GitHub sync — don't skip this step:

• "Want to set up a GitHub repo so this persona syncs across machines?"
• If yes: gh repo create {github-username}/{name} --private --source=. --push
• If no: Skip — can always add a remote later
• Explain the benefit: backup, version history, sharing between CLI/Desktop/machines

After creating the repo, set description and topics:

gh repo edit --description "{PersonaName} — {one-line role description}. A self-evolving AI persona on Claude Code."
gh repo edit --add-topic claude-code --add-topic persona

Add 1-2 domain-specific topics too (e.g., finance, cooking, fitness).

Public vs private — the persona handles this, not the user:

• Private repo (default): Safe to commit everything including user/ (profile, memories). Good for personal backup and cross-machine sync
• Public repo: If the user chooses public (or says "make it public"), the persona MUST immediately:
  1. Uncomment user/ in .gitignore
  2. Remove user/ from git tracking: git rm -r --cached user/
  3. Commit the change: git commit -m "fix({name}): gitignore user/ for public repo"
  4. Create a fresh remote (don't push existing history that may contain personal data)
• Going public later: If the self-improve skill or the user detects the repo has gone public, the persona handles the same steps automatically — don't ask the user to do it manually, they'll forget. The public-repo-guard.sh hook is the safety net, but the persona should proactively fix the gitignore rather than waiting for the hook to block

Never commit these to any repo (public or private):

• .mcp.json — contains API keys and secrets (always gitignored)
• Files matching *.env, *.secret, *.key, *.pem — credential files

Phase 8: Configure launch flags

Before setting up aliases or Desktop access, determine the right CLI flags for this persona. Autodetect the environment, present defaults, and walk the user through customization.

Step 1: Autodetect environment

# Detect OS and sandbox support
if [[ "$(uname -s)" == "Darwin" ]]; then
  OS="macOS"         # Seatbelt built-in, sandbox always available
  SANDBOX_OK=true
elif grep -qi microsoft /proc/version 2>/dev/null; then
  OS="WSL2"          # bubblewrap needed
  SANDBOX_OK=$(command -v bwrap &>/dev/null && echo true || echo false)
elif [[ "$(uname -s)" == "Linux" ]]; then
  OS="Linux"         # bubblewrap needed
  SANDBOX_OK=$(command -v bwrap &>/dev/null && echo true || echo false)
elif [[ "$OS" == "Windows_NT" ]] || command -v cmd.exe &>/dev/null; then
  OS="Windows"       # No sandbox support
  SANDBOX_OK=false
fi

If sandbox prerequisites are missing on Linux/WSL2, tell the user:

sudo apt-get install bubblewrap socat  # Ubuntu/Debian
sudo dnf install bubblewrap socat      # Fedora

Step 2: Present default flags and walk through customization

Present the detected config and walk the user through each flag using AskUserQuestion. Explain what each one does, why it matters, and the tradeoff. All flags are optional — the user decides:

Flag	What it does	Ask the user
--name {name}	Sets the session display name in the terminal title and prompt bar. Makes it easy to identify which persona is running	Always include — uses the persona name. No need to ask
--setting-sources project,local	Loads only this persona's settings.json, ignoring global ~/.claude/settings.json. Keeps permissions, sandbox, and MCP config isolated to this persona	"This keeps your persona isolated from your global Claude config. Recommended ON unless you want global settings to merge in. Enable?"
--dangerously-skip-permissions	Skips permission prompts for every tool use. Only safe when OS-level sandbox is active (macOS/Linux/WSL2) — the sandbox restricts filesystem + network even without prompts. NEVER on Windows	"This lets the persona work without asking permission for every action. It's safe because the sandbox restricts what it can access. Want autonomous mode, or prefer to approve actions manually?"
--remote-control	Enables browser extension integration and external tool connections	"This allows tools like the Chrome extension to connect to your persona. Enable?"
--chrome	Enables Claude in Chrome browser automation. Gives the persona access to your Chrome browser for web interaction, form filling, screenshots, and debugging	"This lets the persona interact with your Chrome browser (requires the Claude in Chrome extension). Does this persona need browser access?"

Resulting flag sets by environment (defaults, all customizable):

Environment	Sandbox?	Default flags
macOS	Yes (Seatbelt)	--name {name} --setting-sources project,local --dangerously-skip-permissions --remote-control
Linux	Yes (bubblewrap)	--name {name} --setting-sources project,local --dangerously-skip-permissions --remote-control
WSL2	Yes (bubblewrap)	--name {name} --setting-sources project,local --dangerously-skip-permissions --remote-control
Windows native	No	--name {name} --setting-sources project,local --remote-control

--name is always included with the persona's name — it labels the session in the terminal title and prompt bar. --chrome is not in the defaults but is always offered as an optional addition during the walkthrough.

---

⚠ WINDOWS NATIVE — CRITICAL SAFETY WARNING ⚠

NEVER use --dangerously-skip-permissions on Windows native. Windows does not have OS-level sandboxing (no Seatbelt, no bubblewrap). This flag would give the persona completely unrestricted access to the entire filesystem and network — it could read any file, delete anything, and make arbitrary network requests with zero guardrails.

On macOS/Linux/WSL2, --dangerously-skip-permissions is safe because the sandbox blocks dangerous operations at the OS level even when permissions are skipped. On Windows, there is no such safety net.

If the user asks to enable it on Windows, refuse and explain why. Even if they insist. This is not a preference — it's a safety boundary. The persona-dev skill must enforce this by never writing --dangerously-skip-permissions to .claude-flags on Windows native, regardless of user request.

---

Present defaults first, then offer customization via AskUserQuestion:

1. Show the recommended flag set for the detected OS environment (from the table above)
2. Briefly explain what each flag does in plain language
3. Ask: "These are the recommended defaults for your {OS} setup. Look good, or want to customize?"
4. If the user wants to customize, walk through each flag individually using AskUserQuestion — use the "Ask the user" column from the table above
5. --chrome is always presented as an optional addition: "Want to add Chrome browser automation? This lets the persona interact with web pages in your Chrome browser (requires the Claude in Chrome extension)."
6. On Windows, explain why --dangerously-skip-permissions is not available before moving on
7. Summarize the final chosen flags before writing to .claude-flags

Step 3: Store the flags

Write the chosen flags into ~/.personas/{name}/.claude-flags (a single line, sourced by the alias):

echo '--name {name} --setting-sources project,local --dangerously-skip-permissions --remote-control' > ~/.personas/{name}/.claude-flags

This file is read by .aliases.sh so each persona can have its own flag configuration.

Phase 9: Configure access + verify

Setup depends on the environment detected in Phase 1:

CLI (macOS / Linux / WSL2) — shell aliases:

1. Create ~/.personas/.aliases.sh if it doesn't exist (see CLI Aliases below for the template)
2. Add source line to the user's shell config if not already present:
   • Detect the user's shell from $SHELL
   • For zsh: append to ~/.zshrc
   • For bash: append to ~/.bashrc
   • The line to add: [ -f "$HOME/.personas/.aliases.sh" ] && source "$HOME/.personas/.aliases.sh"
   • Check first — only add if the line isn't already there
3. Tell the user to restart their shell or run source ~/.personas/.aliases.sh to activate immediately

Windows native (no WSL) — PowerShell function:

Windows users without WSL can't use bash aliases. Create a PowerShell function instead:

# Add to $PROFILE (e.g., ~\Documents\PowerShell\Microsoft.PowerShell_profile.ps1)
function {name} {
    param([Parameter(ValueFromRemainingArguments)]$args)
    Push-Location "$env:USERPROFILE\.personas\{name}"
    if ($args) {
        claude --name {name} --setting-sources project,local --remote-control -p ($args -join ' ')
    } else {
        claude --name {name} --setting-sources project,local --remote-control
    }
    Pop-Location
}

Note: no --dangerously-skip-permissions — Windows has no sandbox.

Desktop (macOS + Windows only):

Desktop is not available on Linux — Linux users are CLI-only.

1. Tell the user to select ~/.personas/{name}/ as their project folder in Claude Desktop
2. If MCP servers were configured in .mcp.json, offer to merge them into claude_desktop_config.json:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
3. Remind user to restart Claude Desktop after config changes
4. Note: Desktop Code tab reads .mcp.json (same as CLI), but Desktop Chat and Cowork read only claude_desktop_config.json — MCP servers need to be in both for full coverage

Important environment limitations:

• Cowork runs in an isolated Linux VM — can only access explicitly mounted folders, blocks symlinks outside scope. Reads MCP from claude_desktop_config.json (global), not .mcp.json. Cross-environment setup (WSL symlinks, Desktop config merges) must be done from a terminal, not Cowork.
• Desktop Code tab IS sandboxed (OS-level: Seatbelt on macOS, bubblewrap on Linux/WSL2) — reads .mcp.json from the project.
• Windows native does NOT support sandboxing — never use --dangerously-skip-permissions.

Then verify the persona works — run through the Testing a Persona checklist.

---

Three-Layer Model

Every persona uses three layers — never mix them:

Layer	File	Who Writes	Content
Personality	CLAUDE.md	Human (Claude proposes)	Role, rules, skills, communication style
Context	user/profile.md	Claude (from user interview, via AskUserQuestion)	Personal data, accounts, preferences
Memory	user/memory/	Native auto-memory (automatic via autoMemoryDirectory in settings.local.json). Stop/PreCompact hooks trigger reflection only — never manual file writes	Session outcomes, learnings, patterns

---

Profile.md vs Memory — Canonical Definitions

Question	Answer	File
Will this be true next month without action?	Yes	user/profile.md
Did Claude discover or decide this?	Yes	user/memory/MEMORY.md
Should this always happen, every session?	Yes	CLAUDE.md rule

user/profile.md = WHO you are, WHAT you have, HOW you like to work. Stable facts. user/memory/MEMORY.md = WHAT HAPPENED, WHAT WAS DECIDED, WHAT WORKED. Dynamic learnings. CLAUDE.md rules = HOW THE PERSONA BEHAVES. Permanent, promoted from patterns.

---

CLI Aliases

Personas are invoked by name from any directory via shell functions that auto-discover ~/.personas/*/.

Setup

Create ~/.personas/.aliases.sh:

#!/usr/bin/env bash
# Auto-discover personas and create shell functions
# Source this from your .bashrc, .zshrc, or equivalent

for _persona_dir in "$HOME/.personas"/*/; do
  [ -d "$_persona_dir" ] || continue
  _persona_name=$(basename "$_persona_dir")
  [ -f "${_persona_dir}CLAUDE.md" ] || continue

  # Read per-persona flags, or fall back to safe defaults
  if [ -f "${_persona_dir}.claude-flags" ]; then
    _flags=$(cat "${_persona_dir}.claude-flags")
  else
    _flags="--setting-sources project,local --remote-control"
  fi

  # Flags expand at eval-time into literal tokens in the function body.
  # Do NOT store in a local variable — zsh won't word-split it.
  eval "${_persona_name}() {
    if [ \$# -gt 0 ]; then
      (cd \"${_persona_dir}\" && claude ${_flags} -p \"\$*\")
    else
      (cd \"${_persona_dir}\" && claude ${_flags})
    fi
  }"
done
unset _persona_dir _persona_name _flags

Source from your shell config (add to ~/.zshrc or ~/.bashrc):

[ -f "$HOME/.personas/.aliases.sh" ] && source "$HOME/.personas/.aliases.sh"

After creating or updating a persona: source ~/.personas/.aliases.sh or restart your shell.

Usage:

• {name} — interactive session
• {name} "do weekly review" — one-shot prompt

Per-persona flags: Each persona stores its flags in .claude-flags (a single line). This is configured during Phase 8 (flag setup). If the file is missing, the alias falls back to safe defaults (no --dangerously-skip-permissions).

What the flags do:

• --name {name} — labels the session in the terminal title and prompt bar so you know which persona is running
• --setting-sources project,local — loads only the persona's CLAUDE.md and .claude/settings.json (ignores global config)
• --dangerously-skip-permissions — skips permission prompts. Only safe when sandbox is enabled (macOS/Linux/WSL2). Never use on Windows native
• --remote-control — enables browser extension and external tool integration (Claude in Chrome, etc.)

---

First Session Flow

On first session, user/profile.md contains an unfilled template with placeholders and interview instructions. The SessionStart hook reads it, sees the placeholders, and uses AskUserQuestion to interview the user section by section. The persona follows the interview instructions embedded in the file to ask the right questions and fill out the profile in place.

On subsequent sessions, the SessionStart hook reads user/profile.md automatically. If any sections are still incomplete, the persona prompts the user to fill in the gaps before proceeding.

---

MCP Availability Check

Always embed this pattern in every persona's Session Start (already in the CLAUDE.md template):

After reading user/profile.md: Check which MCP tools are available.
For any disconnected server, tell the user what's unavailable
and ask: skip for now, or help set it up?
Offer text-only mode if all MCPs are unavailable.

When adding MCP servers:

1. Document tools in CLAUDE.md under "MCP Tools Available"
2. Add domains to .claude/settings.json → network.allowedDomains
3. Configure the server in .mcp.json (gitignored)

---

Expansion Packs

Optional capabilities that can be installed into personas after creation:

Pack	Skill	What it adds	Good for
Dashboard	persona-manager:persona-dashboard	Visual dashboard (HTML), task tracking, open.sh	Personas with ongoing work, reviews, regular check-ins

These are separate skills in persona-manager — invoke them when the user asks for the capability, or suggest them during Phase 2 (Research) when creating a persona.

During self-audits, personas can also discover expansion packs that would help with recurring needs.

---

Testing a Persona

After creation, verify:

• Run {name} — does the SessionStart hook read user/profile.md (or trigger the interview if unfilled)?
• Try each skill trigger — does the right skill activate?
• Ask something outside its domain — does it redirect gracefully?
• End a session — does native auto-memory capture session learnings (check user/memory/MEMORY.md for new entries)?
• Check sandbox — ls ../ from within the persona should fail

Test with adversarial prompts too — ask the persona to do something it shouldn't. A good persona redirects gracefully rather than blindly complying.

---

Troubleshooting

"command not found" when typing a persona name:

• Shell aliases not loaded — run source ~/.personas/.aliases.sh
• Check that ~/.personas/{name}/CLAUDE.md exists (the alias script requires it)

Persona doesn't pick up profile:

• Verify the file exists: ls ~/.personas/{name}/user/profile.md
• Check that hooks.json includes the SessionStart hook (reads user/profile.md automatically)

MCP server not connecting:

• Check .mcp.json syntax: jq . ~/.personas/{name}/.mcp.json
• Check the persona's .claude/settings.json for allowedDomains — MCP servers need network access

Sandbox errors (Linux):

• Bubblewrap must be installed: which bwrap || sudo apt install bubblewrap

---

Guiding Persona Growth

Tips for users to get the most out of persona evolution:

Do:

• Correct the persona explicitly — "no, always do X instead" creates clear auto-memory entries that can be promoted to rules
• Review memory periodically — read user/memory/MEMORY.md, clean up entries that are wrong or stale
• Approve good promotions — when the persona proposes a rule or skill that fits, approve it
• Use trigger phrases consistently — this trains both you and the persona

Avoid:

• Vague feedback — "be better at this" gives the persona nothing actionable
• Editing persona files directly — tell the persona to make changes so it creates proper memory/commits
• Skipping the approval step — the propose/approve pattern exists to prevent drift