How to use the Claude Security Scanner agent skill

What an agent skill is and what claude-security makes the agent do

An agent skill is a folder with a SKILL.md file that tells an agent how to carry out a specific task. When the request matches the skill's description, the agent follows the skill's instructions instead of improvising.

claude-security covers three jobs. Scan codebase reviews the whole repository or a scoped part of it. Scan changes reviews the diff of a branch or pull request against its base, or one commit against its parent. Suggest patches turns existing findings into targeted patch files that you can review and apply.

• Each reported finding is checked by a separate verifier pass before it appears in a report.
• Patches are written to disk as patch files. Nothing is committed, pushed, or opened as a pull request.

Install the claude-security skill

Download the ZIP for this skill from this page. Then use one of these two methods.

Method one is a personal install. Unzip the file into ~/.claude/skills/ so the skill is available in all your projects. Method two is a project install. Unzip it into the .claude/skills/ folder inside a specific repository so it applies only there.

Method three is the Claude apps. Upload the skill under Settings → Capabilities → Skills.

• Requires Claude Code or a compatible SKILL.md agent runtime.
• Requires Git for scanning branches, pull requests, or commits.
• Requires Python 3 for the helper scripts (render_report.py, save_result.py, write_scan_meta.py, patch_artifacts.py).
• Requires Bash shell access for the scripts and git commands.

Trigger the skill with a natural request

You do not need a special command. Describe what you want in plain language. If your request already names a job, the agent starts that job directly. If it does not, the agent opens a menu with three options: Scan codebase (recommended), Scan changes, and Suggest patches.

Examples of requests the skill responds to include scanning the repo, scanning your branch, fixing the findings, or passing a bare commit sha of 7 or more characters. A ref name in the request also points to the changes job.

• "Scan this repo with Claude Security."
• "Scan my branch with Claude Security."
• "Scan commit 3fa9c21 for security problems."
• "Fix the Claude Security findings."

Run each job and read the results

Scan codebase runs in your session, so there is no separate process to launch. Progress appears in the workflow detail view, which you open with /workflows, and a running count appears in the chat. Scan changes works the same way but focuses on the changed lines and the changed files read in full. An ordinary change usually finishes in minutes.

Suggest patches works four findings at a time. For each, a patch-generator subagent drafts a fix in a scratch copy of the repository. A patch-verifier subagent then reviews the change and runs the project's tests. A .patch file is written only when the verifier is confident the change is targeted, adds no new vulnerability, and leaves behaviour unchanged.

• For best results, use auto mode. Press Shift+Tab until the status bar shows auto mode, or start with claude --permission-mode auto.
• Reports are saved in your project as folders named CLAUDE-SECURITY-2 followed by a timestamp.

Safety notes: scripts, network and trust

This skill runs helper scripts and uses the network, and it runs in your session under your permissions. Your session's settings, hooks, CLAUDE.md, and MCP servers apply as usual. There is no isolation layer, so open the session in a repository only if you trust it.

The skill treats repository contents, including code, comments, CLAUDE.md, and findings text, as data to review, not as instructions. Nothing is applied automatically. Every suggested fix stays a patch file until you apply it yourself.

For code you do not trust, the source recommends running the whole session inside sandbox-runtime (https://github.com/anthropic-experimental/sandbox-runtime), which enforces filesystem and network restrictions at the OS level.

Tips for getting useful results

Scan changes is the fastest way to check a pull request before merging, because it looks at the diff. Scan codebase is better for a full review. A flaw that the change does not touch is reported by the codebase scan, not the changes scan.

Only committed changes are scanned, so commit your work before asking for a changes scan. Treat findings as leads to verify, and keep a human review in the loop for critical systems.

• Pick a scoped part of the repository when you want a faster run.
• Review each .patch file and its note before applying it.