Skip to content

Commit ac3b0ba

Browse files
DavidKorczynskiDavidKorczynski
authored
infra: experimental: agent: extend README (#15494)
Signed-off-by: David Korczynski <david@adalogics.com>
1 parent a28842b commit ac3b0ba

1 file changed

Lines changed: 140 additions & 4 deletions

File tree

‎infra/experimental/agent-skills/README.md‎

Lines changed: 140 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,145 @@
11
# OSS-Fuzz agent skills
22

3-
Skills that can be easily used with agents e.g. gemini CLI.
3+
Skills and tooling that let an agent CLI (Gemini CLI or Claude Code) write,
4+
build, and extend OSS-Fuzz fuzzing integrations. The folder ships:
45

6+
- Six skills that give an agent OSS-Fuzz-specific knowledge.
7+
- `infra/experimental/agent-skills/helper.py`, a wrapper that launches agent
8+
sessions over one or more OSS-Fuzz projects in parallel.
9+
- `copy_to_global.sh`, an installer that places the skills where your
10+
agent CLI can find them.
511

6-
# Threat model for running
7-
This is experimental code and has an open threat model. By design, the agents execute untrusted code and are running in "dangerous"/"yolo" modes. As such, when running this tool you should assume you will be running untrusted code on your machine. You should only run this in a trusted environment and on a trusted network. In practice, this means you must run this in a heavily sandboxed environment, and from a security perspective if you run this tool you will run untrusted code in your environment.
12+
Before running anything in this folder, review the [threat model](#threat-model).
13+
This tooling is experimental and runs agents in unrestricted modes.
814

9-
This code does not run in OSS-Fuzz production services and is not part of the tooling that runs our continuous fuzzing of open source projects.
15+
## Contents
16+
17+
| Item | Purpose |
18+
|---|---|
19+
| `fuzzing-memory-unsafe-expert/` | Skill: fuzz C/C++ projects |
20+
| `fuzzing-go-expert/` | Skill: fuzz Go projects |
21+
| `fuzzing-rust-expert/` | Skill: fuzz Rust projects (cargo-fuzz) |
22+
| `fuzzing-jvm-expert/` | Skill: fuzz JVM projects (Java/Kotlin/Scala) with Jazzer |
23+
| `fuzzing-python-expert/` | Skill: fuzz Python projects with Atheris |
24+
| `oss-fuzz-engineer/` | Skill: OSS-Fuzz infra workflows (integrate, fix, extend) |
25+
| `infra/experimental/agent-skills/helper.py` | Driver that launches agent sessions per OSS-Fuzz project |
26+
| `copy_to_global.sh` | Installs the skills into `~/.gemini/skills` or `~/.claude/skills` |
27+
28+
See each skill's `SKILL.md` for the detailed guidance the agent receives.
29+
30+
## Prerequisites
31+
32+
- A supported agent CLI installed and on `PATH`:
33+
[Gemini CLI](https://github.com/google-gemini/gemini-cli) or
34+
[Claude Code](https://claude.com/claude-code).
35+
- Docker (required by OSS-Fuzz's own `infra/helper.py`, which the agent calls).
36+
- Python 3.
37+
- A local checkout of OSS-Fuzz — `infra/experimental/agent-skills/helper.py`
38+
resolves the repo root relative to its own location, so run it from this
39+
checkout.
40+
41+
## Quick start
42+
43+
```bash
44+
# 1. Install the skills into your agent CLI.
45+
./copy_to_global.sh gemini # or: ./copy_to_global.sh claude
46+
47+
# 2. Confirm the agent CLI is reachable.
48+
gemini --version # or: claude --version
49+
50+
# 3. Run a task across one or more OSS-Fuzz projects.
51+
python infra/experimental/agent-skills/helper.py fix-builds open62541 json-c htslib
52+
```
53+
54+
`copy_to_global.sh` **overwrites** any existing skill of the same name in the
55+
target directory.
56+
57+
## How the skills are used
58+
59+
There are two ways the skills get invoked:
60+
61+
1. **Interactively, in your agent CLI.** After `copy_to_global.sh`, the
62+
skills appear to your agent and are auto-selected when a task matches the
63+
skill's description. For example, asking the agent to write a Python
64+
harness will surface `fuzzing-python-expert`. You can use the skills this
65+
way without ever touching `infra/experimental/agent-skills/helper.py`.
66+
67+
2. **Driven by `infra/experimental/agent-skills/helper.py`.** The helper
68+
builds task-specific prompts that reference these skills and launches
69+
non-interactive agent sessions, one per OSS-Fuzz project, in parallel.
70+
Use this when you want to run the same task across many projects.
71+
72+
The agent makes local changes and writes a per-project report. It does
73+
**not** commit or push — review the diff and reports before you do anything
74+
with the output.
75+
76+
## `infra/experimental/agent-skills/helper.py` commands
77+
78+
Run `python infra/experimental/agent-skills/helper.py <command> --help` for
79+
full flag listings. A summary of the available subcommands:
80+
81+
| Command | Purpose | Example |
82+
|---|---|---|
83+
| `expand-oss-fuzz-projects` | Add new harnesses / improve coverage on existing projects | `python infra/experimental/agent-skills/helper.py expand-oss-fuzz-projects open62541 json-c` |
84+
| `fix-builds` | Diagnose and fix broken project builds | `python infra/experimental/agent-skills/helper.py fix-builds htslib` |
85+
| `run-task` | Run an arbitrary `--task` string per project | `python infra/experimental/agent-skills/helper.py run-task --task "Add a harness for the XML attribute parser" open62541` |
86+
| `add-chronos-support` | Add Chronos support to a project | `python infra/experimental/agent-skills/helper.py add-chronos-support json-c` |
87+
| `integrate-project` | Onboard a new project from a Git URL | `python infra/experimental/agent-skills/helper.py integrate-project https://github.com/org/repo` |
88+
| `clean` | Remove local artifacts from previous agent runs | `python infra/experimental/agent-skills/helper.py clean open62541` |
89+
| `show-prompt` | Print the prompt that would be sent, without launching the agent | `python infra/experimental/agent-skills/helper.py show-prompt fix-builds htslib` |
90+
91+
### Useful behaviors and flags
92+
93+
- **Parallelism.** Sessions run in parallel with `DEFAULT_MAX_PARALLEL = 2`.
94+
Override with the helper's parallelism flag if your machine can handle
95+
more concurrent Docker builds.
96+
- **Agent auto-detection.** `infra/experimental/agent-skills/helper.py`
97+
locates the agent CLI on `PATH` automatically — you do not need to tell
98+
it whether you are using Gemini CLI or Claude Code.
99+
- **Dry runs.** `show-prompt` prints the exact prompt that would be sent.
100+
Use it first when trying a new command or task description.
101+
- **Reports and logs.** Each session writes a per-project report locally;
102+
review these before acting on the agent's changes.
103+
104+
## Typical workflows
105+
106+
**Triage a batch of broken projects**
107+
108+
```bash
109+
python infra/experimental/agent-skills/helper.py show-prompt fix-builds proj1 proj2
110+
python infra/experimental/agent-skills/helper.py fix-builds proj1 proj2
111+
# Review the diff and per-project reports, then commit manually.
112+
```
113+
114+
**Onboard a new project end-to-end**
115+
116+
```bash
117+
python infra/experimental/agent-skills/helper.py integrate-project https://github.com/org/repo
118+
# The agent uses oss-fuzz-engineer plus the appropriate fuzzing-*-expert
119+
# skill for the project's language.
120+
```
121+
122+
**Expand coverage on a project you already maintain**
123+
124+
```bash
125+
python infra/experimental/agent-skills/helper.py expand-oss-fuzz-projects myproj
126+
```
127+
128+
**Run a custom investigation across several projects**
129+
130+
```bash
131+
python infra/experimental/agent-skills/helper.py run-task \
132+
--task "Investigate why the XML parser harness has low branch coverage \
133+
and add targeted harnesses for the attribute-parsing paths." \
134+
open62541 json-c
135+
```
136+
137+
## Threat model
138+
139+
This is experimental code with a deliberately permissive threat model:
140+
141+
- Agents run in "dangerous"/"yolo" modes and will execute untrusted code.
142+
- Running this tooling means running untrusted code in your environment.
143+
- Only run it in a heavily sandboxed environment and on a trusted network.
144+
- This code does **not** run in OSS-Fuzz production services and is not part
145+
of the tooling that runs our continuous fuzzing of open source projects.

0 commit comments

Comments
 (0)