GitGuardian Agent Skills

Beta — this distribution is pre-1.0. The skills work today, but they may change shape between releases: no stability guarantee yet on skill names, slash commands, or file layout.

Find exposed credentials before attackers abuse them, block new leaks before they ship, and plant honeytokens to detect future misuse. This repo ships skill files that teach AI coding agents how to use GitGuardian through the GitGuardian CLI (ggshield), the Developer MCP server, and API-backed workflows where appropriate - when to scan, which flags to use, how to interpret findings, how to walk the user through removal and rotation, and when and where to plant honeytokens.

Supported agents: Claude Code, Codex, Cursor, VS Code (GitHub Copilot), Kiro. Install into your agents with curl -fsSL agents.gitguardian.com | sh - details below.

Skills and Commands

Four skills map to four slash commands:

Scan secrets — /gitguardian:scan-secrets

scan-secrets

Find hardcoded secrets in paths, staged changes, commits, full history, Docker images, and packages.

Use when: requesting a one-off scan, auditing existing files or history, or investigating a suspected leak.

Key rule: run the scan the user asked for, then remediate from the structured findings. Routine edits, commits, and pushes use hooks, not repeated agent scans.

Create honeytokens — /gitguardian:create-honeytokens

create-honeytokens

Generate and place decoy AWS credentials.

Use when: planting decoys in .env.example, docs, runbooks, archived repos, or other attractive leak surfaces.

Key rule: plant where attackers look, not where engineers import.

Scan machine — /gitguardian:scan-machine

scan-machine

Audit a whole developer machine for credentials across local repos, dotfiles, cloud CLI configs, shell history, AI agent caches, and abandoned project trees.

Use when: wiping, selling, returning, or auditing a developer machine.

Key rule: this is a broad endpoint scan and requires endpoint scanning on the GitGuardian workspace.

Check HMSL — /gitguardian:check-hmsl

check-hmsl

Check known credentials against HasMySecretLeaked without exposing plaintext to the agent.

Use when: you already have a token, key, .env, vault inventory, or inherited credential list and want to know whether any value has appeared in indexed public leaks.

Key rule: user-run handoff only; the agent must not read or run against the credential file.

Install hooks — /gitguardian:install-hooks

install-hooks

Install recurring protection with ggshield. Pre-commit hooks check staged changes before a commit. Pre-push hooks check outgoing commits before a push. AI hooks check supported prompts and tool actions in Claude Code, Cursor, Codex, Copilot, and Mistral Vibe.

Use when: asking to install Claude/Cursor/Copilot hooks, setting up secret prevention on a repo, asking to block or stop secrets from being committed or pushed, configuring pre-commit hooks, or hardening after a secret was caught.

Key rule: check the existing protection, reuse a matching hook, and offer an installation or a repair one time. Keep existing hook managers. A global installation needs an explicit request or approval. A hook installation does not audit existing code or history.

Triage incidents — /gitguardian:triage-incidents

triage-incidents

Read the secret incidents already detected in your GitGuardian dashboard, rank them by validity, severity, blast radius, and exposure, and drive remediation — rotation first, HMSL for unverifiable validity, history rewrite only when it earns its cost.

Use when: triaging or reviewing GitGuardian incidents, asking what's leaking in the org or what to fix first, remediating or rotating a credential flagged in an incident, responding to a Public Monitoring alert, or assigning/tagging/resolving incidents.

Key rule: the one MCP-first skill — it works through the GitGuardian Developer MCP server, not the ggshield CLI. Covers both internal and Public Monitoring incidents (non-interchangeable IDs). Never auto-resolves: writes are confirmation-gated and RESOLVED follows confirmed rotation.

Skills also route from context. Recurring protection while you edit credential-handling code or prepare commits and pushes belongs to install-hooks. An existing effective hook does the check, so the agent does not run another scan. An explicit scan or a suspected leak activates scan-secrets. A question about whether a known token has leaked activates check-hmsl.

Quick Start

curl -fsSL agents.gitguardian.com | sh

Detects the agent CLIs on your machine, asks which ones to configure, and installs the skills along with the bundled Developer MCP server for each. To explore all available options, ask your agent: "read agents.gitguardian.com and explain how it works."

Claude Code

Add this repo as a plugin marketplace, then install the gitguardian plugin:

/plugin marketplace add GitGuardian/agent-skills

/plugin install gitguardian

For user-wide Claude Code protection after ggshield is installed and authenticated (ggshield 1.53.0+):

ggshield machine setup --no-git-hooks --no-honeytokens --agent claude-code

The hook checks supported prompt and tool events. A finding in a prompt or pre-tool event can block the action. A finding in a post-tool event gives a notification after the action. When a scan has an error, the action continues with a warning. See the AI hook documentation.

Codex

Add the marketplace, then install gitguardian from the plugin browser:

codex plugin marketplace add GitGuardian/agent-skills
codex
/plugins

Requires Codex CLI v0.117.0 or later. Select the GitGuardian marketplace, open gitguardian, and choose Install plugin.

VS Code with GitHub Copilot

Open the Command Palette, run Chat: Install Plugin From Source, and paste:

https://github.com/GitGuardian/agent-skills

Copilot detects the plugin manifest and installs the gitguardian plugin.

Cursor and 50+ other agents

Install with the skills.sh CLI:

npx skills add gitguardian/agent-skills

This works with Cursor, GitHub Copilot, OpenCode, Cline, Windsurf, Gemini CLI, Kiro CLI, and other supported agents.

