How Agent Personas Like the Code-Reviewer Operate in agent-skills

Agent personas in the addyosmani/agent-skills repository operate by combining static Markdown role definitions with reusable skill frameworks, enabling deterministic, multi-axis code review processes.

The agent-skills repository implements a structured approach to AI agent behavior where personas like the code-reviewer function as orchestrators of specialized skills. This architecture separates role identity from execution logic, allowing the code-reviewer persona to conduct consistent, five-dimensional reviews across any codebase by mapping user intent to concrete skill implementations.

Understanding Agent Persona Architecture

Agent personas in this repository are not monolithic prompts but layered configurations that bind identity metadata to executable skill frameworks.

Persona Definition and Metadata

The core identity of the code-reviewer resides in agents/code-reviewer.md【/cache/repos/github.com/addyosmani/agent-skills/main/agents/code-reviewer.md】. This file defines the persona's name and description as a senior code-review agent, alongside a detailed review framework specifying five mandatory review dimensions: Correctness, Readability, Architecture, Security, and Performance.

The file also enforces a strict output template that the agent must produce, ensuring every review contains categorized findings (Critical, Important, Suggestion) and specific sections like "What's Done Well" and "Verification Story."

Skill Mapping Framework

The repository uses AGENTS.md【/cache/repos/github.com/addyosmani/agent-skills/main/AGENTS.md】 as an intent-to-skill router. When a user requests a code review, the OpenCode engine detects the code review intent through this mapping and binds it to the concrete skill code-review-and-quality.

This skill's implementation resides in skills/code-review-and-quality/SKILL.md【/cache/repos/github.com/addyosmani/agent-skills/main/skills/code-review-and-quality/SKILL.md】, which contains the full multi-axis review methodology, detailed checklists for each dimension, and the "Review Process" execution steps that the persona must follow. The architecture intentionally decouples the persona's voice from the skill's technical rigor, allowing the same review framework to be reused across different agent personalities.

How the Code-Reviewer Persona Executes Reviews

When invoked, the code-reviewer persona operates through a deterministic pipeline that transforms raw code changes into structured, actionable feedback.

The Five-Axis Review Process

The persona executes reviews across five mandatory dimensions defined in skills/code-review-and-quality/SKILL.md:

1. Correctness – Logic errors, edge cases, and functional accuracy
2. Readability – Naming conventions, documentation clarity, and code structure
3. Architecture – Design patterns, separation of concerns, and maintainability
4. Security – Input validation, injection risks, and vulnerability patterns (leveraging skills/security-and-hardening/SKILL.md for deep security analysis)
5. Performance – Algorithmic complexity, resource usage, and optimization opportunities (utilizing skills/performance-optimization/SKILL.md for detailed performance profiling)

The persona categorizes each finding into Critical, Important, or Suggestion tiers, ensuring the review recipient can prioritize fixes effectively.

Intent Detection and Skill Invocation

The execution flow follows this sequence:

1. Intent Recognition – The OpenCode engine parses the user request and identifies the code-review intent via the mapping in AGENTS.md.
2. Skill Loading – The engine loads the code-review-and-quality skill framework from skills/code-review-and-quality/SKILL.md.
3. Persona Activation – The code-reviewer persona from agents/code-reviewer.md assumes the role of executor, applying its senior-level voice and expertise to the skill's technical framework.
4. Change-Set Analysis – The persona reads the provided diff or pull request, applying the five-axis methodology systematically.

Output Generation and Template Structure

The persona formats findings using the strict Markdown template defined in agents/code-reviewer.md. The output structure includes:

• Review Summary – Verdict (Approve/Request Changes) and high-level overview
• Critical Issues – Blocker-level findings with file paths and line numbers
• Important Issues – Significant improvements needed
• Suggestions – Quality-of-life enhancements
• What's Done Well – Positive reinforcement section highlighting effective implementations
• Verification Story – Documentation of tests reviewed, build status, and security checks performed

