Skip to content

Refactor /review-pr into a reusable pr-review skill #32

Description

@dceoy

Problem

The complete pull request review workflow currently lives in .opencode/commands/review-pr.md.

OpenCode custom commands are prompt entry points that run only when explicitly invoked, whereas agent skills are reusable instructions discovered and loaded on demand through the native skill tool. Keeping the implementation exclusively in the command prevents other agents or commands from reusing the review workflow without duplicating its prompt.

Goal

Make the PR review workflow reusable by moving its canonical implementation into an OpenCode skill while preserving /review-pr as a thin, backward-compatible command entry point.

Proposed structure

.opencode/
├── commands/
│   └── review-pr.md
└── skills/
    └── pr-review/
        └── SKILL.md

The skill should use valid OpenCode skill frontmatter:

---
name: pr-review
description: Review a GitHub pull request with stale-head protection and validated inline findings
---

The command should contain only the command metadata, argument forwarding, and an explicit instruction to load and follow the skill, for example:

---
description: Comprehensive GitHub PR review with stale-head protection and inline findings.
agent: build
---

Load and follow the `pr-review` skill.

Requested review aspects: "$ARGUMENTS"

The exact wrapper wording may differ, but it must not duplicate the workflow implementation.

Requirements

  • Move the canonical review instructions from .opencode/commands/review-pr.md to .opencode/skills/pr-review/SKILL.md.
  • Keep .opencode/commands/review-pr.md as a minimal wrapper so existing /review-pr usage remains available.
  • Preserve all current behavior, including:
    • GitHub App token preparation.
    • PR number resolution and local-mode fallback.
    • Pinning headRefOid and rejecting stale-head reviews.
    • Aspect-based reviewer selection and parallel delegation.
    • Normalization, deduplication, and changed-line anchor validation.
    • Summary-only handling for unanchorable findings.
    • Batched inline review submission through review-pr-submit.sh only.
    • The exact no-findings result.
    • Read-only behavior for /review-pr simplify.
  • Ensure the build agent is permitted to use the pr-review skill if skill permissions are restricted in opencode.json.
  • Keep one canonical copy of the workflow; do not retain duplicated instructions in the command and skill.
  • Update relevant documentation and validation fixtures if they reference the command file as the implementation source.
  • Format changed Markdown with the repository's configured formatter.

Acceptance criteria

  • /review-pr, /review-pr security, and /review-pr simplify retain their existing observable behavior.
  • An agent can load pr-review directly through the native skill tool without invoking the slash command.
  • The command file is a thin wrapper and the skill is the sole canonical workflow definition.
  • Inline review submission, stale-head protection, and local-mode behavior continue to work.
  • simplify produces proposals only and never edits or commits files.
  • Existing checks pass and no duplicate review comments or alternative write paths are introduced.

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions