Semgrep skill from Trail of Bits: what it does and how to install it (plus CodeQL)

Source: trailofbits/skills · Maintainer: community: Trail of Bits · License: CC-BY-SA-4.0 · Checked: 23 October 2026

What is the Semgrep skill?

The Semgrep skill lets Claude Code run a real Semgrep security scan over your codebase: it detects languages, picks rulesets, asks you to approve the plan, runs the scans and merges the findings into one SARIF file. It is for developers and security reviewers who want a first-pass static analysis without hand-writing dozens of semgrep commands.

It is one of the Trail of Bits skills, a marketplace of security plugins from the auditing firm Trail of Bits. The skill lives in the static-analysis plugin, next to a codeql skill and a sarif-parsing skill. The plugin README credits Axel Mierczuk and Paweł Płatek and says the Semgrep and CodeQL skills are based on the Trail of Bits Testing Handbook.

The skill's description reads: "Runs a Semgrep security scan over a codebase: detects languages, selects rulesets, presents the plan for explicit approval, then runs every approved ruleset through scripts/run-scans.sh, which batches the semgrep processes and writes scans.json, and merges the output to SARIF. Supports two scan modes, "run all" for full ruleset coverage and "important only" for security findings at medium-to-high confidence and impact. Uses Semgrep Pro for cross-file taint analysis when it is available. Use when asked to scan code for vulnerabilities, run a security audit with Semgrep, find bugs, or perform static analysis. For the same scan without the approval gate, use the /static-analysis:semgrep-scan workflow."

What does it do?

The SKILL.md runs five steps, each tracked as a task that blocks the next:

1. Resolve an output folder (default ./static_analysis_semgrep_1, counting up) and detect languages and whether Semgrep Pro is available.
2. Choose a scan mode and rulesets from references/rulesets.md.
3. Present the exact rulesets, target, engine and mode, and wait for an explicit yes. The skill calls this a hard gate: your original "scan this" request does not count as approval.
4. Run scripts/run-scans.sh, which clones third-party rule repos, builds every semgrep command and runs them in batches.
5. Filter, merge into results/results.sarif, report, and delete the cloned repos.

A few principles do the heavy lifting. Every command uses --metrics=off, because Semgrep sends telemetry by default. Third-party rulesets are required when the language matches; the catalog includes Trail of Bits, 0xdea, Decurity, elttam, HashiCorp and others. The script, not the model, writes the commands, so flags can't be silently dropped. And failed or skipped scans must appear in the report, because "A partial scan presented as a complete one is worse than no scan."

The two modes: run all reports everything, while important only keeps security findings with medium or high confidence and impact.

What's in the folder:

• SKILL.md and workflows/scan-workflow.md: the five steps in detail.
• references/rulesets.md and references/scan-modes.md: the ruleset catalog and filter rules.
• scripts/run-scans.sh and scripts/merge_sarif.py: the scan runner and SARIF merger, plus a test file.
• agents/openai.yaml and an icon: display metadata used when the marketplace is imported into a ChatGPT workspace.

What does the CodeQL skill add?

The sibling codeql skill goes deeper and slower. Semgrep matches patterns fast; CodeQL builds a database of your code and runs interprocedural data flow and taint tracking. It covers Python, JavaScript and TypeScript, Go, Java and Kotlin, C and C++, C#, Ruby and Swift.

