Vulnerability Validation Skill

Portable Agent Skill that discovers new vulnerabilities (0-days) in a target repository and then validates them. It is designed for Codex, Claude Code, Gemini CLI, GitHub Copilot, and Google Antigravity users who need a repeatable workflow for finding, proving, rejecting, fixing, and packaging security findings. By default it runs native discovery (finding_source_type = native_discovery): with no findings list it analyzes the code to find vulnerabilities itself — attack-surface mapping and variant analysis, bounded by a declared stopping criterion — then drives every candidate through the same empirical validation machinery; see skill-core/references/discovery-intake.md. A scanner finding, researcher report, or PoC is an optional seed, not a prerequisite, and the skill takes no hard dependency on an external discovery upstream.

Supported Agents

Agent	First-party generated surface	Additional project context
Codex	.agents/skills/vulnerability-validation/ and agents/openai.yaml	AGENTS.md
Claude Code	.claude/skills/vulnerability-validation/	generated CLAUDE.md importing AGENTS.md
Gemini CLI	natively-discovered skill under .gemini/skills/vulnerability-validation/	generated GEMINI.md importing AGENTS.md
GitHub Copilot	.github/copilot-instructions.md (repo-wide); native skill discovery reads the .agents/skills//.claude/skills/ packages	Copilot surfaces that support agent instructions can also consume AGENTS.md, CLAUDE.md, or GEMINI.md
Google Antigravity	IDE/platform natively discovers the .agents/skills/vulnerability-validation/ package (shared with Codex); Google's codelab gives the Antigravity CLI project path as both .agent/skills/ and .agents/skills/, so both packages are generated	AGENTS.md (natively mounted)

Latest supported-agent feature refresh: 2026-06-25 (see skill-core/references/agent-feature-matrix.md).

Other tools that read the open AGENTS.md standard (for example Cursor, Windsurf, Aider, Zed, Cline) may work unmodified via that file but are not first-party supported or tested.

