Installs into .claude/skills of the current project.
Sponsors
SSkills DirectorySkills Directory
Know which skills are safe — weekly.
SSkills DirectorySkills Directory
Is that skill safe to install?
Are you the author of Code Review?
Add the live security badge to your README. It updates with every re-scan.
[](https://www.skillsdirectory.com/skills/gittower-code-review)
---
name: code-review
description: Review changes or PRs against project guidelines
allowed-tools: Read, Write, Grep, Glob, Bash
---
# Code Review
Review local changes or pull requests against project guidelines. All output is written locally — never posted to GitHub.
## Arguments
`/code-review [target] [--output path]`
### Target (optional)
Specifies what to review. Can be:
- **Nothing** - auto-detect new commits on current branch vs main (default)
- **Commit range** - review specific commits (e.g., `HEAD~3..HEAD`, `abc123..def456`)
- **Single commit** - review one commit (e.g., `HEAD~1`, `abc123`)
- **Branch comparison** - review branch diff (e.g., `main..feature/foo`)
- **PR number** - review a pull request (e.g., `#123` or `123`)
### Output (optional)
`--output path` or `-o path` - where to write the review:
- A folder name within `.ai/` (e.g., `issue-59-add-no-verify-option`)
- A relative path (e.g., `.ai/issue-59-add-no-verify-option`)
- If omitted with auto-detect mode: auto-detects from branch name, writes to `.ai/`
- If omitted with explicit target: outputs directly to conversation (no file)
- If omitted with PR mode: auto-saves to `.ai/` (see step 6)
### Examples
```bash
# Auto-detect new commits vs main (writes to .ai/)
/code-review
# Auto-detect, specify output folder
/code-review --output issue-59-add-no-verify-option
/code-review -o .ai/my-feature
# Review specific commits (outputs to conversation)
/code-review HEAD~3..HEAD
/code-review abc123
/code-review main..feature/foo
# Review commits and save to file
/code-review HEAD~5..HEAD --output code-audit
# Review a pull request (auto-saves to .ai/)
/code-review #123
/code-review 123
```
## Instructions
1. **Parse Arguments**
- Check if a commit/range target was provided
- Check if the target is a PR number (`#123` or bare `123` that isn't a valid git ref)
- Check if `--output` or `-o` flag was provided
- Determine review mode: "auto-detect" (default), "explicit", or "pr"
2. **Gather Context**
For **auto-detect mode** (no target specified):
- Get current branch name
- Find associated workflow folder in `.ai/`
- Read the original issue/concept and plan if available
For **explicit mode** (commit/range target specified):
- Validate the commit range/ref exists
- No workflow folder lookup needed
For **PR mode** (PR number specified):
- Fetch PR metadata:
```bash
gh pr view <number> --json title,author,baseRefName,headRefName,headRefOid,number
```
- No workflow folder lookup needed
3. **Detect and Get Changes**
For **auto-detect mode**:
- Determine the main branch: run `git config gitflow.branch.main.name` (fallback to `main`)
- Detect new commits: run `git log <main>..HEAD --oneline`
- If no new commits exist, inform the user and stop
- Get the diff for those commits: `git diff <main>...HEAD`
- List the commits being reviewed
For **explicit mode**:
- If range (contains `..`): `git diff <range>` and `git log <range> --oneline`
- If single commit: `git show <commit> --stat` and `git log -1 <commit>`
For **PR mode**:
- Get the full diff: `gh pr diff <number>`
- Get the commit list: `gh pr view <number> --json commits --jq '.commits[].oid'`
- List all modified files from the diff
For all modes:
- List all modified files
4. **Review Against Guidelines**
Review the code against **[REVIEW_CRITERIA.md](REVIEW_CRITERIA.md)**, which covers:
- Test coverage
- Coding guidelines and architecture
- Code quality
- Security
- Documentation
- Commit messages
5. **Code Quality Checks** (auto-detect mode only)
Skip this step for explicit mode (reviewing historical commits) and PR mode.
For auto-detect mode, run:
```bash
# Format check
go fmt ./...
# Vet check
go vet ./...
```
6. **Determine Output Location**
**Filename includes revision(s) being reviewed:**
```bash
# For auto-detect mode: use HEAD short SHA
HEAD_SHA=$(git rev-parse --short HEAD)
FILENAME="review-${HEAD_SHA}.md"
# For commit range (abc123..def456): use both endpoints
START_SHA=$(git rev-parse --short abc123)
END_SHA=$(git rev-parse --short def456)
FILENAME="review-${START_SHA}-${END_SHA}.md"
# For single commit: use that commit's short SHA
COMMIT_SHA=$(git rev-parse --short abc123)
FILENAME="review-${COMMIT_SHA}.md"
# For PR mode: use PR number and head SHA
HEAD_SHA=$(gh pr view <number> --json headRefOid --jq '.headRefOid' | cut -c1-7)
FILENAME="review-pr<number>-${HEAD_SHA}.md"
```
If `--output` / `-o` was provided:
- If it starts with `.ai/`, use it directly
- Otherwise, treat it as a folder name within `.ai/` (prepend `.ai/`)
- Create the folder if it doesn't exist
- Write to `<folder>/<filename>`
If no `--output` and **auto-detect mode**:
- Extract issue number from branch name (e.g., `feature/59-...` → `59`)
- Look for existing `.ai/issue-<number>-*` folder
- If no `.ai/` folder exists, create one based on the branch name pattern
- Write to `<folder>/<filename>`
If no `--output` and **PR mode**:
- Extract issue number from the PR branch name if possible
- Look for existing `.ai/issue-<number>-*` folder
- Fall back to `.ai/pr-<number>/`
- Write to `<folder>/<filename>`
If no `--output` and **explicit mode**:
- Output directly to the conversation (no file written)
Examples:
- Auto-detect at HEAD `c9625f7` → `.ai/issue-59-foo/review-c9625f7.md`
- Range `abc123..def456` with `-o issue-59-foo` → `.ai/issue-59-foo/review-abc123-def456.md`
- Single commit `abc123` with `-o .ai/my-feature` → `.ai/my-feature/review-abc123.md`
- PR `#60` at head `a1b2c3d` → `.ai/issue-59-foo/review-pr60-a1b2c3d.md`
- Explicit mode, no flag → output to conversation (no file)
7. **Generate Review Report**
Write the review to file OR output directly to conversation based on step 6.
Use this format:
```markdown
# Code Review: <branch-name, commit-range, or PR #number>
## Summary
- Revision(s): `<start-sha>` to `<end-sha>` (or single `<sha>`)
- Files changed: <count>
- Lines added: <count>
- Lines removed: <count>
- Commits reviewed: <count> (list the commit SHAs/subjects)
```
For **PR mode**, add PR metadata to the summary:
```markdown
- PR: #<number> - <title>
- Author: <author>
- Base: <base-branch> ← <head-branch>
```
Then continue with:
```markdown
## Checklist Results
### Passed
- <item 1>
- <item 2>
### Must Fix
- [ ] <issue 1> - <file:line> - <description>
- [ ] <issue 2> - <file:line> - <description>
### Should Fix
- <item 1>
## Quality Checks (auto-detect mode only)
- Format: PASS/FAIL
- Vet: PASS/FAIL
## Recommendations
1. <recommendation>
2. <recommendation>
## Ready for PR? (auto-detect mode only)
<YES/NO - explain if NO>
```
For explicit and PR modes, omit "Quality Checks" and "Ready for PR?" sections.
8. **Report Findings**
- If issues found, list them with specific file:line references
- Suggest fixes for each issue
- For auto-detect mode: indicate if changes are PR-ready
- For explicit and PR modes: provide code review feedback directly in conversation
## Issue Categories
Categorize findings using the severity levels defined in REVIEW_CRITERIA.md (Must fix, Should fix, Nit).