Preface¶

Before submitting a PR, many people ask AI to “take a quick look at the code”. The common results fall into two categories: one only catches whitespace and naming issues, while missing real vulnerabilities like injections, authorization bypasses, and race conditions; the other spits out false positives based on keyword matching, even flagging patterns that are already protected by the framework. What’s missing isn’t just the phrase “review again”, but a fixed workflow: first obtain the full diff, map the attack surface, check items off a list one by one, and finally prove that the problem actually exists.

find-bugs is the result of packaging this workflow into an Agent Skill. It comes from the public repository getsentry/skills maintained by the Sentry Engineering Team, and the official documentation is available at skills/find-bugs/SKILL.md. The repository README states that this is a collection of Agent Skills used daily by Sentry employees, following the open Agent Skills format, and licensed under Apache-2.0.

What It Is¶

In one sentence: It finds bugs, security vulnerabilities, and code quality issues in changes made in your current local branch relative to the default branch, and only outputs reports without modifying any code.

The official frontmatter is as follows:
- name: find-bugs
- description: Find bugs, security vulnerabilities, and code quality issues in local branch changes; use when requested to review changes, find bugs, conduct a security review, or audit the current branch’s code

There is only this one SKILL.md file in the directory, with no attached scripts or references/ folder. It is not a static analyzer, nor does it call Sentry’s product APIs; the actual work is done by an AI Agent that reads this checklist, paired with git and the GitHub CLI (gh) to fetch the full diff.

There are other Skills in the same repository with similar responsibilities but different scopes, which should not be mixed up:
- code-review: Conduct PR reviews in line with Sentry’s engineering practices (runtime errors, performance, testing, design)
- security-review: Specialized security review, only reports high-confidence, exploitable vulnerabilities, with independent language/infrastructure reference documentation

The scope of find-bugs is more narrow: it only looks at changes in the current branch relative to the default branch, covers security, defects, and quality, and explicitly skips purely stylistic and formatting issues.

Core Features and Highlights¶

According to the official SKILL.md, the workflow is fixed in five stages.

Stage 1: Fully Collect Inputs¶

The Agent must first obtain the full diff, not a summary:

