zjuncher/mr-agent/usage-guide

Project Review Skill

Summary

Project Review Skill lets each GitLab project own declarative review rules for /review and /improve without copying or replacing PR-Agent's global prompts. A project opts in by committing one validated manifest to its target branch; PR-Agent pins that manifest and its referenced Markdown files to the exact target-branch SHA used by the command.

The Skill is project context, not executable code. It cannot add tools, run commands, change output schemas, weaken global safety rules, or grant the model additional repository permissions.

Source of truth

Responsibility

Project Review Skill is responsible for:

• expressing project-specific review expectations;
• selecting rules by command, language, changed path, and exclusion path;
• loading explicitly referenced project facts under a fixed character budget;
• providing immutable target SHA, Skill hash, selected rule IDs, matched files, and Reference hashes;
• connecting real suggestion outcomes and review feedback to the Skill version that was actually used;
• proposing evidence-backed Skill changes through project-owned Draft MRs.

It is not responsible for:

• replacing global prompts or their output schemas;
• executing repository scripts, tests, tools, or shell commands;
• creating a project's initial Skill;
• changing references/*.md automatically;
• approving or merging an evolution MR;
• defining CODEOWNERS or project permissions.

Opt-in layout

The project owner creates this fixed structure in the project's default or reviewed target branch:

.pr_agent/skills/review/
├── skill.toml
└── references/
    ├── architecture.md
    └── api-compatibility.md

Only skill.toml is required. The absence of that file means the project has not opted in; PR-Agent keeps its existing global behavior.

PR-Agent never creates the initial file. This makes repository ownership explicit and prevents feedback from an arbitrary project from granting the bot a new writable policy surface.

Manifest schema

schema_version = 1
name = "example-review"
project = "example-group/example-project"
description = "Cook project review rules"
 
[[rules]]
id = "api-compatibility"
targets = ["review", "improve"]
languages = ["cpp"]
paths = ["src/**"]
exclude_paths = ["src/generated/**"]
instruction = "Public API changes must preserve backward compatibility."
references = ["references/api-compatibility.md"]
 
[[rules]]
id = "realtime-no-blocking-io"
targets = ["review", "improve"]
paths = ["src/realtime/**"]
instruction = "Realtime threads must not perform blocking IO."

Top-level fields

Unknown top-level fields are rejected. This prevents a misspelled or future-looking field from silently appearing to work.

Rule fields

Unknown rule fields are rejected. In particular, script, command, validation, tool, and similar executable fields are not part of the schema.

Glob semantics

• * matches characters inside one path segment: src/* matches src/a.py, but not src/pkg/a.py.
• ** crosses directory boundaries: src/** matches both src/a.py and src/pkg/a.py.
• ? matches one non-separator character.
• Paths are repository-relative POSIX paths. Absolute paths, empty segments, . and .. are rejected.
• A file must match at least one paths pattern when paths is present.
• A matching exclude_paths pattern always wins.

Example: a rule with paths = ["src/realtime/**"] and exclude_paths = ["src/realtime/generated/**"] applies to src/realtime/loop.cc, but not src/realtime/generated/messages.cc.

Reference contract

• A Reference must use references/<name>.md.
• Absolute paths, traversal, non-Markdown files, and files outside the fixed directory are rejected.
• References are loaded only when a rule that cites them is selected.
• Manifest and References are read at the same target SHA.
• At most 10 distinct References are selected.
• Loaded Reference text is clipped to a deterministic total budget of 20,000 characters; provenance records clipping and hashes the original content.
• Reference text is labeled as controlled user context. It cannot override system instructions, schemas, safety rules, or tool permissions.

Runtime call flow

1. PR-Agent identifies the GitLab project, MR target branch, current target-branch head SHA, changed files, and language route.
2. It reads .pr_agent/skills/review/skill.toml at that exact SHA, not from the MR source branch.
3. It validates TOML, project identity, schema, sizes, paths, references, IDs, targets, and languages.
4. It selects rules for review or improve, then filters by language and file path.
5. It loads only References used by selected rules, at the same SHA.
6. It computes an immutable Effective Skill and appends it to the user prompt below an explicit trust-boundary notice.
7. It reuses that Skill session through every internal /improve stage: generation, reflection, scenario validation, inline self-check, de-conflict, and Tier-1 repair.
8. It records the target SHA, Skill/Manifest hash, selected rules, matched files, Reference hashes, status, and final prompt bundle.

For a mixed Python/C++ MR, PR-Agent still performs its existing language routing. Each model leg receives only the language-compatible subset of the same target-SHA Skill session.

Why source-branch edits cannot affect the current MR

Assume the target branch main points to SHA A, while an MR source branch adds a malicious Skill at SHA B.

PR-Agent resolves main -> A, then calls the repository Files API with ref=A. It never asks for ref=B or the source branch name. The malicious Skill can be reviewed as ordinary Diff content, but it affects reviews only after maintainers merge it and it becomes part of a later target-branch SHA.

Rollout modes

Configure project_review_skill.rollout_mode in PR-Agent:

The repository default is review_and_improve. This remains opt-in per project because a valid target-branch skill.toml is still required.

An unknown rollout value is treated as disabled.

Failure behavior

Fail-open here means review availability is preserved by falling back to the trusted global prompt. It does not mean invalid project rules are partially accepted.

Provenance and feedback

Published /improve suggestions persist these fields in published_suggestions:

• global_prompt_set_hash, legacy-compatible project_rules_hash, and final prompt_bundle_hash;
• explicit project_skill_hash, project_skill_manifest_hash, and project_skill_target_sha;
• load status, selected rule IDs, matched files, and Reference hashes.

/review stores the same Skill identity in project_skill_usages under the hidden review_id. A later /feedback rating joins to that immutable usage record. Ratings 1-2 become negative project evidence, ratings 4-5 become positive control evidence, and rating 3 remains neutral/pending. Runs with no selected rule or a non-loaded Skill are excluded from Skill evolution.

Evidence from different Skill/Prompt bundles is not mixed. A target Manifest change produces a new hash and supersedes proposals derived from the old version.

Self-evolution lifecycle