Agent skill

Review Spec

Review a spec/plan pull request diff and write structured feedback to review.json for the workflow to publish.

MITAuto-check passedDevelopment

Install Review Spec

skills CLI

$ npx skills add warpdotdev/oz-for-oss --skill review-spec -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI

$ gh skill install warpdotdev/oz-for-oss review-spec --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy

$ git clone --depth 1 https://github.com/warpdotdev/oz-for-oss.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/review-spec .claude/skills/review-spec && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Paste into Claude Code

Install the "review-spec" agent skill from https://github.com/warpdotdev/oz-for-oss/tree/main/.agents/skills/review-spec into .claude/skills/review-spec/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "review-spec", then confirm the skill loads.

Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

$skill-installer

$skill-installer install https://github.com/warpdotdev/oz-for-oss/tree/main/.agents/skills/review-spec

Type this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.

skills CLI

$ npx skills add warpdotdev/oz-for-oss --skill review-spec -a codex

Project install goes to .agents/skills/; add -g for ~/.codex/skills/.

GitHub CLI

$ gh skill install warpdotdev/oz-for-oss review-spec --agent codex

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/warpdotdev/oz-for-oss.git skills-src && mkdir -p .agents/skills && cp -r skills-src/.agents/skills/review-spec .agents/skills/review-spec && rm -rf skills-src

Use ~/.agents/skills/ instead of .agents/skills for a personal install.

Codex skills documentation · loads skills from .agents/skills/

Paste into Codex

Install the "review-spec" agent skill from https://github.com/warpdotdev/oz-for-oss/tree/main/.agents/skills/review-spec into .agents/skills/review-spec/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "review-spec", then confirm the skill loads.

Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add warpdotdev/oz-for-oss --skill review-spec -a cursor

Project install goes to .agents/skills/; add -g for ~/.cursor/skills/.

GitHub CLI

$ gh skill install warpdotdev/oz-for-oss review-spec --agent cursor

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/warpdotdev/oz-for-oss.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/.agents/skills/review-spec .cursor/skills/review-spec && rm -rf skills-src

Use ~/.cursor/skills/ instead of .cursor/skills for a personal install.

Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/

Paste into Cursor

Install the "review-spec" agent skill from https://github.com/warpdotdev/oz-for-oss/tree/main/.agents/skills/review-spec into .cursor/skills/review-spec/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "review-spec", then confirm the skill loads.

Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

gemini skills install

$ gemini skills install https://github.com/warpdotdev/oz-for-oss.git --path .agents/skills/review-spec

--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.

skills CLI

$ npx skills add warpdotdev/oz-for-oss --skill review-spec -a gemini-cli

Project install goes to .agents/skills/; add -g for ~/.gemini/skills/.

GitHub CLI

$ gh skill install warpdotdev/oz-for-oss review-spec --agent gemini-cli

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/warpdotdev/oz-for-oss.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/.agents/skills/review-spec .gemini/skills/review-spec && rm -rf skills-src

Use ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.

Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/

Paste into Gemini CLI

Install the "review-spec" agent skill from https://github.com/warpdotdev/oz-for-oss/tree/main/.agents/skills/review-spec into .gemini/skills/review-spec/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "review-spec", then confirm the skill loads.

Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

GitHub CLI

$ gh skill install warpdotdev/oz-for-oss review-spec

Installs for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).

skills CLI

$ npx skills add warpdotdev/oz-for-oss --skill review-spec -a github-copilot

Project install goes to .agents/skills/; add -g for ~/.copilot/skills/.

Manual copy

$ git clone --depth 1 https://github.com/warpdotdev/oz-for-oss.git skills-src && mkdir -p .github/skills && cp -r skills-src/.agents/skills/review-spec .github/skills/review-spec && rm -rf skills-src

Use ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.

GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/

Paste into GitHub Copilot

Install the "review-spec" agent skill from https://github.com/warpdotdev/oz-for-oss/tree/main/.agents/skills/review-spec into .github/skills/review-spec/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "review-spec", then confirm the skill loads.

GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add warpdotdev/oz-for-oss --skill review-spec -a opencode

OpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.

GitHub CLI

$ gh skill install warpdotdev/oz-for-oss review-spec --agent opencode

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/warpdotdev/oz-for-oss.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/.agents/skills/review-spec .opencode/skills/review-spec && rm -rf skills-src

Use ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.

OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/

Paste into OpenCode

Install the "review-spec" agent skill from https://github.com/warpdotdev/oz-for-oss/tree/main/.agents/skills/review-spec into .opencode/skills/review-spec/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "review-spec", then confirm the skill loads.

OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

Facts