git diff $(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')...HEAD

This command uses gh repo view to retrieve the repository’s default branch (such as main / master), then performs a three-dot diff between the default branch and the current HEAD (i.e., the changes in the current branch relative to the merge base). The official requirements also include:
1. If the output is truncated, open each modified file individually until every changed line has been reviewed
2. List all files modified in this branch before moving to the next stage

This means you are not allowed to “skim a few files and jump to conclusions”.

Stage 2: Map the Attack Surface¶

For each modified file, first list these points instead of guessing vulnerabilities directly:
- All user input (request parameters, headers, body, URL components)
- All database queries
- All authentication/authorization checks
- All session/state operations
- All external calls
- All cryptographic operations

The purpose of this step is to translate the diff into “what an attacker can touch”, giving a concrete foundation for the subsequent checklist.

Stage 3: Security Checklist (Go through every item for every file)¶

The official checklist has 11 items, and you are required to check each one off for every file:
- Injection: SQL, command, template, header injection
- XSS: Is output correctly escaped in templates?
- Authentication: Are protected operations properly authenticated?
- Authorization / IDOR: Is access control verified, not just “logged in”?
- CSRF: Are state-changing operations protected against CSRF?
- Race conditions: Are there TOCTOU issues on read-then-write paths?
- Session: Session fixation, expiration, Secure flags, etc.
- Cryptography: Secure random number generation, appropriate algorithms, keys not logged
- Information disclosure: Error messages, logs, timing side channels
- DoS: Unbounded operations, missing rate limiting, resource exhaustion
- Business logic: Edge cases, broken state machines, numeric overflows

This is not “checking whatever comes to mind”, but a mandatory checklist that must be fully completed.

Stage 4: Verification¶

For every suspicious point, the official requirements require confirming three things:
1. Has the issue already been fixed elsewhere in this change?
2. Is there already test coverage for this scenario?
3. Read the surrounding context to confirm the problem is real

The goal is to reduce false positives: seeing execute or string concatenation does not immediately mean you can report an injection vulnerability.

Stage 5: Pre-closure Audit¶

Before delivering the final conclusion, you must first complete:
1. List every file reviewed and confirm you have finished reading them
2. List every item on the checklist: note whether a problem was found or confirmed clean
3. List areas that could not be fully verified and the reasons why
4. Only then deliver the final findings

Output Format¶

The priority is fixed as: Security Vulnerabilities > Bugs > Code Quality. Stylistic and formatting issues are skipped directly.

Each issue should be documented with the following fields:
- File:Line: Brief description
- Severity: Critical / High / Medium / Low
- Problem: What is wrong
- Evidence: Why this is a real issue (for example: not fixed elsewhere, no existing tests)
- Fix: Specific recommended changes
- References: Reference OWASP, RFC, and other standards when applicable

The official has two hard constraints:
1. State clearly if there are no obvious issues, do not fabricate problems
2. Do not modify code, only report issues; the user decides which fixes to implement

Installation and Activation¶

This Skill is included in the getsentry/skills repository and is provided as part of the sentry-skills plugin. Follow the official README for installation methods.

Claude Code (Official Plugin Marketplace)¶

claude plugin marketplace add getsentry/skills
claude plugin install sentry-skills@sentry-skills

Restart Claude Code after installation. The official documentation states that the Skill will be automatically enabled in relevant scenarios. To update, use:

claude plugin marketplace update
claude plugin update sentry-skills@sentry-skills

Or run /plugin in a chat to open the plugin management interface. If you add this repository using claude plugin marketplace add --sparse, you need to include skills, agents, and .claude-plugin together, as the root plugin manifest loads the top-level skills/ and agents/ directories of the repository.

skills.sh (Cursor / Claude Code / Copilot, etc.)¶

The official README also provides the skills.sh installation method, which is noted to work with Claude Code, Cursor, Cline, GitHub Copilot, and other compatible Agents:

npx skills add getsentry/skills

If you only want to install this single Skill, the command on skills.sh is:

npx skills add https://github.com/getsentry/skills --skill find-bugs

Manual Placement in Each Tool’s Skill Directory¶

SKILL.md follows the universal Agent Skills format. According to Cursor’s documentation, project-level Skills are automatically discovered from .agents/skills/ and .cursor/skills/; user-level paths correspond to ~/.agents/skills/ and ~/.cursor/skills/. Compatible directories also include .claude/skills/, .codex/skills/, and their corresponding user-level paths. When placing manually, the directory structure should look like:

.cursor/skills/find-bugs/SKILL.md

Or:

.agents/skills/find-bugs/SKILL.md

For Claude Code, the project-level path is .claude/skills/find-bugs/SKILL.md, and the user-level path is ~/.claude/skills/find-bugs/SKILL.md. Codex CLI scans $CODEX_HOME/skills (default: ~/.codex/skills) and the project’s .codex/skills/ directory.

After activation, type / in an Agent chat, search for find-bugs to manually invoke it. The official description includes trigger phrases like review changes, find bugs, security review, and audit code, and the Agent may also automatically select this Skill when the description matches.

Typical Usage Examples¶

Prerequisites¶

According to the official commands, the runtime environment requires:
1. The current directory is a Git repository, and you are already on a feature branch with commits or uncommitted changes that can be compared against the default branch
2. The GitHub CLI (gh) is installed and logged in, because the default branch name is retrieved via gh repo view
3. The remote repository is hosted on GitHub; gh repo view will fail for non-GitHub remotes, in which case you need to manually provide the default branch name and have the Agent use git diff <default>...HEAD instead — this is an environment limitation, not an alternative workflow defined in the Skill itself

Invocation Methods¶

The official does not provide a separate “example prompt”, but the description clearly states the trigger scenarios. In a chat where the Skill is installed, you can directly say (or run /find-bugs first and then add):

Please review all changes in the current branch relative to the default branch using find-bugs:
First obtain the full diff, list all modified files, map the attack surface,
then check each item on the security checklist, and finally only output a problem report with evidence, do not modify any code.

You can also narrow the scope, for example, “only look at the diff related to API authentication this time” — the Agent should still follow the five-stage workflow instead of skipping diff collection and jumping to conclusions.

What the Report Looks Like¶

The official required entry format can be understood as the following example (paths and line numbers must come from the current diff, do not copy verbatim):

**app/api/orders.py:142** - Did not verify ownership when fetching an order by object ID
- **Severity**: High
- **Problem**: A logged-in user can read another user's order by passing any `order_id` (IDOR)
- **Evidence**: This query was added in this branch; no object-level authorization is seen in this file or the middleware; no corresponding tests exist
- **Fix**: Add a constraint for the current user (or tenant) when querying, for example `order.user_id == request.user.id`
- **References**: OWASP A01:2021 Broken Access Control

If no issues worthy of reporting are found after completing the five stages, the official text requires explicitly stating “no significant issues were discovered”, rather than fabricating stylistic comments to meet a reporting requirement.

Applicable Scenarios and Notes¶

Suitable For¶

A feature branch is about to be submitted for PR, and you want to conduct a local “security-first” review first
The changes involve user input, authentication, sessions, external calls, or cryptography, and you need to go through the checklist instead of only reviewing business logic
Your team already uses tools that support Agent Skills like Cursor / Claude Code / Codex, and you want review steps to be repeatable and shareable

Important Notes When Using¶

Depends on gh and GitHub remote. The official diff retrieval command hardcodes gh repo view. If gh is not installed, you are not logged in, or the repository is not hosted on GitHub, this command will fail; you need to resolve the environment issue or explicitly tell the Agent the default branch name.
Scope is “current branch relative to default branch”, not the entire repository. It will not replace a full security audit, nor will it scan old code that was not modified but is indirectly affected by this change — Stage 4 only requires reviewing surrounding context for verification, not performing a full repository scan.
Only reports, does not modify. The final line of the official documentation states: do not modify code, let the user decide which fixes to implement. If you need to make fixes on the spot, you should start a new chat or use a different workflow, to avoid conflicting with the responsibilities of this Skill.
Quality is not equal to style. The official explicitly skips stylistic/formatting issues. You should not use this Skill to check naming and whitespace problems.
False positives may still occur, but the workflow reduces them. Stage 4 requires checking “whether the issue has been fixed, whether there are tests, and whether the context confirms the problem”. Even so, the Agent may still misjudge framework-default protections (such as automatic template escaping, ORM parameterization). The repository’s security-review Skill is stricter in this regard: it only reports high-confidence issues with confirmed attacker-controllable input. For a more rigorous security review, you can run security-review after find-bugs.
No test suite or evaluation set. There is only the SKILL.md file in the current directory. The effectiveness depends on whether the model strictly follows the five stages, especially “must read every file if the diff is truncated” and “must list checklist coverage before closing”.

Summary¶

find-bugs packages the “branch-level review” workflow used by the Sentry team itself into a portable Skill: full diff → attack surface mapping → 11-item security checklist → verification → pre-closure audit, then outputs evidence-based reports sorted by priority: security > bugs > code quality. It does not replace professional penetration testing, nor does it automatically modify code, but it turns “let AI take a quick look” into a repeatable pre-commit scan.

Official address:
https://github.com/getsentry/skills/tree/main/skills/find-bugs

`find-bugs: Let AI scan the current branch for bugs and security issues according to the checklist`