Kiro

1. Open Kiro and go to Powers -> Add Power.

2. Choose Add power from GitHub URL.

3. Enter:

   https://github.com/GitGuardian/agent-skills/tree/main/kiro
   

If your Kiro version does not accept a GitHub subdirectory, clone this repo and add the local kiro/ folder instead.

Example Prompts

Scan For Secrets

Scan this repo for hardcoded credentials
Audit the full git history for leaked secrets
Scan my staged changes once now, without committing
Find the secrets I leaked in commit abc1234
Scan this Docker image for embedded credentials

Plant Honeytokens

Drop a honeytoken in my .env.example before I publish this repo
Generate a decoy AWS credential for my Confluence runbook
Plant a tripwire credential so I know if anyone clones our archived repos
Create a honeytoken for the staging deploy script

Scan A Whole Machine

Audit my whole machine for credentials before I wipe it
Scan my home folder for AWS keys and SSH credentials
What credentials are sitting on this machine?
Check ~/.aws, ~/.kube and my shell history for live tokens

Check Known Credentials With HMSL

I inherited a .env from a former teammate. Check if any of these are compromised
Run an HMSL check on this list of API keys
Show me which of these credentials have appeared in public leaks

For HMSL, the agent should not run the check itself. It should hand you a command such as:

ggshield hmsl check /path/to/secrets.txt --json -n none

You run it locally, then paste back only sanitized --json -n none output or a human summary.

How the Skills Work

Every skill is self-contained:

skills/<skill>/
  SKILL.md              # entry point the agent reads first
  references/           # deeper workflow docs loaded only when needed
  evals/                # optional eval prompts and fixtures

Design choices:

• CLI-first scanning. Secret detection uses ggshield because it can scan paths, staged changes, history, commits, Docker images, and packages locally.
• Progressive disclosure. SKILL.md stays short enough to load quickly; long remediation, setup, and workflow details live in references/.
• Structured remediation. scan-secrets points to the GitGuardian Remediation Doctrine before advising on rotation, false positives, history rewrite, or HMSL follow-up.
• HMSL handoff. check-hmsl is intentionally user-run only. The agent prepares commands and interprets sanitized output, but it must not read credential files or invoke ggshield hmsl on them.
• Cross-agent packaging. The same skills ship through Claude Code, Codex, Cursor, VS Code Copilot, skills.sh, and Kiro-specific power files.

Requirements

• A GitGuardian account. The free tier is enough for repo scanning and basic setup.
• ggshield 1.49.0 or later for full hook support.
• Additional workspace capabilities for some flows:
  • Honeytokens require Manager access and a token with honeytokens:write.
  • Machine scans require endpoint scanning enabled on the workspace.
  • Authenticated HMSL checks use the user's workspace quota; anonymous checks have lower quota.

Bundled MCP Server

The plugin includes GitGuardian Developer MCP server configuration for supported hosts:

Host	Config file
Claude Code	.mcp.json
Codex	.codex-mcp.json
Cursor	mcp.json

The MCP server adds GitGuardian API-backed tools for incident triage and honeytoken management. Secret scanning stays CLI-first through ggshield, because the skills need local path, staged-change, history, Docker image, and package scanning.

All three clients use the hosted server (https://mcp.gitguardian.com/mcp) with OAuth — no local install or token setup needed. Claude Code and Cursor trigger the browser login automatically on first use; Codex needs a one-time codex mcp login GitGuardian. For EU SaaS, use https://mcp.eu1.gitguardian.com/mcp instead. For self-hosted GitGuardian or CI/CD, see the local stdio (PAT) instructions.

Project Structure

agent-skills/
|-- .claude-plugin/         # Claude Code plugin manifest and marketplace entry
|-- .cursor-plugin/         # Cursor plugin manifest and marketplace entry
|-- .codex-plugin/          # Codex plugin manifest
|-- .agents/plugins/        # Codex repo-scoped marketplace
|-- skills/                 # self-contained GitGuardian skills
|   |-- scan-secrets/       # secret detection and remediation
|   |-- create-honeytokens/ # honeytoken generation and planting
|   |-- scan-machine/       # endpoint-wide credential inventory
|   |-- check-hmsl/         # user-run public leak checks for known credentials
|   |-- install-hooks/      # install ggshield as a git or AI-assistant hook
|   `-- triage-incidents/   # triage & remediate dashboard incidents via the GG Developer MCP
|-- kiro/                   # Kiro power (Agent Plugins format: plugin.json + skills/ + mcp.json)
|-- test/                   # install-flow sanity tests
`-- assets/                 # README visual assets

Local Development

Load the repo directly while editing skills:

claude --plugin-dir /path/to/agent-skills

For Codex:

codex plugin marketplace add file:///path/to/agent-skills
codex
/plugins

For Cursor:

ln -s /path/to/agent-skills ~/.cursor/plugins/local/gitguardian

Reload the host after editing SKILL.md files. Claude Code can pick up changes with /reload-plugins.

Testing

Install dependencies once:

npm install

Run the install-flow sanity suite:

npm run test:sanity

Other validation used in CI:

for f in $(find . -name '*.json' -not -path './.git/*' -not -path './node_modules/*'); do jq empty "$f"; done
find skills -mindepth 1 -maxdepth 1 -type d ! -name '*-workspace' -exec skills-ref validate {} \;
ggshield secret scan path -r -y .

CI also runs claude plugin validate . and a repo-wide ggshield scan to catch accidental secrets before merge.

License

MIT