Write a reviewer skill

A reviewer skill is a Markdown file with YAML frontmatter. The frontmatter identifies the skill and can define structured rules, path matching, story structure, and narrowly scoped capabilities. The Markdown body can provide freeform review guidance.

Create a project skill when the review belongs to the repository:

ev skills create frontend-review

This creates .ev/skills/frontend-review.md. Project skills are versioned with the codebase. Put a personal skill in ~/.fiberplane/ev/skills/ instead.

Anatomy of a skill

This example reviews frontend changes and activates different instructions for React and CSS files:

---
name: frontend-review
description: Review frontend changes for accessibility and theme consistency.
include:
  - "apps/web/**/*.tsx"
  - "apps/web/**/*.css"
exclude:
  - "**/*.test.tsx"
review:
  rules:
    - id: accessible-interactions
      instruction: Check interactive elements for keyboard and accessible-name support.
      when:
        globs:
          - "**/*.tsx"
    - id: theme-token-parity
      instruction: Check that new colors use theme tokens and work in every supported theme.
      when:
        globs:
          - "**/*.css"
story:
  structure: Lead with user-visible regressions, then list lower-risk improvements.
---

Field	Purpose
name	Stable identifier used by --skill. It normally matches the filename.
description	Short explanation shown by ev skills list and used to distinguish the skill from neighboring reviewers.
include	Changed-file globs that make --auto select this skill.
exclude	Matching files to ignore during automatic selection.
review.rules	One or more focused instructions for the reviewer.
rules[].id	Stable, unique name for a rule.
rules[].when.globs	Changed-file globs that decide whether that individual rule is included in the review.
story.structure	Optional guidance for the readable review narrative produced by EV.

Keep rules concrete: state what to verify and what evidence constitutes a problem. Avoid repeating general code-review advice that another selected skill already provides.

Trigger a skill from changed files

Run automatic selection with:

ev review -b origin/main --stream --auto

EV compares the files in the review scope with each skill’s top-level include and exclude patterns. In the example above, a change under apps/web/ to a .tsx or .css file selects frontend-review, except when the only match is an excluded .test.tsx file.

Use top-level patterns to answer when should EV choose this skill? Use when.globs inside a rule to answer which instructions from the chosen skill apply to this change?

You can inspect the resolved patterns and source before running a review:

ev skills show frontend-review

Select a skill explicitly

Use --skill when you want a predictable review lens regardless of automatic suggestions:

ev review -b origin/main --desktop --skill frontend-review

Explicit selection chooses the skill, while each rule’s when.globs still keeps unrelated instructions out of the prompt. Rules without when.globs always apply when the skill is selected.

Freeform skills

For a small skill, omit review.rules and put the guidance below the frontmatter:

---
name: migration-review
description: Review database migrations for safe rollout and rollback behavior.
include:
  - "**/migrations/**"
---

Check whether the migration is safe for a rolling deployment. Verify that old
and new application versions can run during the transition, and call out any
operation that requires an explicit rollback plan.

Use structured rules when different instructions need different path gates or when rules should remain stable over time. Use a freeform body for one compact, indivisible review workflow.

Capabilities and evidence

Most reviewer skills only need repository and diff access. A skill that controls a browser or creates evidence must declare those capabilities and narrowly allow each command it needs. See Use reviewer skills for the evidence-producing pattern and Work with evidence for the resulting review UI.