Caveman Skill for Compressed Code Review: Ultra-Terse PR Feedback

TLDR: The caveman-review skill is a prompt-only plugin that converts verbose code reviews into single-line, token-efficient comments using the strict format L<line>: <severity> <problem>. <fix>., reducing output token usage by approximately 65%.

The JuliusBrussee/caveman repository provides a minimalist approach to AI-assisted development through the caveman-review skill. This Caveman skill for compressed code review transforms traditional multi-sentence PR feedback into ultra-concise, actionable single-line directives that agents like Claude Code, Gemini, and Cursor can generate and parse with minimal token overhead. Unlike traditional review tools that generate paragraphs of explanation, this implementation lives entirely in skill definition files and relies on pure prompt engineering to enforce brevity.

How the Caveman Review Skill Works

The implementation consists of two complementary files that register the skill with any compatible agent and define the compression rules.

Skill Definition in SKILL.md

The core logic resides in skills/caveman-review/SKILL.md, which serves as the prompt template for the LLM. This file instructs the agent to scan the current diff or explicit file lists and emit findings using a strict single-line format. According to the source code, the skill mandates the pattern L<line>: <severity> <problem>. <fix>. and explicitly forbids filler phrases such as "I think…" or "Great work!" that typically bloat token counts.

Command Registration

The second component, src/plugins/opencode/commands/caveman-review.md, registers the /caveman-review slash command within the agent interface. When invoked, the agent loads the skill definition from the skills/ directory and executes the review logic without running any compiled binary. This skill-registry model ensures the plugin remains language-agnostic and trivially updatable by editing markdown files rather than recompiling code.

The Compressed Review Format

The Caveman skill enforces a rigid structure that prioritizes data density over natural language flow.

Single-Line Syntax

Each issue must occupy exactly one line following the format L<line>: <severity> <problem>. <fix>.. For multi-line ranges, the syntax becomes L<start>-<end>:. The skill automatically drops any content that does not conform to this pattern, including introductory clauses and concluding remarks. When the agent encounters security or architectural concerns that require explanation, an auto-clarity switch temporarily allows full paragraphs before resuming the terse mode for remaining issues.

Severity Emoji System

The format supports optional emoji prefixes to provide immediate visual categorization:

• 🔴 Critical (bugs)
• 🟡 Warn (risks)
• 🔵 Nit (style issues)
• ❓ Question (unclear intent)

These single-character indicators replace entire sentences of severity explanation, contributing to the token reduction while maintaining scanability.

Using the Caveman-Review Command

Activate the skill in any supported agent environment that can load skills from the skills/ directory.

Review the current staged changes:

/caveman-review

Review specific files or patterns:

/caveman-review src/*.js

Sample Output

The command produces output ready for direct paste into PR comments:

L42: 🔴 bug: user can be null after .find(). Add guard before .email.
L88-140: 🔵 nit: 50‑line function does 4 things. Extract validate/normalize/persist.
L23: 🟡 risk: no retry on 429. Wrap in withBackoff(3).

Each line contains the exact line number, severity classification, identified problem, and concrete fix—eliminating the need for additional context or prose.

Token Efficiency and Performance

By collapsing multi-sentence reviews into single-line directives, the caveman-review skill achieves approximately 65% reduction in output token usage compared to standard verbose review prompts. The only additional cost is the few hundred input tokens required to load the skill definition initially. This efficiency makes the skill particularly effective for large-scale reviews where token limits or latency constraints apply. The drop-list mechanism—explicitly filtering filler sentences—ensures that every output token carries actionable information.

Summary

• The caveman-review skill lives in skills/caveman-review/SKILL.md and src/plugins/opencode/commands/caveman-review.md as pure prompt text with no runtime dependencies.
• Output format requires L<line>: <severity> <problem>. <fix>. with optional emoji severity tags (🔴, 🟡, 🔵, ❓).
• The /caveman-review command integrates with Claude Code, Gemini, Cursor, and other agents supporting the skill-registry model.
• Token usage drops by roughly 65% through the elimination of filler phrases and forced single-line constraint.
• An auto-clarity switch allows temporary expansion for complex architectural feedback before returning to compressed mode.

Frequently Asked Questions

How do I install the caveman-review skill in my agent?

Copy the skills/caveman-review/ directory from the JuliusBrussee/caveman repository into your agent's skill path, or reference the INSTALL.md file for agent-specific integration matrices. The skill requires no compilation or package installation since it consists entirely of markdown prompt definitions.

Can I customize the severity levels or output format?

Yes. Because the skill is defined in plain-text SKILL.md, you can modify the severity emojis, adjust the line-number syntax, or add new categories by editing the rules section. Changes take effect immediately upon reloading the skill without restarting the agent.

What happens when the review requires detailed explanation?

The skill includes an auto-clarity switch that detects when an issue involves security vulnerabilities or architectural concerns requiring elaboration. In these cases, the agent writes a full paragraph for that specific issue, then resumes the standard L<line>: format for subsequent findings, balancing token efficiency with necessary depth.

Does this work with all programming languages?

Yes. The caveman-review skill is language-agnostic because it operates on diff text and file content rather than language-specific parsers. The LLM interprets the code based on the provided files, making the skill effective for JavaScript, Python, Rust, Go, or any codebase that produces text-based diffs.

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