This template ensures that every review produced by the code-reviewer persona is comprehensive, consistent, and actionable regardless of the codebase being analyzed.

Practical Code Examples

The following examples demonstrate how the code-reviewer persona processes input and generates structured output according to its defined skill framework.

Input Prompt Structure

When requesting a review, the prompt should specify the intent and provide the change context:

# Prompt sent to the agent

Review the following pull request for correctness, security, and performance.
Spec: Add caching layer to the API client.
Change: https://github.com/example/repo/pull/42

Typical Agent Output

Based on the template in agents/code-reviewer.md, the persona generates structured feedback like this:

## Review Summary

**Verdict:** REQUEST CHANGES

**Overview:** The change introduces a caching wrapper for the API client but lacks input validation and contains a potential N+1 query.

### Critical Issues

- [src/api/client.js:57] Missing validation of the `cacheKey` parameter – leads to injection risk.
- [src/api/client.js:112] N+1 query pattern when iterating over `items` – could cause severe latency.

### Important Issues

- [src/api/client.js:84] Function name `wrap` is vague; consider `createCachingClient`.
- [tests/api/client.test.js:21] No test for cache miss scenario.

### Suggestions

- Add JSDoc comments to clarify intent.
- Extract cache configuration to a separate module for reusability.

### What's Done Well

- Clear separation of concerns between request handling and caching.
- Comprehensive unit tests for cache hit path.

### Verification Story

- Tests reviewed: yes – 85% coverage, missing edge cases.
- Build verified: yes – `npm run build` passes.
- Security checked: no – requires input sanitisation.

Summary

The code-reviewer persona in the agent-skills repository demonstrates a sophisticated approach to AI agent design through these key architectural principles:

• Separation of concerns: Persona identity (agents/code-reviewer.md) remains distinct from execution logic (skills/code-review-and-quality/SKILL.md), enabling modular skill reuse across different agent personalities.
• Structured methodology: The five-axis review process (Correctness, Readability, Architecture, Security, Performance) ensures comprehensive coverage of code quality dimensions.
• Deterministic output: Strict template enforcement in the persona definition guarantees consistent, actionable review formats regardless of input variability.
• Intent-based routing: The AGENTS.md mapping system allows the OpenCode engine to route code review requests to the appropriate skill framework automatically.

Frequently Asked Questions

What makes the code-reviewer persona different from other agent personas?

The code-reviewer persona is distinguished by its strict five-axis methodology and categorized severity system (Critical, Important, Suggestion). While other personas might focus on creative generation or data analysis, the code-reviewer implements a deterministic quality gate process defined in skills/code-review-and-quality/SKILL.md, making it functionally equivalent to a senior engineer performing systematic pull request reviews.

How does the code-reviewer handle security vulnerabilities?

Security analysis follows the Security axis defined in the review framework, leveraging additional depth from skills/security-and-hardening/SKILL.md when needed. The persona specifically categorizes security findings as Critical Issues if they represent injection risks or validation gaps, and includes a mandatory "Security checked" field in the Verification Story section to document whether input sanitization and vulnerability scanning were verified.

Can the code-reviewer persona be customized for specific languages or frameworks?

Yes, the modular architecture allows for customization through the skill layer. While the base persona in agents/code-reviewer.md defines the universal review structure, the specific checklists and anti-patterns in skills/code-review-and-quality/SKILL.md can be extended or overridden to include language-specific linters, framework conventions, or domain-specific security concerns without modifying the core persona identity.

Where is the review output template defined?

The output template is defined in agents/code-reviewer.md【/cache/repos/github.com/addyosmani/agent-skills/main/agents/code-reviewer.md】, which specifies the exact Markdown structure including the Review Summary, Critical Issues, Important Issues, Suggestions, What's Done Well, and Verification Story sections. This template enforcement ensures that every review produced by the persona maintains consistent formatting and completeness standards.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}