How to use the GitHub Deep Review agent skill

What is an agent skill?

An agent skill is a folder containing a SKILL.md file with instructions that an AI agent loads when your request matches the skill's description. The skill tells the agent how to work on one kind of task, which tools to use and what to report.

This skill is one folder, github-deep-review, with a SKILL.md file and an agents/openai.yaml file.

What the skill makes the agent do

The skill asks the agent to use the GitHub CLI (gh), not web browsing, to pull issue and PR details, comments, reviews, changed files and diffs. It then reads the surrounding code in a local repository, following the real call path from entrypoint to the owning module, and checks git history for where a bug came from.

Every review is meant to answer a fixed set of questions: what the bug is, the root cause if it can be found, whether the proposed fix is the best one, whether a larger refactor would help, what proof exists, and what remains unverified. The skill tells the agent to say "not proven" when the evidence is weak.

• Pulls issue and PR data with gh issue view and gh pr view, and diffs with gh pr diff.
• Inspects local repo state with git status, git fetch origin and git log.
• Searches the code for key symbols, errors, config or endpoints with rg.
• For PRs, leads with findings that include file, line or symbol references and a concrete failure mode.
• For regressions, separates the code author, introducing PR author, merger and current PR author, and labels provenance as clear, likely or unknown.

Install the skill

Download the ZIP for this skill from this page and unzip it. You can install it in one of two places.

For your user account, unzip it into ~/.claude/skills/ so the github-deep-review folder sits inside that directory. For a single project, unzip it into the project's .claude/skills/ folder instead.

In the Claude apps, you can upload the skill under Settings → Capabilities → Skills instead of copying files.

• Personal install: ~/.claude/skills/github-deep-review/
• Project install: <your-project>/.claude/skills/github-deep-review/
• Claude apps: Settings → Capabilities → Skills

Prepare your environment

The skill depends on several command-line tools. Install and check them before your first review. The skill expects gh to be authenticated to access the repository you are reviewing.

The skill also refers to a companion author-context skill at ~/Projects/agent-scripts/skills/github-author-context/SKILL.md. That file is not included in this download, so the author-context steps will not work as written unless you have it. Review work can still proceed without it.

• GitHub CLI (gh), authenticated with access to the target repository
• git
• ripgrep (rg)
• A local clone of the repository you want reviewed

Trigger the skill with natural requests

You do not need a special command. Describe the review you want in plain language and name the issue or PR number. Naming the local clone helps the agent find the code to read.

The skill is most useful when you ask for analysis rather than a summary. Ask about root cause, whether the fix is the best one, or whether the change introduced a regression.

• Review PR 456 in this repo. Is the proposed fix the best one, and what proof exists?
• Is issue 123 still a real bug on main, or was it already fixed?
• Triage issue 123: find the root cause and tell me what evidence is missing.
• Check when this regression was introduced and say unknown if the history does not prove it.

Read the output

Reviews follow a compact template. A PR review leads with findings and states whether there are blocking issues. If none are found, the output lists the strongest proof checked and the residual risk.

• Ref and Surface: the issue or PR and the affected area.
• Cause: code path and confidence.
• Provenance: introduced, made visible or carried forward by a commit or PR, or N/A or unknown.
• Best fix and Refactor: whether a larger change would help, and why.
• Proof and Risk: tests, CI, source or docs checked, and what is still uncertain.

Safety notes: scripts and network

This skill runs scripts and uses the network. It calls gh to read GitHub data, and it runs git fetch origin, which contacts your remote. Check the commands before you approve them if your agent asks.

The skill tells the agent not to approve, comment, close, merge, push or land anything unless you explicitly ask. A misread of the output could still lead to a wrong decision, so have a human check the root cause and the proof before you act on it.

• Read-only GitHub reads via gh; write actions are forbidden unless you ask.
• git fetch origin updates your local repository from the remote.
• The output may be wrong. Verify the cited files and tests yourself.