Agents & Skills

Relevant source files

The following files were used as context for generating this wiki page:

• skills/marginalia-review/SKILL.md
• README.md
• PRODUCT.md
• examples/commands/triage.md
• studio/public/openapi.yaml
• CLAUDE.md
• studio/src/lib/api.ts

Marginalia executes user-defined Claude Code slash commands to automate code reviews and comment triage. The bot acts as a headless runner for these agents and skills, which reside in the project's .claude/ directory.

The system relies on the claude CLI to fetch merge request (MR) data through GitLab and Atlassian connectors. It produces structured reports that the local studio displays for developer review.

Sources: README.md:1-10, PRODUCT.md:21-25

Core Architecture

The system uses a polling mechanism to trigger headless Claude commands. The bot handles the environment, git worktrees, and report collection while the agent logic performs the actual analysis.

Execution Flow

1. The poller identifies new commits or comments on GitLab.
2. The bot checks out the MR branch in a dedicated worktree.
3. The bot spawns the claude CLI with specific slash commands (REVIEW_COMMAND or TRIAGE_COMMAND).
4. The agent writes a markdown report and a .marginalia-findings.json file.
5. The studio reads these files to present findings to the user.

Sources: README.md:36-45, README.md:105-115

The sequence above illustrates the automated trigger of Claude agents and the delivery of their verified findings to the studio.

Sources: README.md:144-155, PRODUCT.md:31-35

The Review Skill

The marginalia-review skill enables Claude to act as a senior engineer. It follows a strict protocol to ensure technical accuracy and relevance to the specific codebase.

Review Protocol

• Repository Learning: The agent reads CLAUDE.md, CONTRIBUTING, and local documentation to understand repo-specific conventions.
• Risk Assessment: The agent assigns a risk level (Low, Medium, or High) based on factors like blast radius and test coverage.
• Verification: The agent runs tests, type checks, and linters defined in the repository. It reports failures as evidence.
• Findings Generation: The agent produces postable comments categorized by severity.

Sources: skills/marginalia-review/SKILL.md:6-33, CLAUDE.md:3-5

Risk Levels

Level	Rationale
low	Contained changes, well covered by tests, no sensitive areas.
medium	Changes behavior in shared code or has thin test coverage.
high	Touches auth, payments, data, migrations, or public contracts.

Sources: skills/marginalia-review/SKILL.md:17-21, studio/src/lib/api.ts:46-50

The Triage Agent

The triage agent manages peer feedback on MRs authored by the user. It evaluates unresolved comments against the ticket requirements and the code diff.

Triage Logic

1. Fetch: Retrieves unresolved discussion threads from GitLab.
2. Classify: Decides if a comment is RELEVANT, NOT RELEVANT, or WRONG.
3. Act: Applies code fixes for relevant comments directly in the bot worktree.
4. Draft: Writes replies for comments that do not require code changes.

Sources: examples/commands/triage.md:7-12, README.md:120-130

The triage agent classifies feedback and automates the application of relevant fixes to a local-only git branch.

Sources: README.md:131-140, examples/commands/triage.md

Output and Reporting

Agents must adhere to a specific output contract to enable rich display features in the studio. Reports consist of two main parts: a Markdown narrative and structured JSON findings.

Findings Data Model

Each finding includes metadata that allows the studio to anchor comments to specific lines in the diff and track their status.

Field	Type	Description
id	string	Stable identifier across re-runs.
severity	string	critical, important, suggestion, or info.
path	string	Repository-relative file path.
line	integer	Line number in the new version of the file.
comment	string	Ready-to-post paragraph for the MR author.

Sources: README.md:46-55, studio/public/openapi.yaml:286-295

Severity Definitions

• critical: Blocks the merge (e.g., security holes, broken builds).
• important: Should be fixed (e.g., likely bugs, missing tests on risky logic).
• suggestion: Optional improvements.
• info: Questions or praise for well-implemented code.

Sources: skills/marginalia-review/SKILL.md:46-52, studio/src/lib/api.ts:80-85

Summary

Agents and skills form the intelligence layer of Marginalia. By leveraging headless Claude CLI commands, the system transforms raw code diffs and peer comments into structured, verified engineering reviews. These agents prioritize repo-specific standards over generic preferences and ensure all behavioral claims are verified through local test execution.

Sources: PRODUCT.md:21-25, skills/marginalia-review/SKILL.md:1-5