Files
agent-skills/agents
Addy Osmani bc7f9e88d3 docs(agents): add Composition block to each persona
Each persona now ends with a three-bullet block stating when to invoke it
directly, which slash commands wrap it, and the rule that personas do not
invoke other personas. Keeps the persona honest about its place in the
workflow without re-stating the broader orchestration model.
2026-04-18 23:29:36 -07:00
..

Agent Personas

Specialist personas that play a single role with a single perspective. Each persona is a Markdown file consumed as a system prompt by your harness (Claude Code, Cursor, Copilot, etc.).

Persona Role Best for
code-reviewer Senior Staff Engineer Five-axis review before merge
security-auditor Security Engineer Vulnerability detection, OWASP-style audit
test-engineer QA Engineer Test strategy, coverage analysis, Prove-It pattern

How personas relate to skills and commands

Three layers, each with a distinct job:

Layer What it is Example Composition role
Skill A workflow with steps and exit criteria code-review-and-quality The how — invoked from inside a persona or command
Persona A role with a perspective and an output format code-reviewer The who — adopts a viewpoint, produces a report
Command A user-facing entry point /review, /ship The when — composes personas and skills

The user (or a slash command) is the orchestrator. Personas do not call other personas. Skills are mandatory hops inside a persona's workflow.

When to use each

Direct persona invocation

Pick this when you want one perspective on the current change and the user is in the loop.

  • "Review this PR" → invoke code-reviewer directly
  • "Are there security issues in auth.ts?" → invoke security-auditor directly
  • "What tests are missing for the checkout flow?" → invoke test-engineer directly

Slash command (single persona behind it)

Pick this when there's a repeatable workflow you'd otherwise re-explain every time.

  • /review → wraps code-reviewer with the project's review skill
  • /test → wraps test-engineer with TDD skill

Slash command (orchestrator — fan-out)

Pick this only when independent investigations can run in parallel and produce reports that a single agent then merges.

  • /ship → fans out to code-reviewer + security-auditor + test-engineer in parallel, then synthesizes their reports into a go/no-go decision

This is the only orchestration pattern this repo endorses. See references/orchestration-patterns.md for the full pattern catalog and anti-patterns.

Decision matrix

Is the work a single perspective on a single artifact?
├── Yes → Direct persona invocation
└── No  → Are the sub-tasks independent (no shared mutable state, no ordering)?
         ├── Yes → Slash command with parallel fan-out (e.g. /ship)
         └── No  → Sequential slash commands run by the user (/spec → /plan → /build → /test → /review)

Worked example: valid orchestration

/ship is the canonical fan-out orchestrator in this repo:

/ship
  ├── (parallel) code-reviewer    → review report
  ├── (parallel) security-auditor → audit report
  └── (parallel) test-engineer    → coverage report
                  ↓
        merge phase (main agent)
                  ↓
        go/no-go decision + rollback plan

Why this works:

  • Each sub-agent operates on the same diff but produces a different perspective
  • They have no dependencies on each other → genuine parallelism, real wall-clock savings
  • Each runs in a fresh context window → main session stays uncluttered
  • The merge step is small and benefits from full context, so it stays in the main agent

Worked example: invalid orchestration (do not build this)

A meta-orchestrator persona whose job is "decide which other persona to call":

/work-on-pr → meta-orchestrator
                  ↓ (decides "this needs a review")
              code-reviewer
                  ↓ (returns)
              meta-orchestrator (paraphrases result)
                  ↓
              user

Why this fails:

  • Pure routing layer with no domain value
  • Adds two paraphrasing hops → information loss + 2× token cost
  • The user already knows they want a review; let them call /review directly
  • Replicates work that slash commands and AGENTS.md intent-mapping already do

Rules for personas

  1. A persona is a single role with a single output format. If you find yourself adding a second role, create a second persona.
  2. Personas do not invoke other personas. Composition is the job of slash commands or the user.
  3. A persona may invoke skills (the how).
  4. Every persona file ends with a "Composition" block stating where it fits.

Adding a new persona

  1. Create agents/<role>.md with the same frontmatter format used by existing personas.
  2. Define the role, scope, output format, and rules.
  3. Add a Composition block at the bottom (Invoke directly when / Invoke via / Do not invoke from another persona).
  4. Add the persona to the table at the top of this file.
  5. If the persona enables a new orchestration pattern, document it in references/orchestration-patterns.md rather than inventing the pattern in the persona file itself.