Skip to content
Get packs

Guide · Agent skill

How to use the CodeQL Code Scanning Guide agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The CodeQL Code Scanning Guide skill is an agent skill that gives an AI agent step-by-step guidance for configuring CodeQL, GitHub's static analysis tool for finding security bugs in source code. It is written for developers and security engineers who want the agent to set up or troubleshoot code scanning on a GitHub repository or run the CodeQL command-line tool locally. After following this guide you will know how to install the skill, how to ask for help in plain language, and what the skill needs to work.

CodeQL Code Scanning Guidegithub/awesome-copilot · MIT

Quick start

  1. 1Download the skill ZIP. Download the codeql skill ZIP from this page.
  2. 2Unzip into a skills folder. Unzip it into ~/.claude/skills/ for personal use, or into your project's .claude/skills/ folder for one project.
  3. 3Or upload it in the Claude apps. In the Claude apps, go to Settings → Capabilities → Skills and upload the skill.
  4. 4Check your requirements. Confirm your repository has code scanning or GitHub Advanced Security enabled and uses GitHub Actions, and install the CodeQL CLI bundle if you need local runs.
  5. 5Ask in plain language. Describe your repository, languages and goal, such as adding a workflow or fixing a failed analysis.
  6. 6Review the output before running it. Read any generated workflow or command, then commit or run it in your own environment.

What an agent skill is and what this one makes the agent do

An agent skill is a folder of instructions and reference files that an AI agent loads when a request matches the skill's description. This skill is named codeql and its SKILL.md file covers the full procedure for CodeQL code scanning, with extra detail in separate reference files.

When installed, the agent can write or adjust GitHub Actions workflow files, choose languages and build modes, set permissions and triggers, run the CodeQL command-line tool locally, and interpret or troubleshoot SARIF results.

  • Create or customize a codeql.yml GitHub Actions workflow
  • Choose between default setup and advanced setup
  • Configure the language matrix, build modes and query suites
  • Set up monorepos with per-component categories
  • Run CodeQL CLI commands such as database create, database analyze and github upload-results
  • Explain or troubleshoot SARIF output and failed analysis runs

Install the codeql skill with a ZIP download

Download the ZIP for this skill from this page and unzip it. The skill is a folder, so the unzipped folder should contain SKILL.md and the references folder.

For a personal install that applies to all your projects, unzip the folder into ~/.claude/skills/. To limit the skill to one project, unzip it into that project's .claude/skills/ folder instead.

You can also upload the skill in the Claude apps. Go to Settings → Capabilities → Skills and add the ZIP there.

  • Personal install: ~/.claude/skills/
  • Project install: .claude/skills/ inside your project
  • Claude apps: Settings → Capabilities → Skills

Trigger the skill with natural requests

You do not need a special command. The skill is meant to be used when a request involves code scanning configuration, CodeQL workflow files, CLI commands, SARIF output, security analysis setup, or troubleshooting CodeQL analysis. Describe what you want in plain language and name the thing you are working on, such as your repository, language or error message.

Include details that change the answer, such as whether you use default or advanced setup, which languages the repository contains, and whether the project is compiled. These details decide the build mode and matrix the agent should use.

  • Add CodeQL scanning to this repo; it is a Python and TypeScript project with a Node frontend.
  • Write a codeql.yml workflow that scans on push to main and on pull requests.
  • My CodeQL analysis fails on a C++ build with autobuild. What should I change?
  • Explain what this SARIF result means and how to dismiss it correctly.
  • Run CodeQL locally on this Java project and upload the results to GitHub.

Example: set up a basic advanced workflow

For a first advanced setup, the skill's guidance is to create a .github/workflows/codeql.yml file. It sets triggers, least-privilege permissions, a language matrix, and separate init and analyze steps. Ask the agent to produce the workflow for your languages, then review the output before committing it.

