Codex Review Skill

A Claude Code skill for professional code review with automatic CHANGELOG generation, integrating with Codex AI to analyze diffs, suggest improvements, and maintain structured release documentation.

When to Use This Skill

Choose this skill when:

• Reviewing code changes before committing to version control
• Generating automatic CHANGELOG entries from code diffs
• Performing pre-commit quality checks with AI-powered analysis
• Reviewing large refactoring efforts for regressions
• Maintaining structured release notes alongside code changes

Consider alternatives when:

• You need a general-purpose code review checklist (use the code-review-checklist skill)
• You need security-only scanning (use a security review skill)
• You need manual CHANGELOG writing without code analysis

Quick Start

Copy
# Add to your Claude Code project
claude mcp add codex-review

# Review staged changes
claude "review my staged changes and generate changelog entries"

# Review a specific commit range
claude "review commits from v1.2.0 to HEAD with changelog"

Copy
# .claude/skills/codex-review.yml
name: codex-review
description: AI code review with automatic CHANGELOG generation
triggers:
  - "codex review"
  - "review with changelog"
  - "pre-commit review"
config:
  changelog_format: keep-a-changelog
  review_depth: standard
  auto_categorize: true

Core Concepts

Review + CHANGELOG Pipeline

Step	Action	Output
1. Diff Analysis	Parse git diff for changed files	Structured diff object
2. Code Review	Analyze changes for issues and improvements	Review findings with severity
3. Categorization	Classify changes (added, changed, fixed, etc.)	Categorized change list
4. CHANGELOG Gen	Generate user-facing change descriptions	CHANGELOG.md entries
5. Summary	Produce review summary with action items	Markdown report

Auto-Generated CHANGELOG

Copy
## [Unreleased]

### Added
- User avatar upload with automatic image resizing (#234)
- Export dashboard data to CSV format (#251)

### Changed
- Improved search query performance with database index (#267)
- Updated authentication flow to support SSO providers (#271)

### Fixed
- Resolved duplicate entries in search results (#289)
- Fixed password reset for custom email domains (#293)

### Security
- Patched reflected XSS in comment rendering (#301)

Review Integration

Copy
# Pre-commit hook integration
#!/bin/sh
# .git/hooks/pre-commit
claude "codex review staged changes, block if blockers found"

# CI pipeline integration
# .github/workflows/review.yml
- name: AI Code Review
  run: claude "codex review PR changes, post review comments"

Configuration

Parameter	Type	Default	Description
changelog_format	string	"keep-a-changelog"	CHANGELOG format: keep-a-changelog, conventional, custom
review_depth	string	"standard"	Review depth: quick, standard, thorough
auto_categorize	boolean	true	Auto-categorize changes (added/changed/fixed)
changelog_file	string	"CHANGELOG.md"	Path to CHANGELOG file
include_commit_refs	boolean	true	Include commit hashes in CHANGELOG entries
block_on_blocker	boolean	false	Fail pre-commit if blocker-severity issues found
audience	string	"developers"	CHANGELOG audience: developers, users, stakeholders

Best Practices

1. Run codex review as a pre-commit hook — catching issues before they enter version control is cheaper than catching them in PR review; configure the skill to block commits with blocker-severity findings.

2. Write CHANGELOG entries for your audience — developer-facing changelogs can be technical, but user-facing release notes should translate changes into benefits; set the audience parameter accordingly.

3. Review the generated CHANGELOG entries — auto-categorization is accurate for clear-cut changes but may miscategorize refactoring or mixed-purpose commits; always review before publishing.

4. Keep one CHANGELOG entry per logical change — multiple commits fixing the same feature should produce one entry, not several; group related commits manually when the auto-categorization splits them.

5. Include issue/PR references in entries — enable include_commit_refs so CHANGELOG readers can trace back to the full discussion and context of each change.

Common Issues

CHANGELOG entries are too technical for end users — Set audience: users to generate plain-language descriptions. Instead of "refactored UserService DI container," the skill will produce "improved account page loading speed."

Pre-commit hook is too slow for small changes — Use review_depth: quick for pre-commit hooks and reserve standard or thorough depth for CI pipeline reviews where speed is less critical.

Duplicate CHANGELOG entries from merge commits — The skill may process both the merge commit and individual commits. Enable skip_merges: true or use squash-and-merge workflow to avoid duplicate entries.