All five are first-party supported surfaces. Copilot is not a local CLI smoke target in this repo; its supported surfaces are native skill discovery (Copilot cloud agent, code review, CLI, app, and VS Code read the generated .agents/skills//.claude/skills/ packages — equivalent project skill locations), GitHub's repo-wide custom-instructions file, and the agent-instruction files that supported Copilot environments read. Google Antigravity natively recognizes the .agents/ directory — the IDE/platform mounts AGENTS.md and discovers the .agents/skills/ package (shared with Codex). Google's codelab gives the Antigravity CLI's project path inconsistently (.agent/skills/ and .agents/skills/), so both packages are generated and the CLI discovers the skill either way; the Antigravity CLI is not a local smoke target here.

Gemini CLI transition

Per Google's 2026-05-19 announcement, the hosted Gemini CLI and Gemini Code Assist IDE extensions stop serving free, Google AI Pro, and Ultra individuals on 2026-06-18. Organizations on a Gemini Code Assist Standard or Enterprise license are unaffected, and the open-source github.com/google-gemini/gemini-cli repository remains maintained — so Gemini CLI stays first-party here. Google positions the Antigravity CLI as the successor surface for individuals; this repository supports both. Gemini CLI users keep the .gemini/skills/vulnerability-validation/ package and generated GEMINI.md, and individuals moving to Antigravity get the IDE and CLI surfaces described above. Sources are recorded in docs/authoritative-sources.md.

Layout

• skill-core/: canonical skill body and references
• .agents/skills/vulnerability-validation/: Codex-ready skill surface
• .claude/skills/vulnerability-validation/: Claude Code skill mirror
• .gemini/skills/vulnerability-validation/: Gemini CLI natively-discovered skill
• .agent/skills/vulnerability-validation/: Google Antigravity CLI skill (singular .agent/; Google's docs also give the plural CLI path, covered by the shared .agents/skills/ package)
• AGENTS.md: canonical repo working agreement
• CLAUDE.md and GEMINI.md: generated agent-native repo instruction mirrors
• .github/copilot-instructions.md: generated repo-wide Copilot instruction surface
• scripts/sync_agent_surfaces.py: regenerates agent-native surfaces from canonical files
• tests/: drift, contract, workflow, and typo/provenance-hygiene checks

Use

Codex scans .agents/skills in a repository. Claude Code can use the mirrored .claude/skills/vulnerability-validation directory. Gemini CLI natively discovers the skill under .gemini/skills/vulnerability-validation (and reads .agents/skills as an alias), and uses GEMINI.md as hierarchical context importing AGENTS.md. GitHub Copilot uses the generated repo-wide .github/copilot-instructions.md surface and, in Copilot environments that support agent instructions, the generated/imported AGENTS.md, CLAUDE.md, or GEMINI.md context files.

Install into your repository

Each generated skill package is self-contained — the SKILL.md entrypoint embeds the full canonical body, and the package ships its own references/ and the bundled artifact validator under scripts/. To install, copy the package directory for your agent into the same path in your repository:

• Codex: copy .agents/skills/vulnerability-validation/; optionally also copy agents/openai.yaml to enable implicit invocation.
• Claude Code: copy .claude/skills/vulnerability-validation/.
• Gemini CLI: copy .gemini/skills/vulnerability-validation/, or rely on a copied .agents/skills/ package, which Gemini reads as an alias.
• GitHub Copilot: copy .agents/skills/vulnerability-validation/ or .claude/skills/vulnerability-validation/ (equivalent project skill locations).
• Google Antigravity: the IDE/platform reads .agents/skills/vulnerability-validation/ (copy it, same as Codex); Google's docs give the Antigravity CLI's project path as both .agent/skills/ and .agents/skills/, so both packages are provided — copy whichever your CLI build resolves. Antigravity also reads AGENTS.md natively.

No other files from this repository are required at runtime; the rest of the repo is packaging, sync tooling, and tests for maintaining the skill itself.

Discover and invoke

• Codex — run /skills to browse and select the skill, or type $vulnerability-validation in the composer to invoke it explicitly; implicit invocation is enabled via agents/openai.yaml.
• Claude Code — type /vulnerability-validation, or let Claude auto-load it from its description; the project skill lives under .claude/skills/.
• Gemini CLI — natively discovered from .gemini/skills/ (and the .agents/skills/ alias); Gemini selects it when a task matches its description. Run /skills list to browse installed skills, or gemini skills install <repo-url> to install this skill from its repository URL.
• GitHub Copilot — the skill is discovered on demand from the generated .agents/skills/ and .claude/skills/ packages by Copilot cloud agent, code review, the CLI, the app, and VS Code (equivalent project skill locations); the repo-wide .github/copilot-instructions.md is also applied automatically to Copilot requests in this repository.
• Google Antigravity — the IDE/platform natively discovers the skill from .agents/skills/ (and mounts AGENTS.md); Google's docs give the Antigravity CLI's project path as both .agent/skills/ and .agents/skills/, so both are provided. Antigravity selects the skill when a task matches its description (progressive disclosure on the SKILL.md description).

Preferred edit path:

make sync
make lint
make verify

On hosts without make (for example native Windows), use that platform's Python launcher (python, python3, or py -3) with the equivalent stdlib commands:

python scripts/sync_agent_surfaces.py
python scripts/sync_agent_surfaces.py --check
python scripts/lint_repo.py
python -m unittest discover -s tests

The canonical body is skill-core/vulnerability-validation.md. If a generated Codex, Claude, Gemini, Copilot, or Antigravity surface needs a content change, make that change in skill-core/, skill.json, or AGENTS.md first, then run make sync. Generated agent-native files are packaging outputs only.

Make targets

• make sync regenerates agent-native mirrors from canonical sources.
• make lint checks generated surfaces are current and runs scripts/lint_repo.py.
• make test runs python3 -m unittest discover -s tests (deterministic, offline).
• make verify is lint + test + integration-test.
• make optimization-check is a fast named gate that runs a curated set of idiomatic-correctness tests against the latest agent-skill conventions (Open Agent Skills frontmatter, Codex / Claude Code / Gemini CLI / GitHub Copilot / Google Antigravity surface conventions, canonical-body line cap, schema-in-references discipline, and GitHub Copilot custom-instructions shape), the mandatory cross-agent skill-optimization review, the supported-OS portability review, and the size/speed regression guard from reviews/public-disclosure-correlation-consensus.md.
• make integration-test runs python3 -m unittest discover -s integration_tests. Tests there auto-skip when the corresponding CLI is absent and require explicit INTEGRATION_TEST_USE_REAL_AUTH=1 to consume real auth/quota. See integration_tests/README.md for the rules each test must follow.
• make ci runs the full local pipeline without rerunning lint through overlapping targets: lint + optimization-check + test + privacy-check + review-invariants-check + integration-test.

To exercise the skill against installed agent CLIs, install whichever you need (links go to authoritative documentation recorded in docs/authoritative-sources.md). Copilot is verified through repository custom instructions and supported Copilot agent-instruction surfaces rather than a local smoke-test CLI. The Antigravity CLI is likewise not a local smoke target here; it is verified through its native Antigravity skills discovery:

• Claude Code: https://code.claude.com/docs/en/skills
• OpenAI Codex CLI: https://developers.openai.com/codex/cli
• Google Gemini CLI: https://github.com/google-gemini/gemini-cli
• GitHub Copilot repository instructions: https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions
• Google Antigravity Agent Skills: https://ai.google.dev/gemini-api/docs/antigravity-agent

CI

The GitHub workflow uses shallow checkout and, on pushes, verifies the agent-native mirrors are current against canonical sources (fail-on-drift via sync_agent_surfaces.py --check) rather than committing regenerated mirrors back, so every job runs with read-only contents permission and no write token. It runs lint, named gates, and unit tests without duplicate make verify work. Pull requests run the Ubuntu read-only gates and a Python-only cross-OS matrix on Ubuntu, macOS, and Windows. The matrix uses fixed python commands rather than shell-expanded matrix values and fails if generated files are stale, review invariants drift, lint fails, or unit tests fail on any OS. Both the pull-request and push jobs also run make integration-test: its deterministic, network-free checks always execute, while live-CLI smoke tests auto-skip on CI runners because the agent CLIs and the explicit real-auth opt-in are absent. Run make integration-test (or make ci) on a developer machine with agent CLIs installed to exercise the live smoke paths.

Portability

The skill body stays OS-neutral. Repository maintenance instructions use make as the preferred path and document equivalent Python commands for hosts without make. Opt-in live CLI smoke tests isolate HOME, Windows profile/cache variables, and temp variables under a skill-owned temporary root. Codex CLI itself supports macOS, Windows, and Linux; the current Codex smoke test uses POSIX PTY support and therefore covers macOS/Linux/WSL while skipping cleanly on native Windows until a Windows-safe runner is added.

License

Licensed under the Apache License, Version 2.0. See LICENSE and NOTICE.