Its workflow is build database, then create data extensions (models for your project's own wrappers around SQL, request parsing or shell calls), then run analysis. Its principles are blunt: a database that builds is not automatically good, zero findings "needs investigation, not celebration", and pack names should never be passed straight to codeql database analyze because default suites can filter queries out. Bundled Python and shell scripts check database quality and verify the query suite isn't empty. It also has notes for Apple Silicon build failures.

The codeql description says to use Semgrep instead for fast pattern matching or when a compiled language won't build, and to use sarif-parsing to read results that already exist.

How do you install Trail of Bits skills?

Claude Code plugin. The repo README adds the marketplace, which is named trailofbits:

/plugin marketplace add trailofbits/skills
/plugin install static-analysis@trailofbits

The README suggests /plugin menu to browse instead; the plugin@marketplace form is the standard syntax from the Claude Code plugin docs. Plugin skills are namespaced, so you get /static-analysis:semgrep and /static-analysis:codeql, plus the /static-analysis:semgrep-scan and /static-analysis:codeql-build workflows.

Codex. Also from the README:

codex plugin marketplace add trailofbits/skills
codex plugin add static-analysis@trailofbits

One skill at a time. The skills CLI, as shown on the skills.sh page:

npx skills add https://github.com/trailofbits/skills --skill semgrep
npx skills add https://github.com/trailofbits/skills --skill codeql

Folders land in .claude/skills/<name>/, or ~/.claude/skills/<name>/ with -g. This route skips the plugin's workflow commands. Codex and Cursor read the same SKILL.md format; see Codex skills and Cursor skills.

Then install the tools. Semgrep's quickstart lists pipx and uv as the preferred methods:

pipx install semgrep
semgrep --version

For CodeQL, the skill's own check suggests gh extension install github/gh-codeql or brew install --cask codeql.

How do you use it?

Example prompts (suggestions, not quotes from the repo):

• Run a Semgrep security scan on this repo, important only. Show me the plan first.
• Scan /Users/me/code/api with Semgrep and save results to ./audit-semgrep.
• /static-analysis:semgrep-scan {"target": "/abs/path/to/repo", "mode": "run-all"}
• Build a CodeQL database for this Go service and run a full analysis.
• CodeQL found nothing. Check the database quality and the query suite before we trust that.

The workflow command skips the approval step; the README says that is safe because the scan is read-only over the target and writes only to its output folder.

Tips and limits

From the files and the pages linked, not from testing:

• Security audits on skills.sh. As of 23 October 2026, the semgrep skill showed Warn from Socket and Snyk (audited 29 September 2026) and Pass from Gen Agent Trust Hub. Socket flagged the supply chain risk of cloning many unpinned third-party rule repos; Snyk flagged exposure to untrusted external content. The codeql skill showed Pass on all three. Review the files before installing.
• What runs. run-scans.sh runs git clone and semgrep; merge_sarif.py runs through uv. The SKILL.md frontmatter pre-approves Bash, Read, Glob, AskUserQuestion and task tools during the turn that invokes it, per the allowed-tools rules.
• Pro claims are the skill's. It says Pro "catches ~250% more true positives". Its Pro check notes the run quietly drops to OSS mode if you're logged out, have no subscription, or the registry is blocked, and OSS mode can't track data flow across files.
• CodeQL licensing. GitHub's CodeQL terms allow free use on open source codebases and for academic research, and restrict other code, such as a private repo, unless you have a paid GitHub Advanced Security license.
• Ruleset licenses differ. The catalog marks the Trail of Bits Semgrep rules as AGPLv3.
• Skill license. CC-BY-SA-4.0: credit Trail of Bits, and share adapted versions under the same license.

Save it in your Kipt library

In Kipt, open Skills and paste the skill's GitHub folder link into the import box. Kipt reads the SKILL.md and its files, including the scripts and references; for a repo with many skills it shows a list to pick from, so you can take semgrep, codeql and sarif-parsing together. You can also drop the folder or a .zip. Your skills live in your own private GitHub repo and install into Claude Code or Codex with one command:

npx skills add https://github.com/<you>/<repo>.git --all -g

Keep the CC-BY-SA notice with any copy you change. Kipt is not affiliated with Trail of Bits.

Similar skills

• Security and hardening skill: Addy Osmani's rules for writing secure code in the first place.
• Code review skill: a human-style review to go with automated scans.
• Terraform skill: HashiCorp's style guide skill, which pairs with the HashiCorp Semgrep rules.
• Dockerfile skill: smaller, safer images to scan.