> **behavioral-evals** — chapter 3 of 24 in [google-gemini/gemini-cli](https://skillsdocs.com/google-gemini/gemini-cli).
>
> Book (all chapters, one file): https://skillsdocs.com/google-gemini/gemini-cli.md
> Machine manifest: https://skillsdocs.com/google-gemini/gemini-cli/.well-known/agent-skills/index.json
> Install the book: `npx skills add google-gemini/gemini-cli`
> Upstream: https://github.com/google-gemini/gemini-cli/blob/main/.gemini/skills/behavioral-evals/SKILL.md @ `main`
> Raw bytes, no header: https://raw.githubusercontent.com/google-gemini/gemini-cli/main/.gemini/skills/behavioral-evals/SKILL.md
> Base for relative paths: https://raw.githubusercontent.com/google-gemini/gemini-cli/main/.gemini/skills/behavioral-evals/
> Licence: Apache-2.0 — https://spdx.org/licenses/Apache-2.0.html
>
> Bundled files (6), referenced from this skill's directory:
>   - `assets/interactive_eval.ts.txt` — https://raw.githubusercontent.com/google-gemini/gemini-cli/main/.gemini/skills/behavioral-evals/assets/interactive_eval.ts.txt
>   - `assets/standard_eval.ts.txt` — https://raw.githubusercontent.com/google-gemini/gemini-cli/main/.gemini/skills/behavioral-evals/assets/standard_eval.ts.txt
>   - `references/creating.md` — https://raw.githubusercontent.com/google-gemini/gemini-cli/main/.gemini/skills/behavioral-evals/references/creating.md
>   - `references/fixing.md` — https://raw.githubusercontent.com/google-gemini/gemini-cli/main/.gemini/skills/behavioral-evals/references/fixing.md
>   - `references/promoting.md` — https://raw.githubusercontent.com/google-gemini/gemini-cli/main/.gemini/skills/behavioral-evals/references/promoting.md
>   - `references/running.md` — https://raw.githubusercontent.com/google-gemini/gemini-cli/main/.gemini/skills/behavioral-evals/references/running.md
>
> Content © its authors, served unmodified. Takedown: https://github.com/kyleledbetter/skillsdocs/issues/new?labels=takedown&title=Takedown+request

<!-- Verbatim upstream SKILL.md follows, YAML frontmatter included. -->

---
name: behavioral-evals
description: Guidance for creating, running, fixing, and promoting behavioral evaluations. Use when verifying agent decision logic, debugging failures, debugging prompt steering, or adding workspace regression tests.
---

# Behavioral Evals

## Overview

Behavioral evaluations (evals) are tests that validate the **agent's decision-making** (e.g., tool choice) rather than pure functionality. They are critical for verifying prompt changes, debugging steerability, and preventing regressions.

> [!NOTE]
> **Single Source of Truth**: For core concepts, policies, running tests, and general best practices, always refer to **[evals/README.md](file:///Users/abhipatel/code/gemini-cli/docs/evals/README.md)**.

---

## 🔄 Workflow Decision Tree

1.  **Does a prompt/tool change need validation?**
    *   *No* -> Normal integration tests.
    *   *Yes* -> Continue below.
2.  **Is it UI/Interaction heavy?**
    *   *Yes* -> Use `appEvalTest` (`AppRig`). See **[creating.md](references/creating.md)**.
    *   *No* -> Use `evalTest` (`TestRig`). See **[creating.md](references/creating.md)**.
3.  **Is it a new test?**
    *   *Yes* -> Set policy to `USUALLY_PASSES`.
    *   *No* -> `ALWAYS_PASSES` (locks in regression).
4.  **Are you fixing a failure or promoting a test?**
    *   *Fixing* -> See **[fixing.md](references/fixing.md)**.
    *   *Promoting* -> See **[promoting.md](references/promoting.md)**.

---

## 📋 Quick Checklist

### 1. Setup Workspace
Seed the workspace with necessary files using the `files` object to simulate a realistic scenario (e.g., NodeJS project with `package.json`).
*   *Details in **[creating.md](references/creating.md)***

### 2. Write Assertions
Audit agent decisions using `rig.setBreakpoint()` (AppRig only) or index verification on `rig.readToolLogs()`.
*   *Details in **[creating.md](references/creating.md)***

### 3. Verify
Run single tests locally with Vitest. Confirm stability locally before relying on CI workflows.
*   *See **[evals/README.md](file:///Users/abhipatel/code/gemini-cli/docs/evals/README.md)** for running commands.*

---

## 📦 Bundled Resources

Detailed procedural guides:
*   **[creating.md](references/creating.md)**: Assertion strategies, Rig selection, Mock MCPs.
*   **[fixing.md](references/fixing.md)**: Step-by-step automated investigation, architecture diagnosis guidelines.
*   **[promoting.md](references/promoting.md)**: Candidate identification criteria and threshold guidelines.