Agent Instructions

This file is the contract for any AI agent or human contributor working on this repo. (The skills in skills/ are the contract between agents and users of the skills — different audience.)

Read at the repo root as AGENTS.md (cross-vendor agents.md convention) or as CLAUDE.md (symlink, for Claude Code's project-instruction lookup). One file, two entry points — editing either follows automatically.

Deep reference for specific tasks lives under docs/maintainers/ and is loaded on demand — see Maintainer references at the bottom. Keep this file terse: it loads into every session.

Project Overview

This repo ships skill files that teach AI coding agents how to use ggshield, GitGuardian's open-source CLI. The agent invokes ggshield directly; the skill files supply the missing instructions on when, how, and what to do with the output.

Target agents: Claude Code directly via the plugin marketplace, Cursor via the .cursor-plugin/ manifest, Codex via the .codex-plugin/ manifest (and the repo-scoped .agents/plugins/marketplace.json), and ~50 other agents (Kiro CLI, Copilot, OpenCode, Cline, Windsurf, Gemini CLI, …) via the skills.sh CLI.

Repository Structure

.claude-plugin/        # Claude Code plugin metadata (marketplace.json + plugin.json)
.cursor-plugin/        # Cursor plugin metadata (same two files)
.codex-plugin/         # Codex plugin metadata (plugin.json only)
.agents/plugins/       # Codex repo-scoped marketplace (marketplace.json)
.codex-mcp.json        # Codex MCP server config (Claude: .mcp.json, Cursor: mcp.json)
.github/workflows/     # CI: JSON + frontmatter validation, install-flow sanity, release automation
test/sanity.test.ts    # install-flow sanity tests (vitest)
package.json           # tooling-only (vitest); no runtime deps
release-please-*.{json} # Release Please config + released-version manifest
skills/<name>/         # one folder per skill (folder name = SKILL.md frontmatter `name:`)
  SKILL.md             #   what the agent reads first
  references/<topic>.md #  long-form, loaded on demand; shared refs duplicated per skill
  evals/               #   evals.json + targets.json + files/ fixtures (scan-secrets, check-hmsl)
kiro/                  #   legacy Kiro power copy (Kiro now installs from the root); not kept in sync
docs/maintainers/      # task-gated reference for working ON this repo (see bottom of this file)
README.md              # user-facing: what / install / what-you-can-do
LICENSE                # MIT

The six skills are scan-secrets, create-honeytokens, scan-machine, check-hmsl, install-hooks, triage-incidents. Shared references (ggshield-cli-setup.md, gitguardian-platform.md, and hook-selection.md for scanning/hook setup) are duplicated into every skill that links to them — see Skills are self-contained.

Skills index

Slash commands

Every skill is invokable as a slash command — /gitguardian:<skill-name> (Claude Code) or the equivalent in Cursor. We do not ship a separate commands/ directory; that's the legacy "flat .md as skill" pattern Anthropic now recommends against (see Critical structural rules in docs/maintainers/distribution.md).

The skill description (frontmatter) is what shows up in the slash-command autocomplete dropdown. Keep it action-verb-first ("Scan code for hardcoded secrets…", "Generate a GitGuardian honeytoken…") so it reads as a label, with the auto-trigger conditions following ("Auto-triggers when …") so model-driven invocation still works.

Commit attribution

AI-authored commits must include the model byline:

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Replace with the actual model that authored the work. This is non-negotiable on this repo — the lineage matters for review and provenance.

Key conventions

These are repo-wide rules. Not preferences, conventions — break them and a reviewer will push back.

Naming layers (brand vs capability vs tool)

The repo's user-facing surface has three distinct layers, and the right name lives at the right layer:

Layer 3 is plumbing. It appears in each skill's ## Overview, ## Commands, and ## Troubleshooting sections — because users need to know which tool runs and how to install it — but never in a skill folder name, command name, or plugin namespace.

Concretely:

• Skill folder is scan-secrets/, not ggshield-scan-secrets/. If we add API-backed scanning later, the same skill teaches both paths.
• Slash command is /gitguardian:scan-secrets, not /ggshield:scan-secrets. The plugin namespace is the brand; the suffix after : is the skill name (which is the action); nothing in between says which tool runs it.
• The plugin description is broad ("via ggshield, the Developer MCP server, and the GitGuardian API") so it doesn't lock us into one tool.
• The ggshield keyword stays in plugin.json so users searching the marketplace for "ggshield" still find this plugin — discovery is a separate concern from naming.

When in doubt, ask: would this name still be right if we swapped the underlying tool? If no, the tool name is in the wrong layer.

Skill folder naming

Verb-noun, no product prefix. scan-secrets, create-honeytokens, check-hmsl, scan-machine. The plugin name is already gitguardian — prefixing every skill with gitguardian- or ggshield- is redundant. Matches the convention used across mature multi-skill plugin repos.

Long-form content goes under references/

Anything past ~150 lines, anything heavily detailed (alert response, planting strategy, full command variants with examples) lives in skills/<name>/references/<topic>.md. The SKILL.md stays terse and points at the reference. Lets the agent decide on demand what to load.

Skills are self-contained — references live inside each skill

Every reference file lives inside its owning skill at skills/<name>/references/<file>.md. There is no bundle-root references/ directory. SKILL.md files link to references as bare relative paths (references/<file>.md), which is the canonical pattern documented at https://code.claude.com/docs/en/skills#add-supporting-files and used by supabase/agent-skills and getsentry/sentry-for-ai — the two largest precedents.

This means truly-shared content (e.g., ggshield-cli-setup.md and gitguardian-platform.md) is duplicated into every skill that links to it. Yes, that means 4 copies. The DRY cost is real, and it's the price for two properties we need:

• Every skill works in isolation. A user who installs only check-hmsl via npx skills add --skill check-hmsl gets a complete skill folder with all its references resolved. Bundle-root references break this case.
• Path resolution is platform-independent. Codex, Claude Code, Cursor, and skills.sh all interpret references/<file>.md as relative to the SKILL.md location. Bundle-root ../../references/<file>.md is non-standard and surfaced agent-side resolution bugs in practice (see commit history for the Codex-on-/references/ failure).

Edit discipline. When you change a duplicated reference file in one skill, propagate the same change to every other skill that has a copy. A CI check that diffs the duplicated files would catch drift if/when this becomes a recurring problem. See docs/maintainers/contributing.md for the checksum check.

Skill-specific references (no duplication) — scan-secrets/references/workflows.md, create-honeytokens/references/planting-strategy.md — live alongside the shared ones in the same references/ folder; only the content differs in whether it has copies elsewhere.

The remediation doctrine

Remediation guidance is per-skill, not shared. Each skill that needs to tell the user what to do with a found credential gets its own remediation doctrine, tailored to that skill's detection context. There is no single cross-skill doctrine duplicated everywhere — that was tried and the fit was poor (an HMSL match is always public-facing; a honeytoken is never rotated; a machine-scan finding is always off-repo), so each skill's reality is different enough to warrant its own doctrine.

Current state:

• scan-secrets/references/remediation-doctrine.md — the full doctrine: four triage axes, four deliverable modes, four lifecycle tracks (pre-leak, post-leak public, post-leak internal-private, off-repo), a credential-lifecycle section that states where type-specific mechanics come from instead of carrying vendor runbooks, the generic coordination framework, public-leak takedown, and per-mode validation. SKILL.md routes here directly when findings are present; the sibling interpreting-results.md is a separate reference for reading ggshield output (JSON shape, validity, severity), the HMSL handoff, and ggignore false positives — it is not a remediation file. This doctrine is also the right basis for a future incident-management skill, which shares scan-secrets' full-lifecycle detection context.
• check-hmsl — keeps a short, self-contained remediation reminder inline (an HMSL match is always public-facing, so "it's burned, rotate it" is the whole story for now).
• scan-machine and create-honeytokens — retain their existing remediation prose for now; each will get its own tailored doctrine later.

Do not re-introduce a single shared doctrine duplicated across these skills to cover them — author per-skill doctrines instead.

When you add a remediation doctrine for another skill, author it for that skill's detection context rather than copying scan-secrets' wholesale.

SKILL.md section order

## Overview
## When to Use
## Onboarding (first use)            ← setup BEFORE commands, since commands are useless without it
    ### Prerequisites
    ### Setup
## Commands (or skill-specific reference)
## Best Practices
## Troubleshooting

Onboarding before Commands is deliberate: every command in the reference is useless until ggshield is installed and authenticated. A new user landing on the skill should hit the install path first.

Frontmatter description: is a trigger statement, not a feature list

Claude Code and Cursor auto-trigger skills by matching this field against the user's prompt and the current file context. Write it as:

Use when <concrete user condition>, when <file pattern>, when <error message>. Use when <explicit ask>.

Keep it to ~50–60 words. Drop redundant credential-type enumerations and troubleshooting-detail hooks that belong in the Troubleshooting section.

No markdown or bracketed prefixes in description. No *emphasis*, **bold**, backticks, or [USER-RUN ONLY …] / [AGENT-EXECUTABLE] prefixes — they render as literal noise in catalog indices and machine-parsed dropdowns. Write plain prose.

Do not mention execution in the description unless the skill is the command-handoff exception. Agent-executable is the default, so stating it ("the agent runs X directly", "agent-executable") is noise — leave it out. Only a skill with command-handoff: "true" (below) states its execution contract in the description, and as a sentence ("User-run only — the agent prepares the commands, the user runs them…"), not a bracket. The machine-readable flag lives in metadata; the runtime enforcement lives in the body (the check-hmsl STOP block) — never collapse that human-readable contract out of a command-handoff skill's description.

metadata.command-handoff and metadata.version

Every SKILL.md carries a metadata block (a string→string map per the agent-skills spec):

metadata:
  version: "0.1.4" # x-release-please-version

• command-handoff — the exception flag, set to "true" only on a skill where the agent must not run the tool itself. Skills are agent-executable by default, so the default carries no flag. The exception exists when running the command would pull sensitive content into the agent's context — e.g. check-hmsl, where reading the credential file or echoing its contents into the thread defeats HMSL's local-hashing protocol. On those skills the agent's job is to build the command and hand it to the user to run, then interpret the sanitized output the user pastes back. Only check-hmsl carries it today:

  metadata:
    command-handoff: "true"
    version: "0.1.4" # x-release-please-version

  It is a label for catalogs/validators/routers — it does not enforce anything; the body (STOP block) is the enforcement.

• version — mirrors the plugin/package version; not an independent per-skill semver. The line carries an # x-release-please-version annotation and is registered as a generic extra-file in release-please-config.json, so Release Please bumps it in lockstep with the manifests (see docs/maintainers/releasing.md). Quote it so YAML reads it as a string; never hand-edit it out of step.

license: and compatibility: are required on every skill

Both are optional in the agent-skills spec; both are mandatory here. They sit between description: and metadata:, matching the spec's own field order.

• license: MIT — same on every skill, mirroring the repo's root LICENSE. A skill installed on its own via npx skills add --skill <name> travels without that file, so the frontmatter is the only place its license is legible.
• compatibility: — the skill's real environment requirements, in one sentence, max 500 chars. This is the machine-readable version of the skill's own ### Prerequisites section, so the two must agree: when you raise a minimum ggshield version or add a required scope in Prerequisites, update compatibility in the same commit.

Write what this skill needs, not what the bundle needs — the field earns its place by differentiating. triage-incidents needs ggmcp and no CLI at all; scan-machine needs endpoint scanning enabled server-side; create-honeytokens needs a Manager seat and the honeytokens:write scope; check-hmsl is user-run and works unauthenticated. A generic "requires ggshield" on all six would be worse than nothing.

Mind YAML: an unquoted : inside the value breaks the frontmatter. Rephrase to avoid the colon rather than quoting the whole string. CI catches it — skills-ref validate runs on every skill in validate.yml — but catching it locally is faster.

Verify before claiming

Before listing GitGuardian product capabilities, check gitguardian.com or product docs — do not rely on training data. Before listing ggshield CLI capabilities, run ggshield --help and ggshield <subcommand> --help against the installed version. The product surface and the CLI surface are not the same; GitGuardian has dashboard features (Public Monitoring, NHI Governance) that aren't exposed through ggshield, and ggshield does not ship IaC or SCA scanning despite adjacent vendors doing both.

No git push without explicit consent

The maintainer reviews every push. Always commit, then ask before pushing. "Commit" does not imply "push"; previous consent for one push does not authorize the next. The same applies to deleting remote branches (e.g., during a rename), which is a destructive action — ask first.

No emojis in skill / command content

Keep skill output platform-neutral. Emojis vary in support across the ~50 target agents.

Maintainer references

Task-gated working knowledge lives under docs/maintainers/. Load the relevant file only when you're doing that task — none of it needs to be in always-on context.

Resources

• ggshield CLI: https://github.com/GitGuardian/ggshield
• GitGuardian Developer MCP server: https://github.com/GitGuardian/ggmcp
• GitGuardian public docs: https://docs.gitguardian.com (append .md to any HTML page to get the Markdown version; AI-agent index at https://docs.gitguardian.com/llms.txt)
• Claude Code plugin docs: https://code.claude.com/docs/en/plugins (full vendor docs index in docs/maintainers/distribution.md)
• Codex plugin docs: https://developers.openai.com/codex/plugins
• Cursor plugin template: https://github.com/cursor/plugin-template
• Cursor plugin submission: https://cursor.com/marketplace/publish
• skills.sh CLI (cross-agent installer): https://skills.sh