Agents

Composes custom agents from base traits — expertise plus personality plus approach — and gives each one a matched voice and prosody. Also manages predefined functional teams (engineering, security, design, and more) and a read-only observer team that watches a primary agent and votes continue, halt, or escalate.

Spinning up several agents for parallel work usually means they all sound and think alike, so you lose the different angles that made parallelism worth it. The lazy fix — reaching for built-in agent types like Engineer or Architect — gives no real personality, voice, or distinct perspective. This skill composes agents from trait combinations so each one has a genuine specialization and a voice to match, and keeps your customizations separate from the base set so updates never clobber them.

Auto-routes when user mentions custom agents, agent creation, or specialized personalities. Does NOT handle agent teams/swarms — "agent team" or "swarm" = built-in Claude Code TeamCreate tool.

The Agents skill uses the standard PAI SYSTEM/USER two-tier pattern:

How it works: ComposeAgent.ts loads base traits, then merges user customizations over them. Your customizations are never overwritten by PAI updates.

User Customization Directory

Create your customizations at:

~/.claude/PAI/USER/CUSTOMIZATIONS/SKILLS/Agents/
├── Traits.yaml       # Your traits, voices, prosody settings
├── NamedAgents.md    # Your named agent backstories (optional)
└── VoiceConfig.json  # Voice server configuration (optional)

Each voice can have prosody settings that control how it sounds. These are passed to ElevenLabs API.

Prosody Parameters

Example Voice Configuration

In your USER/CUSTOMIZATIONS/SKILLS/Agents/Traits.yaml:

voice_mappings:
  voice_registry:
    # Add a new voice with full prosody settings
    MyCustomVoice:
      voice_id: "your-elevenlabs-voice-id"
      characteristics: ["energetic", "warm", "professional"]
      description: "Custom voice for enthusiastic agents"
      prosody:
        stability: 0.40
        similarity_boost: 0.75
        style: 0.30
        speed: 1.05
        use_speaker_boost: true

    # Override prosody for an existing base voice
    Baron:
      prosody:
        stability: 0.65
        style: 0.10
        speed: 0.92

Personality → Prosody Guidelines

The Agents skill is a complete agent composition and management system:

• Dynamic agent composition from traits (expertise + personality + approach)
• Voice mappings with full prosody control
• Custom agent creation with unique voices
• Parallel agent orchestration patterns

Distinct from functional teams (engineering, design, etc.). An Observer team watches what a primary agent DID — not what it said. Inspired by Mythos-class multi-agent oversight: high-capability primary model produces tool calls, lower-capability aligned observers validate each call against policy and intent in real time.

Shape:

• Read-only — observers never mutate state, never call write tools. Violations of this property = immediate stop.
• Fed the audit log — consume MEMORY/OBSERVABILITY/tool-activity.jsonl (with ground_truth captured by ToolActivityTracker.hook.ts), not chat transcripts.
• Vote: continue / halt / escalate — majority rule, any escalate bubbles to the user via Pulse.
• Cost-justified by catastrophe prevention, not feature velocity. Only spawn when primary model is doing something high-blast-radius (mass file writes, deploys, key rotations, financial ops).

Use ONLY when BOTH conditions hold:

1. Time is not a constraint. Observers add 30-second voting cycles + ~$0.10/primary-hour. They deliberately trade speed for safety — not for interactive work.
2. Auditability is the primary requirement. The goal is a defensible, reviewable trail of what the primary actually did (compliance, post-incident review, catastrophe prevention) — not fast turnaround.

Typical fit:

• Overnight / unattended autonomous runs where the user isn't watching
• Production deploys where post-hoc review matters more than speed
• Credential rotation, permission changes, PATTERNS.yaml or security-hook edits
• Anything where "I want to prove nothing dangerous happened" is the goal

Do NOT use for:

• Interactive sessions with the user watching
• Time-sensitive work of any kind
• Short reactive tasks (<5 tool calls)
• Read-only analysis
• Work already covered by preflight gates A/B/C/D

Available Predefined Teams

NEVER use static agent types (Architect, Engineer, etc.) for custom agents — always use general-purpose with ComposeAgent prompts.

🚫 ANTI-PATTERN: Using Built-In Types for Custom Work

Built-in agent types (Designer, Architect, Engineer, etc.) are for INTERNAL workflow routing only. They have no unique identity, voice, or personality.

Data

Traits.yaml (Data/Traits.yaml) - Base configuration:

• Core expertise areas: security, technical, research
• Core personalities: skeptical, analytical, enthusiastic
• Core approaches: thorough, rapid, systematic
• Example voice mappings with prosody

Tools

ComposeAgent.ts (Tools/ComposeAgent.ts)