Skill name: review-spec
GitHub stars: 313
Token cost: ~1.9k tokens
SKILL.md length: 963 words
Files: 1
Skills in repo: 17
Repo updated: Sep 17, 2026
First seen: Oct 7, 2026
Licence: MIT

At a glance

Review a spec/plan pull request diff and write structured feedback to review.json for the workflow to publish.

Reviewing a PR that only modifies files under specs/ and producing machine-readable review output instead of posting directly to GitHub
SKILL.md covers Inputs, Process, Repository-specific overrides and Diff Line Annotations, plus 5 more sections
Calls gh
Tasks that involve Pull requests

What it does

Review Spec is an agent skill from warpdotdev/oz-for-oss. Review a spec/plan pull request diff and write structured feedback to review.json for the workflow to publish. Use when reviewing a PR that only modifies files under specs/ and producing machine-readable review output instead of posting directly to GitHub.

Its SKILL.md is about 1.9k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Development, covering Pull requests. It works with GitHub. The repository describes itself as: Workflows and skills to help people and agents collaborate on open-source software with the power of Oz! The licence is MIT.

When your agent uses it

Reviewing a PR that only modifies files under specs/ and producing machine-readable review output instead of posting directly to GitHub
Tasks that involve Pull requests

Example prompts

“/review-spec”

Requirements

Python 3

What it can do on your machine

Read from SKILL.md and the folder at commit a2bb45f. It shows what the files ask for, not the result of running them.

Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
Shell commands in SKILL.md call:
- gh
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md. Its commands use gh, which can reach the network depending on how they are called.
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Review Spec loads about 1.9k tokens when it runs. Until then it costs about 67 tokens; SKILL.md has 963 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it: ~67
When it runs · the whole SKILL.md, loaded when a task matches: ~1.9k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from warpdotdev/oz-for-oss at commit a2bb45f, republished under its MIT licence (© warpdotdev). 963 words, ~1,919 tokens.