The skill notes that to switch from default setup to advanced setup, you disable default setup first and then commit the workflow file.

  • Triggers: push and pull_request to your main branch, plus an optional weekly schedule
  • Permissions: security-events write, contents read, actions read
  • Matrix: one entry per language, with a build-mode for each
on: push: branches: [main, protected] pull_request: branches: [main] schedule: - cron: '30 6 * * 1' # Weekly Monday 6:30 UTC

Example: run the CodeQL CLI locally

For local work, the skill covers creating a database, analyzing it into SARIF, and uploading the results. Download the CodeQL bundle from the releases page given in the reference files, extract it, and add it to your PATH. Always use the bundle rather than a standalone CLI download.

The commands below come from the skill. Replace the placeholders, such as the commit SHA and repository name, with your own values. Uploading requires a GITHUB_TOKEN environment variable with security-events: write permission.

codeql database create codeql-db \ --language=javascript-typescript \ --source-root=src codeql database analyze codeql-db \ javascript-code-scanning.qls \ --format=sarif-latest \ --sarif-category=javascript \ --output=results.sarif codeql github upload-results \ --repository=owner/repo \ --ref=refs/heads/main \ --commit=<commit-sha> \ --sarif=results.sarif

Safety notes: scripts and network access

The skill does not run scripts and does not use the network, according to its listing. It only explains how to configure and run CodeQL. Any workflow file or shell command it writes would run in your own environment, so read it before you commit or execute it.

You still need your own GitHub repository with code scanning or GitHub Advanced Security enabled, GitHub Actions for workflow-based scanning, and the CodeQL CLI bundle if you want local CLI use.

  • The skill runs no scripts and makes no network calls itself
  • Generated workflows and commands run in your environment with your permissions
  • Keep GITHUB_TOKEN scoped to the minimum permissions needed

Tips for better results

Give the agent your exact error text or the failing workflow log. Troubleshooting depends on details such as the build mode and runner. For compiled languages, say which build system you use, because autobuild may not handle every setup.

Use the category setting in monorepos so SARIF results from different languages or components stay separate.

  • Paste the failing log line, not a summary of it
  • Name the languages and build system in your first message
  • Ask for a category per component in monorepos
  • Review SARIF findings before dismissing them

What people use it for

  • Adding CodeQL scanning to a repository for the first time with a new advanced workflow file
  • Setting build modes and category values for a monorepo with compiled and interpreted languages
  • Running the CodeQL CLI locally to create a database, analyze it and upload SARIF results
  • Explaining a SARIF finding or alert severity before deciding how to handle it
  • Diagnosing a failed CodeQL analysis run in GitHub Actions

Frequently asked questions

How do I install the codeql agent skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. You can also upload it in the Claude apps under Settings → Capabilities → Skills.

What do I need to use this skill?

You need a GitHub repository with code scanning or GitHub Advanced Security enabled, and GitHub Actions for workflow-based scanning. The CodeQL CLI bundle is only needed for local command-line use.

Is the codeql skill free?

The skill is listed under the MIT licence. The source does not state any price, so check the repository for licence terms.

Does the skill run scans for me?

No. The skill explains how to configure and run CodeQL, and any workflows or scripts it produces run in your own environment. It runs no scripts and uses no network, according to its listing.

Can I use this skill if my project is not on GitHub?

The guidance centres on GitHub and GitHub Actions, so it is not a good fit for projects hosted elsewhere. The CLI parts may still help if you run CodeQL locally.

How is this different from CodeQL's default setup?

Default setup is enabled from repository settings and is quick to start. Advanced setup uses a codeql.yml workflow file that gives you control over triggers, build modes, query suites and matrix strategies, and this skill helps with the advanced file.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

This skill suits developers adding CodeQL to a GitHub repository for the first time, teams with monorepos or compiled languages that need build-mode and category settings, and security engineers troubleshooting local or workflow runs. It is a poor choice for projects not on GitHub or not using GitHub Actions, and for anyone expecting the agent to run scans itself.

Download the skill