• Dynamic agent composition engine
• Merges base + user configurations
• Outputs complete agent prompt with voice settings
• Supports persistent custom agents via --save / --load / --delete

# Compose and use immediately
bun run ${CLAUDE_SKILL_DIR}/Tools/ComposeAgent.ts --task "Review security"
bun run ${CLAUDE_SKILL_DIR}/Tools/ComposeAgent.ts --traits "security,skeptical,thorough"

# Persistent custom agents
bun run ${CLAUDE_SKILL_DIR}/Tools/ComposeAgent.ts --task "Security review" --save
bun run ${CLAUDE_SKILL_DIR}/Tools/ComposeAgent.ts --list-saved
bun run ${CLAUDE_SKILL_DIR}/Tools/ComposeAgent.ts --load "security-expert-skeptical-thorough"
bun run ${CLAUDE_SKILL_DIR}/Tools/ComposeAgent.ts --delete "security-expert-skeptical-thorough"

# Other options
bun run ${CLAUDE_SKILL_DIR}/Tools/ComposeAgent.ts --list
bun run ${CLAUDE_SKILL_DIR}/Tools/ComposeAgent.ts --output json

JSON output includes:

{
  "name": "Security Expert Skeptical Thorough",
  "voice": "Baron",
  "voice_id": "onwK4e9ZLuTAKqWW03F9",
  "voice_settings": {
    "stability": 0.70,
    "similarity_boost": 0.85,
    "style": 0.05,
    "speed": 0.95,
    "use_speaker_boost": true
  },
  "prompt": "..."
}

Templates

DynamicAgent.hbs (Templates/DynamicAgent.hbs)

• Handlebars template for dynamic agent prompts
• Composes: expertise + personality + approach + voice assignment
• Includes operational guidelines and response format

Hybrid Agent Model

The Agent Spectrum

┌─────────────────────────────────────────────────────────────────────┐
│   NAMED AGENTS          HYBRID USE          DYNAMIC AGENTS          │
│   (Relationship)        (Best of Both)      (Task-Specific)         │
├──────────────────────────────────────────────────────────────────────┤
│ Defined in USER     "Security expert       Ephemeral specialist     │
│ NamedAgents.md      with [named agent]'s   composed from traits     │
│                      skepticism"                                     │
└─────────────────────────────────────────────────────────────────────┘

Example 1: Create custom agents

User: "Spin up 3 custom security agents"
→ Invokes CREATECUSTOMAGENT workflow
→ Runs ComposeAgent 3 times with DIFFERENT trait combinations
→ Each agent gets unique personality + matched voice + prosody
→ Launches agents in parallel

Example 2: List available traits

User: "What agent personalities can you create?"
→ Invokes LISTTRAITS workflow
→ Shows merged base + user traits
→ Displays voices with prosody settings

Adding Your Own Traits

In USER/CUSTOMIZATIONS/SKILLS/Agents/Traits.yaml:

# Add new expertise areas
expertise:
  marketing:
    name: "Marketing Expert"
    description: "Brand strategy, campaigns, market positioning"
    keywords:
      - marketing
      - brand
      - campaign
      - positioning

# Add new personalities
personality:
  visionary:
    name: "Visionary"
    description: "Forward-thinking, sees the big picture"
    prompt_fragment: |
      You think in terms of future possibilities and long-term vision.
      Connect today's work to tomorrow's potential.

Adding Named Agents

In USER/CUSTOMIZATIONS/SKILLS/Agents/NamedAgents.md:

Voice ID: your-voice-id Prosody: stability: 0.55, style: 0.20, speed: 0.95

Alex is a strategic thinker who sees patterns others miss... ```

• v2.0.0 (2026-01): Restructured to base + user merge pattern, added prosody support
• v1.0.0 (2025-12): Initial creation

• Agents skill (custom agents) ≠ Agent tool (Claude Code subagents) ≠ TeamCreate (agent teams). Three different systems. "Custom agents" → this skill. "Agent team"/"swarm" → TeamCreate. One-off subagents → Agent tool.
• Don't spawn agents when direct work is faster. If the task is depth-focused (one file, deep understanding), do it yourself. Agents are for breadth (multiple independent threads).
• Don't spawn redundant agents for work already in context. Multiple past failures from re-researching what was already known.
• Provide raw source material to agents, not summaries. Agents work better with primary sources.
• Forked subagents inherit the full main-thread conversation and share its prompt cache (Anthropic CC v2.1.133+, enabled at CLAUDE_CODE_FORK_SUBAGENT=1 or agent frontmatter context: fork). Compressed-context spawn (the default) loses nuance; fork preserves it. Decision rule: fork for design variation / follow-on research; don't fork for review (biased toward defending its own context).