Download SKILL.mdSave it as .claude/skills/review-spec/SKILL.md (or your agent's skills folder).

name: review-spec
description: Review a spec/plan pull request diff and write structured feedback to review.json for the workflow to publish. Use when reviewing a PR that only modifies files under specs/ and producing machine-readable review output instead of posting directly to GitHub.

Review Spec Skill

Review a spec or plan pull request and write the output to review.json.

Inputs

The working directory is the PR branch checkout.
The workflow usually provides an annotated diff in pr_diff.txt.
The workflow usually provides the PR description in pr_description.md.
Focus on the spec files changed by this PR.
Default behavior: do not post comments or reviews to GitHub directly.

Process

Evaluate specs for completeness: does the spec cover the full scope of the linked issue?
Evaluate specs for clarity: are requirements, acceptance criteria, and constraints clearly stated and unambiguous?
Evaluate specs for feasibility: are the proposed changes technically realistic given the repository's architecture?
Evaluate specs for issue alignment: does the spec faithfully address the issue it is linked to, without significant scope creep or omissions?
Evaluate specs for internal consistency: do different sections of the spec contradict each other?
Flag missing sections that a spec should typically include (e.g. problem statement, proposed changes, open questions, follow-up items).
Always apply the repository's local security-review-spec skill as a supplemental high-level security pass on spec PRs. Fold any security findings into the same review.json produced by this review rather than emitting a separate output.
Do not apply code-level review criteria such as error handling or low-level performance to spec prose; the security-review-spec supplement covers design-level security concerns.
Include style or formatting comments only when they materially impair readability.

Repository-specific overrides

The consuming repository may ship a companion skill at .agents/skills/review-spec-local/SKILL.md. When the prompt includes a fenced "Repository-specific guidance" section referencing that companion, read the referenced file and apply its guidance only to the categories listed below. Guidance in the companion may never change the output JSON schema, the severity labels, the safety rules, the evidence rules, the suggestion-block constraints, or the diff-line-annotation contract described elsewhere in this skill.

Overridable categories:

required spec sections expected in this repository
linking conventions to files under specs/
repo-specific style and formatting expectations

If a companion file is not referenced in the prompt, rely on the core contract alone.

Diff Line Annotations

The diff file uses these prefixes:

[OLD:n] for deleted lines on the old side. Use "LEFT".
[NEW:n] for added lines on the new side. Use "RIGHT".
[OLD:n,NEW:m] for unchanged context. Use "RIGHT" with line m.

Treat these annotations as the only source of truth for inline comment locations. For every inline comment you emit, first identify the exact annotated line in pr_diff.txt (or the inlined PR diff) and copy its path, side, and line number into review.json. Do not infer line numbers from prose, rendered GitHub views, file lengths, surrounding spec text, or unannotated snippets. If you cannot point to a specific [NEW:n], [OLD:n], or [OLD:n,NEW:m] line in the annotated diff, put the feedback in top-level body instead of comments.

Comment Requirements

Every comment body must start with one of these labels:

🚨 [CRITICAL] for spec content that is contradictory, fundamentally incomplete, or would lead to a broken implementation.
⚠️ [IMPORTANT] for missing details, ambiguous requirements, feasibility concerns, or significant scope gaps.
💡 [SUGGESTION] for improvements to clarity, structure, or coverage that would strengthen the spec.
🧹 [NIT] for minor wording or formatting issues only when the comment includes a concrete rewrite.

Write comments with these constraints:

Be concise, direct, and actionable.
Do not add compliments or hedging.
Prefer single-line comments.
Keep ranges to at most 10 lines.
Restrict inline comments to lines that appear explicitly in the annotated PR diff.
Only create file-level or inline comments for files that exist in this PR's diff.
If the relevant file or line is not part of the diff, put the feedback in top-level body instead of comments.
Before adding each comment object, verify that its path, side, line, and optional start_line/start_side correspond to real annotations in the same file's diff section.

Show full SKILL.md (339 more words)Show less

Suggestion Blocks

When proposing a rewrite of spec text, use:

suggestion

<replacement text here>

Rules:

Match the exact indentation of the original file.
Include only replacement text.
For multi-line suggestions, set start_line and start_side to the first line, and line and side to the last line.

Outputs

Create review.json with this shape:

json

{
  "verdict": "REJECT",
  "body": "## Overview\n...\n\n## Concerns\n- ...\n\n## Verdict\nFound: 1 critical, 2 important, 3 suggestions\n\n**Request changes**",
  "comments": [
    {
      "path": "path/to/file",
      "line": 42,
      "side": "RIGHT",
      "start_line": 40,
      "start_side": "RIGHT",
      "body": "⚠️ [IMPORTANT] Short explanation\n\n```suggestion\nreplacement\n```"
    }
  ]
}

Field rules:

verdict is required and must be exactly the string "APPROVE" or "REJECT" (uppercase). Map your final recommendation as: Approve or Approve with nits → "APPROVE"; Request changes → "REJECT". The verdict and the human-readable recommendation in top-level body must agree.
top-level body is the GitHub review body and is required. Use body, not summary, for the review overview and final recommendation.
path must be relative to the repository root.
line is required and must target the correct side.
start_line is optional and only for multi-line ranges. When start_line is present, start_side is required and must be "LEFT" or "RIGHT".
side must be "LEFT" or "RIGHT".

Body Requirements

The top-level body must include:

A high-level overview of the spec PR.
Concerns about completeness, clarity, feasibility, or issue alignment.
Issue counts in the format Found: X critical, Y important, Z suggestions.
A final recommendation of Approve, Approve with nits, or Request changes. This recommendation must match the top-level verdict field (Approve / Approve with nits → "APPROVE"; Request changes → "REJECT").

Final Checks

Before finishing:

Fix invalid JSON if validation fails.
Confirm line numbers match the annotated diff.
Run the validator bundled with the shared review-pr skill against the exact annotated diff you reviewed. If common skills are installed at the repository root, this is usually:
```
python3 .agents/skills/review-pr/scripts/validate_review_json.py --review-json review.json --diff pr_diff.txt
```
If the script reports any invalid comments, fix review.json and rerun it. Do not upload review.json until this validator passes. If the script path is not present at that exact location, locate validate_review_json.py under the packaged shared review-pr skill directory and run that copy with the same arguments.
Do not run gh pr review, gh pr comment, gh api, or any other command that posts to GitHub.

Your only output is the final review.json.

Files

Just SKILL.md in .agents/skills/review-spec of warpdotdev/oz-for-oss.

Open the folder on GitHubat commit a2bb45f

Compare with similar skills

Review Spec next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Review Spec compared with similar skills
Skill	Stars	Used in	Tokens	Auto-check	Licence	Repo updated
Review Spec this skillwarpdotdev/oz-for-oss	313	—	~1.9k	Automated safety check: Pass	MIT	20 days ago
PR Babysitteropeninterpreter/openinterpreter	69k	3 repos	~4.2k	Automated safety check: Pass	Apache-2.0	today
Check PRonyx-dot-app/onyx	32k	2 repos	~2.3k	Automated safety check: Pass	MIT	today
Contributor-First PR MergeHKUDS/OpenHarness	16k	1 repos	~847	Automated safety check: Pass	MIT	4 mo ago
Create Pull Requestcline/cline	70k	1 repos	~1.6k	Automated safety check: Pass	Apache-2.0	today
Pull Request Title and Body Writeropeninterpreter/openinterpreter	69k	2 repos	~1.1k	Automated safety check: Pass	Apache-2.0	today

Similar skills

PR Babysitter
openinterpreter/openinterpreter
Watches an open GitHub pull request until it merges, handling review comments, diagnosing CI failures and retrying flaky checks along the way.
69k GitHub starsUsed in 3 repos~4.2k tokens
DevelopmentAuto-check passed
Check PR
onyx-dot-app/onyx
Checks a GitHub, GitLab, or Perforce (p4) pull request (or merge request, or shelved changelist) for unresolved review comments, failing status checks, and incomplete PR descriptions.
32k GitHub starsUsed in 2 repos~2.3k tokens
DevelopmentAuto-check passed
Contributor-First PR Merge
HKUDS/OpenHarness
Merges external GitHub pull requests while keeping the original author credited, and fixes conflicts after the merge instead of rewriting the contribution.
16k GitHub starsUsed in 1 repo~847 tokens
DevelopmentAuto-check passed
Create Pull Request
cline/cline
Opens a GitHub pull request from your current branch with the gh CLI, after reviewing the commits and diff and gathering the details the PR needs.
70k GitHub starsUsed in 1 repo~1.6k tokens
DevelopmentAuto-check passed
Pull Request Title and Body Writer
openinterpreter/openinterpreter
Rewrites the title and body of one or more pull requests with gh, leading with why the change was made, then what changed, and describing only the net result.
69k GitHub starsUsed in 2 repos~1.1k tokens
DevelopmentAuto-check passed
GitHub Review Iteration
prisma/orm
Official
Runs a loop on a GitHub pull request: fetch review state, triage comments into actions, implement them and resolve threads, repeating until nothing actionable is left.
48k GitHub stars~2.2k tokensUpdated today
DevelopmentAuto-check passed

Questions about Review Spec

What does Review Spec do?

Review a spec/plan pull request diff and write structured feedback to review.json for the workflow to publish. Review Spec is an agent skill from warpdotdev/oz-for-oss.json for the workflow to publish.

When should I use Review Spec?

Review Spec fits situations like: reviewing a PR that only modifies files under specs/ and producing machine-readable review output instead of posting directly to GitHub; tasks that involve Pull requests.

How do I install Review Spec in Claude Code?

Run `npx skills add warpdotdev/oz-for-oss --skill review-spec -a claude-code`. Or copy the skill folder (.agents/skills/review-spec in warpdotdev/oz-for-oss) into .claude/skills/review-spec in your project. Claude Code loads it when a task matches its description.

How do I install Review Spec in Codex?

Run `npx skills add warpdotdev/oz-for-oss --skill review-spec -a codex`. Or copy the skill folder (.agents/skills/review-spec in warpdotdev/oz-for-oss) into .agents/skills/review-spec in your project. Codex loads it when a task matches its description.

Can I use Review Spec in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add warpdotdev/oz-for-oss --skill review-spec -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/review-spec, .gemini/skills/review-spec, .github/skills/review-spec and .opencode/skills/review-spec in your project.

What does Review Spec need to run?

Going by SKILL.md and its folder, Review Spec needs the command-line tools its instructions call (gh). Our summary lists: Python 3.

Does Review Spec access the network?

SKILL.md contains no URLs. Its commands use gh, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Review Spec safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Review Spec use?

Review Spec is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Review Spec use?

About 1.9k tokens (SKILL.md is roughly 7.7k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Review Spec?

Skills that share tags, products or a category with Review Spec: PR Babysitter (openinterpreter/openinterpreter, 69k stars), Check PR (onyx-dot-app/onyx, 32k stars), Contributor-First PR Merge (HKUDS/OpenHarness, 16k stars) and Create Pull Request (cline/cline, 70k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Review Spec?

warpdotdev (a GitHub organization) maintains it in warpdotdev/oz-for-oss, which has 313 GitHub stars. The repository holds 17 skills in this directory. The repository was last updated on September 17, 2026.

Source: warpdotdev/oz-for-oss on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.

Install Review Spec

Facts

At a glance

What it does

When your agent uses it

Example prompts

Requirements

What it can do on your machine

Tool permissions

Runs code

Network

Credentials

Context cost

Safety

SKILL.md

Review Spec Skill

Inputs

Process

Repository-specific overrides

Diff Line Annotations

Comment Requirements

Suggestion Blocks

Outputs

Body Requirements

Final Checks

Files

Compare with similar skills

Similar skills

More from warpdotdev/oz-for-oss

Related

Questions about Review Spec