PR review

The reference workflow is available here.

Automatically review pull requests, providing feedback on code quality, security, and best practices. Reviews can be triggered in two ways:

• Requesting faheem-code-agent as a reviewer
• Adding the review-this label to the PR

Note

The reference workflow triggers on either the "review-this" label or when the faheem-code-agent account is requested as a reviewer. In Faheem Code organization repositories, faheem-code-agent has access, so this works as-is. In your own repositories, requesting faheem-code-agent will only work if that account is added as a collaborator or is part of a team with access. If you don't plan to grant access, use the label trigger instead, or change the condition to a reviewer handle that exists in your repo.

Quick start

# 1. Copy workflow to your repository
cp examples/03_github_workflows/02_pr_review/workflow.yml .github/workflows/pr-review.yml

# 2. Configure secrets in GitHub Settings → Secrets
# Add: LLM_API_KEY

# 3. (Optional) Create a "review-this" label in your repository
# Go to Issues → Labels → New label
# You can also trigger reviews by requesting "faheem-code-agent" as a reviewer

Features

• Fast Reviews - Results posted on the PR in only 2 or 3 minutes
• Comprehensive Analysis - Analyzes the changes given the repository context. Covers code quality, security, best practices
• GitHub Integration - Posts comments directly to the PR
• Customizable - Add your own code review guidelines without forking

Security

• Users with write access (maintainers) can trigger reviews by requesting faheem-code-agent as a reviewer or adding the review-this label.
• Maintainers need to read the PR to make sure it's safe to run.

Customizing the code review

Instead of forking the agent_script.py, you can customize the code review behavior by adding a skill file to your repository. This is the recommended approach for customization.

How it works

The PR review agent uses skills from the SMART-National-Solution/faheem-code-extensions repository by default. You can add your project-specific guidelines alongside the default skill by creating a custom skill file.

Note

Skill paths: Place skills in .agents/skills/ (recommended). The legacy path .faheem-code/skills/ is also supported. See Skill Loading Precedence for details.

Example: custom code review skill

Create .agents/skills/custom-codereview-guide.md in your repository:

---
name: custom-codereview-guide
description: Project-specific review guidelines for MyProject
triggers:
- /codereview
---

# MyProject-Specific Review Guidelines

In addition to general code review practices, check for:

## Project Conventions

- All API endpoints must have OpenAPI documentation
- Database migrations must be reversible
- Feature flags required for new features

## Architecture Rules

- No direct database access from controllers
- All external API calls must go through the gateway service

## Communication Style

- Be direct and constructive
- Use GitHub suggestion syntax for code fixes

Note

Note: These rules supplement the default code-review skill, not replace it.

Tip

How skill merging works: Using a unique name like custom-codereview-guide allows BOTH your custom skill AND the default code-review skill to be triggered by /codereview. When triggered, skill content is concatenated into the agent's context (public skills first, then your custom skills). There is no smart merging—if guidelines conflict, the agent sees both and must reconcile them.

If your skill has name: code-review (matching the public skill's name), it will completely override the default public skill instead of supplementing it.

Note

Migrating from override to supplement: If you previously created a skill with name: code-review to override the default, rename it (e.g., to my-project-review) to receive guidelines from both skills instead.

Benefits of custom skills

1. No forking required: Keep using the official SDK while customizing behavior
2. Version controlled: Your review guidelines live in your repository
3. Easy updates: SDK updates don't overwrite your customizations
4. Team alignment: Everyone uses the same review standards
5. Composable: Add project-specific rules alongside default guidelines

Note

See the software-agent-sdk's own custom-codereview-guide skill for a complete example.

Reference workflow

Note

This example is available on GitHub: examples/03_github_workflows/02_pr_review/

---
# Faheem Code PR Review Workflow
#
# To set this up:
#  1. Copy this file to .github/workflows/pr-review.yml in your repository
#  2. Add LLM_API_KEY to repository secrets
#  3. Customize the inputs below as needed
#  4. Commit this file to your repository
#  5. Trigger the review by either:
#     - Adding the "review-this" label to any PR, OR
#     - Requesting faheem-code-agent as a reviewer
#
# For more information, see:
# https://github.com/SMART-National-Solution/faheem-code-sdk/tree/main/examples/03_github_workflows/02_pr_review
name: PR Review by Faheem Code

on:
    # Trigger when a label is added or a reviewer is requested
    pull_request:
        types: [labeled, review_requested]

permissions:
    contents: read
    pull-requests: write
    issues: write

jobs:
    pr-review:
        # Run when review-this label is added OR faheem-code-agent is requested as reviewer
        if: |
            github.event.label.name == 'review-this' ||
            github.event.requested_reviewer.login == 'faheem-code-agent'
        runs-on: ubuntu-latest
        steps:
            - name: Checkout for composite action
              uses: actions/checkout@v4
              with:
                  repository: SMART-National-Solution/faheem-code-sdk
                  # Use a specific version tag or branch (e.g., 'v1.0.0' or 'main')
                  ref: main
                  sparse-checkout: .github/actions/pr-review

            - name: Run PR Review
              uses: ./.github/actions/pr-review
              with:
                  # LLM model(s) to use. Can be comma-separated for A/B testing
                  # - one model will be randomly selected per review
                  llm-model: anthropic/claude-sonnet-4-5-20250929
                  llm-base-url: ''
                  # [DEPRECATED] review-style is no longer used; standard and roasted are merged
                  # review-style: roasted
                  # Extensions version to use (version tag or branch name)
                  extensions-version: main
                  # Secrets
                  llm-api-key: ${{ secrets.LLM_API_KEY }}
                  github-token: ${{ secrets.GITHUB_TOKEN }}

Action inputs

Input	Description	Required	Default
llm-model	LLM model to use	Yes	-
llm-base-url	LLM base URL (optional)	No	''
review-style	[DEPRECATED] Previously chose between standard and roasted. Now ignored — the styles have been merged.	No	roasted
extensions-version	Git ref for extensions (tag, branch, or commit SHA)	No	main
extensions-repo	Extensions repository (owner/repo)	No	SMART-National-Solution/faheem-code-extensions
llm-api-key	LLM API key	Yes	-
github-token	GitHub token for API access	Yes	-

Related files

• PR Review Plugin - Complete plugin with scripts and skills (in extensions repo)
• Agent Script - Main review agent script
• Prompt Template - Review prompt template
• Example Workflow - Example workflow
• Composite Action - Reusable GitHub Action