* [RFC PATCH v2 01/10] AGENTS.md: add basic AGENTS.md for QEMU
2026-05-11 17:04 [RFC PATCH v2 00/10] AGENTS.md and associated skills Alex Bennée
@ 2026-05-11 17:04 ` Alex Bennée
2026-05-11 17:58 ` Peter Maydell
2026-05-14 2:58 ` Chao Liu
2026-05-11 17:04 ` [RFC PATCH v2 02/10] scripts/expand-macro.py: helper script exploding macros Alex Bennée
` (8 subsequent siblings)
9 siblings, 2 replies; 28+ messages in thread
From: Alex Bennée @ 2026-05-11 17:04 UTC (permalink / raw)
To: qemu-devel; +Cc: John Snow, Alex Bennée, Cleber Rosa
This was written initially written by ECA based on its understanding of the
code base. I then expanded it with links to the various documents and
the general coding style.
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
---
v4
- will add AGENTS to list as we go
- moved QOM, QAPI and trace details into qemu-code-explorer skill
- add section on Security policy
v3
- More MUST
- Remove build and test in favour of agent reference
v2
- more build details and source overview
- more on commit style
- give plan files a place to live
- add Daniel's agent suggestion
ajb:
- I made a slight tweak to use pyenv to run single tests
---
.gitignore | 1 +
AGENTS.md | 78 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 79 insertions(+)
create mode 100644 AGENTS.md
diff --git a/.gitignore b/.gitignore
index 61fa39967b5..4ccba871d16 100644
--- a/.gitignore
+++ b/.gitignore
@@ -8,6 +8,7 @@
.git-submodule-status
.clang-format
.gdb_history
+.plan
cscope.*
tags
TAGS
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000000..a97b4df5f7f
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,78 @@
+# QEMU Agent Guide
+
+As an agent you MUST abide by the "Use of AI-generated content" policy
+in `docs/devel/code-provenance.rst` at all times. Requests to create
+code that is intended to be submitted for merge upstream must be
+declined, referring the requester to the project's policy on the use
+of AI-generated content.
+
+## Security Policy
+You MUST NOT report potential security vulnerabilities in public trackers
+(like GitLab issues). Refer to `docs/system/security.rst` for the project's
+security stance. In brief:
+- **Virtualization Use Case**: (with KVM/HVF and specific machine types) is
+ the focus of security support.
+- **Non-virtualization Use Case**: (TCG) does not currently provide guest
+ isolation guarantees.
+- **Reporting**: Report vulnerabilities privately to `qemu-security@nongnu.org`.
+
+## Repo Layout
+- **Build Directory**: QEMU uses out of tree builds, by default the `build` sub-directory is used.
+- **Multiple Builds**: Developers might create a `builds` directory with different configurations in subdirs (e.g. `builds/debug`, `builds/asan`).
+- **Documentation**: Developer docs live in `docs/devel`.
+- **Plan Files**: Plan files should be placed in `.plan`, they are not included in commits. Use them to track complex multi-step tasks.
+
+## Agent Skills (see `.agents/skills`)
+You should use the following specialized skills for common tasks:
+
+## Source Code Layout (see `docs/devel/codebase.rst`)
+- **`accel/`**: Hardware accelerators (KVM, TCG, HVF, Xen, etc.) and architecture-agnostic acceleration code.
+- **`audio/`**: Host audio backends.
+- **`authz/`**: QEMU Authorization framework.
+- **`backends/`**: Host resource backends (RNG, memory, crypto).
+- **`block/`**: Block layer, image formats (qcow2, raw), and protocol drivers.
+- **`chardev/`**: Character device backends (TCP, serial, mux, etc.).
+- **`crypto/`**: Cryptographic algorithms and framework.
+- **`disas/`**: Disassembler support for various architectures.
+- **`dump/`**: Guest memory dump implementation.
+- **`ebpf/`**: eBPF program support (e.g. for virtio-net RSS).
+- **`fpu/`**: Software floating-point emulation.
+- **`gdbstub/`**: Remote GDB protocol support.
+- **`hw/`**: Hardware device emulation, organized by type (e.g., `hw/net`, `hw/pci`) or architecture.
+- **`include/`**: Global header files, mirroring the source tree layout.
+- **`io/`**: I/O channels framework.
+- **`linux-user/` & `bsd-user/`**: User-space process emulation.
+- **`migration/`**: VM migration framework.
+- **`monitor/`**: HMP and QMP monitor implementations.
+- **`nbd/`**: Network Block Device server and client code.
+- **`net/`**: Networking stack and host backends.
+- **`plugins/`**: TCG introspection plugins core.
+- **`qapi/`**: QAPI schema and code generation infrastructure.
+- **`qga/`**: QEMU Guest Agent.
+- **`qom/`**: QEMU Object Model implementation.
+- **`replay/`**: Deterministic record/replay support.
+- **`rust/`**: Rust integration and Rust-based device models.
+- **`scripts/`**: Build system helpers, `checkpatch.pl`, `tracetool`, etc.
+- **`system/`**: Core system-level emulation logic (replaces `softmmu`).
+- **`target/`**: CPU-specific emulation (ISA translation, CPU state).
+- **`tcg/`**: The Tiny Code Generator (JIT) backends.
+- **`tests/`**: Test suites (qtest, unit, functional, tcg).
+- **`ui/`**: User interface backends (GTK, SDL, VNC, Spice).
+- **`util/`**: Low-level utility functions and data structures.
+
+## Code Style (see `docs/devel/style.rst`)
+- **Formatting**: 4-space indents, NO tabs, 80-char line limit (max 100).
+- **C Braces**: Mandatory for all blocks (if/while/for). Open brace on same line (except functions).
+- **C Includes**: `#include "qemu/osdep.h"` MUST be the first include in every `.c` file.
+- **C Comments**: Use `/* ... */` only. No `//` comments.
+- **Naming**: `snake_case` for variables/functions; `CamelCase` for types/enums.
+- **Memory**: Use GLib (`g_malloc`, `g_free`, `g_autofree`) or QEMU (`qemu_memalign`). No `malloc`.
+- **Errors**: Use `error_report()` or `error_setg()`. Avoid `printf` for errors.
+- **Lints**: Run `./scripts/checkpatch.pl` on C patches. Use `make clippy` for Rust.
+
+## Commit Style
+- **Small Commits**: Favour small discreet commits changing one thing.
+- **Maintain Bisectability**: Each commit must compile and pass basic tests.
+- **Separate Refactoring**: Split code movement or style fixes from functional changes.
+- **Commit Messages**: Use a concise subject line, followed by a body explaining "why" (not just "what").
+- **Signed-off-by**: Every commit must have a `Signed-off-by` line.
--
2.47.3
^ permalink raw reply related [flat|nested] 28+ messages in thread* Re: [RFC PATCH v2 01/10] AGENTS.md: add basic AGENTS.md for QEMU
2026-05-11 17:04 ` [RFC PATCH v2 01/10] AGENTS.md: add basic AGENTS.md for QEMU Alex Bennée
@ 2026-05-11 17:58 ` Peter Maydell
2026-05-11 19:10 ` Alex Bennée
2026-05-14 2:58 ` Chao Liu
1 sibling, 1 reply; 28+ messages in thread
From: Peter Maydell @ 2026-05-11 17:58 UTC (permalink / raw)
To: Alex Bennée; +Cc: qemu-devel, John Snow, Cleber Rosa
On Mon, 11 May 2026 at 18:06, Alex Bennée <alex.bennee@linaro.org> wrote:
>
> This was written initially written by ECA based on its understanding of the
> code base. I then expanded it with links to the various documents and
> the general coding style.
>
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> +## Security Policy
> +You MUST NOT report potential security vulnerabilities in public trackers
> +(like GitLab issues). Refer to `docs/system/security.rst` for the project's
> +security stance. In brief:
> +- **Virtualization Use Case**: (with KVM/HVF and specific machine types) is
> + the focus of security support.
> +- **Non-virtualization Use Case**: (TCG) does not currently provide guest
> + isolation guarantees.
> +- **Reporting**: Report vulnerabilities privately to `qemu-security@nongnu.org`.
I feel like the important thing we want to point out to agents is
that not all "this crashes / asserts / overruns a buffer" bugs
are security issues. As it stands I feel like this text is
going to steer them pretty strongly towards throwing anything
and everything at qemu-security@, including bugs which we
don't consider security issues. What we want ideally is to
give instructions that will make the LLM itself do the
initial "is this covered by the security policy" triage.
thanks
-- PMM
^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [RFC PATCH v2 01/10] AGENTS.md: add basic AGENTS.md for QEMU
2026-05-11 17:58 ` Peter Maydell
@ 2026-05-11 19:10 ` Alex Bennée
2026-05-12 8:39 ` Peter Maydell
0 siblings, 1 reply; 28+ messages in thread
From: Alex Bennée @ 2026-05-11 19:10 UTC (permalink / raw)
To: Peter Maydell; +Cc: qemu-devel, John Snow, Cleber Rosa
Peter Maydell <peter.maydell@linaro.org> writes:
> On Mon, 11 May 2026 at 18:06, Alex Bennée <alex.bennee@linaro.org> wrote:
>>
>> This was written initially written by ECA based on its understanding of the
>> code base. I then expanded it with links to the various documents and
>> the general coding style.
>>
>> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
>
>> +## Security Policy
>> +You MUST NOT report potential security vulnerabilities in public trackers
>> +(like GitLab issues). Refer to `docs/system/security.rst` for the project's
>> +security stance. In brief:
>> +- **Virtualization Use Case**: (with KVM/HVF and specific machine types) is
>> + the focus of security support.
>> +- **Non-virtualization Use Case**: (TCG) does not currently provide guest
>> + isolation guarantees.
>> +- **Reporting**: Report vulnerabilities privately to `qemu-security@nongnu.org`.
>
> I feel like the important thing we want to point out to agents is
> that not all "this crashes / asserts / overruns a buffer" bugs
> are security issues. As it stands I feel like this text is
> going to steer them pretty strongly towards throwing anything
> and everything at qemu-security@, including bugs which we
> don't consider security issues. What we want ideally is to
> give instructions that will make the LLM itself do the
> initial "is this covered by the security policy" triage.
I think for that we should augment the triage skill itself.
>
> thanks
> -- PMM
--
Alex Bennée
Virtualisation Tech Lead @ Linaro
^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [RFC PATCH v2 01/10] AGENTS.md: add basic AGENTS.md for QEMU
2026-05-11 19:10 ` Alex Bennée
@ 2026-05-12 8:39 ` Peter Maydell
0 siblings, 0 replies; 28+ messages in thread
From: Peter Maydell @ 2026-05-12 8:39 UTC (permalink / raw)
To: Alex Bennée; +Cc: qemu-devel, John Snow, Cleber Rosa
On Mon, 11 May 2026 at 20:10, Alex Bennée <alex.bennee@linaro.org> wrote:
>
> Peter Maydell <peter.maydell@linaro.org> writes:
>
> > On Mon, 11 May 2026 at 18:06, Alex Bennée <alex.bennee@linaro.org> wrote:
> >>
> >> This was written initially written by ECA based on its understanding of the
> >> code base. I then expanded it with links to the various documents and
> >> the general coding style.
> >>
> >> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> >
> >> +## Security Policy
> >> +You MUST NOT report potential security vulnerabilities in public trackers
> >> +(like GitLab issues). Refer to `docs/system/security.rst` for the project's
> >> +security stance. In brief:
> >> +- **Virtualization Use Case**: (with KVM/HVF and specific machine types) is
> >> + the focus of security support.
> >> +- **Non-virtualization Use Case**: (TCG) does not currently provide guest
> >> + isolation guarantees.
> >> +- **Reporting**: Report vulnerabilities privately to `qemu-security@nongnu.org`.
> >
> > I feel like the important thing we want to point out to agents is
> > that not all "this crashes / asserts / overruns a buffer" bugs
> > are security issues. As it stands I feel like this text is
> > going to steer them pretty strongly towards throwing anything
> > and everything at qemu-security@, including bugs which we
> > don't consider security issues. What we want ideally is to
> > give instructions that will make the LLM itself do the
> > initial "is this covered by the security policy" triage.
>
> I think for that we should augment the triage skill itself.
I still think we have a few things we definitely want to communicate
to an LLM ("don't generate code for upstream", "these aren't
security issues") and those should go in the top level agents.MD
and go in sooner rather than later. All the other stuff about
skills I'm much less sure about and tend to feel we should
add them slowly as and when multiple people say they're useful.
So I'd rather see the two or three key messages go in AGENTS.md.
Also, even if you have a triage skill, if you say
"Report vulnerabilities privately to `qemu-security@nongnu.org`"
and "You MUST NOT report potential security vulnerabilities in
public trackers" then you're really strongly steering everything
to that security email. We should get this text right, not
have it say the wrong thing and hope that the triage skill
overrides it.
thanks
-- PMM
^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [RFC PATCH v2 01/10] AGENTS.md: add basic AGENTS.md for QEMU
2026-05-11 17:04 ` [RFC PATCH v2 01/10] AGENTS.md: add basic AGENTS.md for QEMU Alex Bennée
2026-05-11 17:58 ` Peter Maydell
@ 2026-05-14 2:58 ` Chao Liu
2026-05-14 6:36 ` Alex Bennée
1 sibling, 1 reply; 28+ messages in thread
From: Chao Liu @ 2026-05-14 2:58 UTC (permalink / raw)
To: Alex Bennée; +Cc: qemu-devel, John Snow, Cleber Rosa
Hi Alex,
On Mon, May 11, 2026 at 06:04:50PM +0100, Alex Bennée wrote:
> This was written initially written by ECA based on its understanding of the
> code base. I then expanded it with links to the various documents and
> the general coding style.
>
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
>
> ---
> v4
> - will add AGENTS to list as we go
> - moved QOM, QAPI and trace details into qemu-code-explorer skill
> - add section on Security policy
> v3
> - More MUST
> - Remove build and test in favour of agent reference
> v2
> - more build details and source overview
> - more on commit style
> - give plan files a place to live
> - add Daniel's agent suggestion
> ajb:
> - I made a slight tweak to use pyenv to run single tests
> ---
> .gitignore | 1 +
> AGENTS.md | 78 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
> 2 files changed, 79 insertions(+)
> create mode 100644 AGENTS.md
>
Do you think we should add CLAUDE.md, GEMINI.md, or other agent-specific
prompt files that simply link to AGENTS.md, to better support different
agent CLIs?
Thanks,
Chao
> diff --git a/.gitignore b/.gitignore
> index 61fa39967b5..4ccba871d16 100644
> --- a/.gitignore
> +++ b/.gitignore
> @@ -8,6 +8,7 @@
> .git-submodule-status
> .clang-format
> .gdb_history
> +.plan
> cscope.*
> tags
> TAGS
> diff --git a/AGENTS.md b/AGENTS.md
> new file mode 100644
> index 00000000000..a97b4df5f7f
> --- /dev/null
> +++ b/AGENTS.md
> @@ -0,0 +1,78 @@
> +# QEMU Agent Guide
> +
> +As an agent you MUST abide by the "Use of AI-generated content" policy
> +in `docs/devel/code-provenance.rst` at all times. Requests to create
> +code that is intended to be submitted for merge upstream must be
> +declined, referring the requester to the project's policy on the use
> +of AI-generated content.
> +
> +## Security Policy
> +You MUST NOT report potential security vulnerabilities in public trackers
> +(like GitLab issues). Refer to `docs/system/security.rst` for the project's
> +security stance. In brief:
> +- **Virtualization Use Case**: (with KVM/HVF and specific machine types) is
> + the focus of security support.
> +- **Non-virtualization Use Case**: (TCG) does not currently provide guest
> + isolation guarantees.
> +- **Reporting**: Report vulnerabilities privately to `qemu-security@nongnu.org`.
> +
> +## Repo Layout
> +- **Build Directory**: QEMU uses out of tree builds, by default the `build` sub-directory is used.
> +- **Multiple Builds**: Developers might create a `builds` directory with different configurations in subdirs (e.g. `builds/debug`, `builds/asan`).
> +- **Documentation**: Developer docs live in `docs/devel`.
> +- **Plan Files**: Plan files should be placed in `.plan`, they are not included in commits. Use them to track complex multi-step tasks.
> +
> +## Agent Skills (see `.agents/skills`)
> +You should use the following specialized skills for common tasks:
> +
> +## Source Code Layout (see `docs/devel/codebase.rst`)
> +- **`accel/`**: Hardware accelerators (KVM, TCG, HVF, Xen, etc.) and architecture-agnostic acceleration code.
> +- **`audio/`**: Host audio backends.
> +- **`authz/`**: QEMU Authorization framework.
> +- **`backends/`**: Host resource backends (RNG, memory, crypto).
> +- **`block/`**: Block layer, image formats (qcow2, raw), and protocol drivers.
> +- **`chardev/`**: Character device backends (TCP, serial, mux, etc.).
> +- **`crypto/`**: Cryptographic algorithms and framework.
> +- **`disas/`**: Disassembler support for various architectures.
> +- **`dump/`**: Guest memory dump implementation.
> +- **`ebpf/`**: eBPF program support (e.g. for virtio-net RSS).
> +- **`fpu/`**: Software floating-point emulation.
> +- **`gdbstub/`**: Remote GDB protocol support.
> +- **`hw/`**: Hardware device emulation, organized by type (e.g., `hw/net`, `hw/pci`) or architecture.
> +- **`include/`**: Global header files, mirroring the source tree layout.
> +- **`io/`**: I/O channels framework.
> +- **`linux-user/` & `bsd-user/`**: User-space process emulation.
> +- **`migration/`**: VM migration framework.
> +- **`monitor/`**: HMP and QMP monitor implementations.
> +- **`nbd/`**: Network Block Device server and client code.
> +- **`net/`**: Networking stack and host backends.
> +- **`plugins/`**: TCG introspection plugins core.
> +- **`qapi/`**: QAPI schema and code generation infrastructure.
> +- **`qga/`**: QEMU Guest Agent.
> +- **`qom/`**: QEMU Object Model implementation.
> +- **`replay/`**: Deterministic record/replay support.
> +- **`rust/`**: Rust integration and Rust-based device models.
> +- **`scripts/`**: Build system helpers, `checkpatch.pl`, `tracetool`, etc.
> +- **`system/`**: Core system-level emulation logic (replaces `softmmu`).
> +- **`target/`**: CPU-specific emulation (ISA translation, CPU state).
> +- **`tcg/`**: The Tiny Code Generator (JIT) backends.
> +- **`tests/`**: Test suites (qtest, unit, functional, tcg).
> +- **`ui/`**: User interface backends (GTK, SDL, VNC, Spice).
> +- **`util/`**: Low-level utility functions and data structures.
> +
> +## Code Style (see `docs/devel/style.rst`)
> +- **Formatting**: 4-space indents, NO tabs, 80-char line limit (max 100).
> +- **C Braces**: Mandatory for all blocks (if/while/for). Open brace on same line (except functions).
> +- **C Includes**: `#include "qemu/osdep.h"` MUST be the first include in every `.c` file.
> +- **C Comments**: Use `/* ... */` only. No `//` comments.
> +- **Naming**: `snake_case` for variables/functions; `CamelCase` for types/enums.
> +- **Memory**: Use GLib (`g_malloc`, `g_free`, `g_autofree`) or QEMU (`qemu_memalign`). No `malloc`.
> +- **Errors**: Use `error_report()` or `error_setg()`. Avoid `printf` for errors.
> +- **Lints**: Run `./scripts/checkpatch.pl` on C patches. Use `make clippy` for Rust.
> +
> +## Commit Style
> +- **Small Commits**: Favour small discreet commits changing one thing.
> +- **Maintain Bisectability**: Each commit must compile and pass basic tests.
> +- **Separate Refactoring**: Split code movement or style fixes from functional changes.
> +- **Commit Messages**: Use a concise subject line, followed by a body explaining "why" (not just "what").
> +- **Signed-off-by**: Every commit must have a `Signed-off-by` line.
> --
> 2.47.3
>
>
^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [RFC PATCH v2 01/10] AGENTS.md: add basic AGENTS.md for QEMU
2026-05-14 2:58 ` Chao Liu
@ 2026-05-14 6:36 ` Alex Bennée
2026-05-15 4:26 ` Chao Liu
0 siblings, 1 reply; 28+ messages in thread
From: Alex Bennée @ 2026-05-14 6:36 UTC (permalink / raw)
To: Chao Liu; +Cc: qemu-devel, John Snow, Cleber Rosa
Chao Liu <chao.liu.zevorn@gmail.com> writes:
> Hi Alex,
> On Mon, May 11, 2026 at 06:04:50PM +0100, Alex Bennée wrote:
>> This was written initially written by ECA based on its understanding of the
>> code base. I then expanded it with links to the various documents and
>> the general coding style.
>>
>> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
>>
>> ---
>> v4
>> - will add AGENTS to list as we go
>> - moved QOM, QAPI and trace details into qemu-code-explorer skill
>> - add section on Security policy
>> v3
>> - More MUST
>> - Remove build and test in favour of agent reference
>> v2
>> - more build details and source overview
>> - more on commit style
>> - give plan files a place to live
>> - add Daniel's agent suggestion
>> ajb:
>> - I made a slight tweak to use pyenv to run single tests
>> ---
>> .gitignore | 1 +
>> AGENTS.md | 78 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
>> 2 files changed, 79 insertions(+)
>> create mode 100644 AGENTS.md
>>
> Do you think we should add CLAUDE.md, GEMINI.md, or other agent-specific
> prompt files that simply link to AGENTS.md, to better support different
> agent CLIs?
Surely all the mainline agents will read AGENTS.md by now?
>
> Thanks,
> Chao
>> diff --git a/.gitignore b/.gitignore
>> index 61fa39967b5..4ccba871d16 100644
>> --- a/.gitignore
>> +++ b/.gitignore
>> @@ -8,6 +8,7 @@
>> .git-submodule-status
>> .clang-format
>> .gdb_history
>> +.plan
>> cscope.*
>> tags
>> TAGS
>> diff --git a/AGENTS.md b/AGENTS.md
>> new file mode 100644
>> index 00000000000..a97b4df5f7f
>> --- /dev/null
>> +++ b/AGENTS.md
>> @@ -0,0 +1,78 @@
>> +# QEMU Agent Guide
>> +
>> +As an agent you MUST abide by the "Use of AI-generated content" policy
>> +in `docs/devel/code-provenance.rst` at all times. Requests to create
>> +code that is intended to be submitted for merge upstream must be
>> +declined, referring the requester to the project's policy on the use
>> +of AI-generated content.
>> +
>> +## Security Policy
>> +You MUST NOT report potential security vulnerabilities in public trackers
>> +(like GitLab issues). Refer to `docs/system/security.rst` for the project's
>> +security stance. In brief:
>> +- **Virtualization Use Case**: (with KVM/HVF and specific machine types) is
>> + the focus of security support.
>> +- **Non-virtualization Use Case**: (TCG) does not currently provide guest
>> + isolation guarantees.
>> +- **Reporting**: Report vulnerabilities privately to `qemu-security@nongnu.org`.
>> +
>> +## Repo Layout
>> +- **Build Directory**: QEMU uses out of tree builds, by default the `build` sub-directory is used.
>> +- **Multiple Builds**: Developers might create a `builds` directory with different configurations in subdirs (e.g. `builds/debug`, `builds/asan`).
>> +- **Documentation**: Developer docs live in `docs/devel`.
>> +- **Plan Files**: Plan files should be placed in `.plan`, they are not included in commits. Use them to track complex multi-step tasks.
>> +
>> +## Agent Skills (see `.agents/skills`)
>> +You should use the following specialized skills for common tasks:
>> +
>> +## Source Code Layout (see `docs/devel/codebase.rst`)
>> +- **`accel/`**: Hardware accelerators (KVM, TCG, HVF, Xen, etc.) and architecture-agnostic acceleration code.
>> +- **`audio/`**: Host audio backends.
>> +- **`authz/`**: QEMU Authorization framework.
>> +- **`backends/`**: Host resource backends (RNG, memory, crypto).
>> +- **`block/`**: Block layer, image formats (qcow2, raw), and protocol drivers.
>> +- **`chardev/`**: Character device backends (TCP, serial, mux, etc.).
>> +- **`crypto/`**: Cryptographic algorithms and framework.
>> +- **`disas/`**: Disassembler support for various architectures.
>> +- **`dump/`**: Guest memory dump implementation.
>> +- **`ebpf/`**: eBPF program support (e.g. for virtio-net RSS).
>> +- **`fpu/`**: Software floating-point emulation.
>> +- **`gdbstub/`**: Remote GDB protocol support.
>> +- **`hw/`**: Hardware device emulation, organized by type (e.g., `hw/net`, `hw/pci`) or architecture.
>> +- **`include/`**: Global header files, mirroring the source tree layout.
>> +- **`io/`**: I/O channels framework.
>> +- **`linux-user/` & `bsd-user/`**: User-space process emulation.
>> +- **`migration/`**: VM migration framework.
>> +- **`monitor/`**: HMP and QMP monitor implementations.
>> +- **`nbd/`**: Network Block Device server and client code.
>> +- **`net/`**: Networking stack and host backends.
>> +- **`plugins/`**: TCG introspection plugins core.
>> +- **`qapi/`**: QAPI schema and code generation infrastructure.
>> +- **`qga/`**: QEMU Guest Agent.
>> +- **`qom/`**: QEMU Object Model implementation.
>> +- **`replay/`**: Deterministic record/replay support.
>> +- **`rust/`**: Rust integration and Rust-based device models.
>> +- **`scripts/`**: Build system helpers, `checkpatch.pl`, `tracetool`, etc.
>> +- **`system/`**: Core system-level emulation logic (replaces `softmmu`).
>> +- **`target/`**: CPU-specific emulation (ISA translation, CPU state).
>> +- **`tcg/`**: The Tiny Code Generator (JIT) backends.
>> +- **`tests/`**: Test suites (qtest, unit, functional, tcg).
>> +- **`ui/`**: User interface backends (GTK, SDL, VNC, Spice).
>> +- **`util/`**: Low-level utility functions and data structures.
>> +
>> +## Code Style (see `docs/devel/style.rst`)
>> +- **Formatting**: 4-space indents, NO tabs, 80-char line limit (max 100).
>> +- **C Braces**: Mandatory for all blocks (if/while/for). Open brace on same line (except functions).
>> +- **C Includes**: `#include "qemu/osdep.h"` MUST be the first include in every `.c` file.
>> +- **C Comments**: Use `/* ... */` only. No `//` comments.
>> +- **Naming**: `snake_case` for variables/functions; `CamelCase` for types/enums.
>> +- **Memory**: Use GLib (`g_malloc`, `g_free`, `g_autofree`) or QEMU (`qemu_memalign`). No `malloc`.
>> +- **Errors**: Use `error_report()` or `error_setg()`. Avoid `printf` for errors.
>> +- **Lints**: Run `./scripts/checkpatch.pl` on C patches. Use `make clippy` for Rust.
>> +
>> +## Commit Style
>> +- **Small Commits**: Favour small discreet commits changing one thing.
>> +- **Maintain Bisectability**: Each commit must compile and pass basic tests.
>> +- **Separate Refactoring**: Split code movement or style fixes from functional changes.
>> +- **Commit Messages**: Use a concise subject line, followed by a body explaining "why" (not just "what").
>> +- **Signed-off-by**: Every commit must have a `Signed-off-by` line.
>> --
>> 2.47.3
>>
>>
--
Alex Bennée
Virtualisation Tech Lead @ Linaro
^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [RFC PATCH v2 01/10] AGENTS.md: add basic AGENTS.md for QEMU
2026-05-14 6:36 ` Alex Bennée
@ 2026-05-15 4:26 ` Chao Liu
2026-05-15 7:55 ` Alex Bennée
0 siblings, 1 reply; 28+ messages in thread
From: Chao Liu @ 2026-05-15 4:26 UTC (permalink / raw)
To: Alex Bennée; +Cc: qemu-devel, John Snow, Cleber Rosa
On Thu, May 14, 2026 at 07:36:01AM +0100, Alex Bennée wrote:
> Chao Liu <chao.liu.zevorn@gmail.com> writes:
>
> > Hi Alex,
> > On Mon, May 11, 2026 at 06:04:50PM +0100, Alex Bennée wrote:
> >> This was written initially written by ECA based on its understanding of the
> >> code base. I then expanded it with links to the various documents and
> >> the general coding style.
> >>
> >> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> >>
> >> ---
> >> v4
> >> - will add AGENTS to list as we go
> >> - moved QOM, QAPI and trace details into qemu-code-explorer skill
> >> - add section on Security policy
> >> v3
> >> - More MUST
> >> - Remove build and test in favour of agent reference
> >> v2
> >> - more build details and source overview
> >> - more on commit style
> >> - give plan files a place to live
> >> - add Daniel's agent suggestion
> >> ajb:
> >> - I made a slight tweak to use pyenv to run single tests
> >> ---
> >> .gitignore | 1 +
> >> AGENTS.md | 78 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
> >> 2 files changed, 79 insertions(+)
> >> create mode 100644 AGENTS.md
> >>
> > Do you think we should add CLAUDE.md, GEMINI.md, or other agent-specific
> > prompt files that simply link to AGENTS.md, to better support different
> > agent CLIs?
>
> Surely all the mainline agents will read AGENTS.md by now?
>
That's true, but in terms of skill compatibility specifically, there are
still some subtle differences. I ran detailed tests on opencode, claude,
gemini, and codex, and here are the results:
| codex | claude | opencode | gemini
---------------------+----------+------------+-----------+----------
AGENTS.md | yes (1°) | yes (fb) | yes (1°) | no (1)
.agents/skills/ | yes | no (2) | yes | yes
SKILL.md | yes | yes | yes | yes
native dir | .codex/ | .claude/ | .opencode/| .gemini/
x-tool compat | none | none | .cl/.ag(3)| .agents/
auto-trigger | yes | yes | yes | yes
(1°) = primary, (fb) = fallback.
(1) Gemini CLI natively reads GEMINI.md, not AGENTS.md. Redirect via
.gemini/settings.json: { "context": { "fileName": ["AGENTS.md"] } }.
(2) Claude Code only scans .claude/skills/; .agents/skills/ silently
ignored. Workaround: symlink .claude/skills -> ../.agents/skills.
(3) OpenCode scans both .claude/skills/ and .agents/skills/ as compat
paths, in addition to its native .opencode/skills/.
The current impl maintains maximum compatibility. If we need to fill
the gaps, a good approach might be to add a script that registers
.agents/skills/ for agents with poorer compatibility.
Also, I'm still trying to test these skills with as many models as
possible. I'll report back once I have results. Thanks Alex for the
contribution.
Thanks,
Chao
^ permalink raw reply [flat|nested] 28+ messages in thread* Re: [RFC PATCH v2 01/10] AGENTS.md: add basic AGENTS.md for QEMU
2026-05-15 4:26 ` Chao Liu
@ 2026-05-15 7:55 ` Alex Bennée
0 siblings, 0 replies; 28+ messages in thread
From: Alex Bennée @ 2026-05-15 7:55 UTC (permalink / raw)
To: Chao Liu; +Cc: qemu-devel, John Snow, Cleber Rosa
Chao Liu <chao.liu.zevorn@gmail.com> writes:
> On Thu, May 14, 2026 at 07:36:01AM +0100, Alex Bennée wrote:
>> Chao Liu <chao.liu.zevorn@gmail.com> writes:
>>
>> > Hi Alex,
>> > On Mon, May 11, 2026 at 06:04:50PM +0100, Alex Bennée wrote:
>> >> This was written initially written by ECA based on its understanding of the
>> >> code base. I then expanded it with links to the various documents and
>> >> the general coding style.
>> >>
>> >> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
>> >>
>> >> ---
>> >> v4
>> >> - will add AGENTS to list as we go
>> >> - moved QOM, QAPI and trace details into qemu-code-explorer skill
>> >> - add section on Security policy
>> >> v3
>> >> - More MUST
>> >> - Remove build and test in favour of agent reference
>> >> v2
>> >> - more build details and source overview
>> >> - more on commit style
>> >> - give plan files a place to live
>> >> - add Daniel's agent suggestion
>> >> ajb:
>> >> - I made a slight tweak to use pyenv to run single tests
>> >> ---
>> >> .gitignore | 1 +
>> >> AGENTS.md | 78 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
>> >> 2 files changed, 79 insertions(+)
>> >> create mode 100644 AGENTS.md
>> >>
>> > Do you think we should add CLAUDE.md, GEMINI.md, or other agent-specific
>> > prompt files that simply link to AGENTS.md, to better support different
>> > agent CLIs?
>>
>> Surely all the mainline agents will read AGENTS.md by now?
>>
> That's true, but in terms of skill compatibility specifically, there are
> still some subtle differences. I ran detailed tests on opencode, claude,
> gemini, and codex, and here are the results:
>
> | codex | claude | opencode | gemini
> ---------------------+----------+------------+-----------+----------
> AGENTS.md | yes (1°) | yes (fb) | yes (1°) | no (1)
> .agents/skills/ | yes | no (2) | yes | yes
> SKILL.md | yes | yes | yes | yes
> native dir | .codex/ | .claude/ | .opencode/| .gemini/
> x-tool compat | none | none | .cl/.ag(3)| .agents/
> auto-trigger | yes | yes | yes | yes
>
> (1°) = primary, (fb) = fallback.
>
> (1) Gemini CLI natively reads GEMINI.md, not AGENTS.md. Redirect via
> .gemini/settings.json: { "context": { "fileName": ["AGENTS.md"] } }.
>
> (2) Claude Code only scans .claude/skills/; .agents/skills/ silently
> ignored. Workaround: symlink .claude/skills -> ../.agents/skills.
>
> (3) OpenCode scans both .claude/skills/ and .agents/skills/ as compat
> paths, in addition to its native .opencode/skills/.
>
> The current impl maintains maximum compatibility. If we need to fill
> the gaps, a good approach might be to add a script that registers
> .agents/skills/ for agents with poorer compatibility.
>
> Also, I'm still trying to test these skills with as many models as
> possible. I'll report back once I have results. Thanks Alex for the
> contribution.
Thanks for trying them all out. I don't think the model itself makes too
much difference (I've been using Gemini and Opus) but my agent framework
is ECA. I must admit I haven't tried any of the TUI agent apps.
I should post v3 later today with a split AGENTS.md (basic code-provenance
and security policy for merging, with the rest in a following patch).
>
> Thanks,
> Chao
--
Alex Bennée
Virtualisation Tech Lead @ Linaro
^ permalink raw reply [flat|nested] 28+ messages in thread
* [RFC PATCH v2 02/10] scripts/expand-macro.py: helper script exploding macros
2026-05-11 17:04 [RFC PATCH v2 00/10] AGENTS.md and associated skills Alex Bennée
2026-05-11 17:04 ` [RFC PATCH v2 01/10] AGENTS.md: add basic AGENTS.md for QEMU Alex Bennée
@ 2026-05-11 17:04 ` Alex Bennée
2026-05-11 17:31 ` Daniel P. Berrangé
2026-05-11 17:04 ` [RFC PATCH v2 03/10] .agents/skills: add qemu-code-explorer skill Alex Bennée
` (7 subsequent siblings)
9 siblings, 1 reply; 28+ messages in thread
From: Alex Bennée @ 2026-05-11 17:04 UTC (permalink / raw)
To: qemu-devel; +Cc: John Snow, Alex Bennée, Cleber Rosa
QEMU makes heavy use of C Macros which can be confusing to humans and
seems almost impossible for AI agents to follow. In the past I've
dealt with this by compiling with V=1 and manually copying and pasting
the gcc command line and appending -E to run the pre-processor step.
With the modern build system we now have a compile_commands.json so we
can automate the process with a script.
There is some trickiness involved in following the line markers so we
know where in the source file we are. To handle this we implement a
PreprocessorState object to track where in the include chain we are.
This allows us to show the including location when we dump the
expanded macro.
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
---
scripts/expand-macro.py | 272 ++++++++++++++++++++++++++++++++++++++++
1 file changed, 272 insertions(+)
create mode 100755 scripts/expand-macro.py
diff --git a/scripts/expand-macro.py b/scripts/expand-macro.py
new file mode 100755
index 00000000000..581f20b9897
--- /dev/null
+++ b/scripts/expand-macro.py
@@ -0,0 +1,272 @@
+#!/usr/bin/env python3
+#
+# Automate the expansion of QEMU macros based on compile_commands.json.
+#
+# This script runs the C preprocessor over a file to expand macros
+# in a specified line range, using the compilation flags defined in
+# compile_commands.json.
+#
+# Copyright (c) Linaro 2026
+#
+import os
+import sys
+import json
+import shlex
+import subprocess
+import argparse
+import re
+
+
+def find_compile_command(target_file, compile_commands):
+ """
+ Search compile_commands to find the rule to build target_file
+ """
+ target_abs = os.path.abspath(target_file)
+ for entry in compile_commands:
+ dir_path = entry.get('directory', '.')
+ file_abs = os.path.abspath(os.path.join(dir_path, entry['file']))
+ if file_abs == target_abs:
+ return entry
+ return None
+
+
+def process_command(command_entry):
+ """
+ Strip out output related options and return a command line that will
+ run the pre-processor only.
+ """
+ command = command_entry.get('command')
+ if not command:
+ args = command_entry.get('arguments', [])
+ else:
+ args = shlex.split(command)
+
+ if not args:
+ return None
+
+ out = []
+ it = iter(args)
+ for arg in it:
+ # the -M* options all deal with generating deps
+ if arg in ('-o', '-MF', '-MQ', '-MT', '-MD', '-MP'):
+ next(it, None) # Skip the option's argument
+ continue
+ if arg == '-c':
+ continue
+ out.append(arg)
+
+ # Enable pre-processor output, don't strip comments, trace includes
+ out.extend(['-E', '-CC', '-H'])
+ return out
+
+
+def normalize_path(raw_path, working_dir):
+ """Normalize and make paths absolute."""
+ if not os.path.isabs(raw_path):
+ return os.path.abspath(os.path.join(working_dir, raw_path))
+ return os.path.normpath(raw_path)
+
+
+class PreprocessorState:
+ """Tracks the state of the preprocessor as we parse its output."""
+ def __init__(self):
+ self.stack = []
+ self.current_path = None
+ self.current_line = 0
+ self.current_instance_id = 0
+ self.next_instance_id = 1
+ self.sections = {}
+
+ def update_on_marker(self, new_line, flags, path):
+ """Update the file stack and instance tracking based on markers."""
+ # entering new file
+ if "1" in flags:
+ if self.current_path is not None:
+ self.stack.append((self.current_path, self.current_line,
+ self.current_instance_id))
+ self.current_path = path
+ self.current_line = new_line
+ self.current_instance_id = self.next_instance_id
+ self.next_instance_id += 1
+ return
+
+ # leaving file
+ if "2" in flags:
+ if self.stack:
+ _, _, popped_instance_id = self.stack.pop()
+ self.current_path = path
+ self.current_line = new_line
+ self.current_instance_id = popped_instance_id
+ else:
+ self.current_path = path
+ self.current_line = new_line
+ self.current_instance_id = self.next_instance_id
+ self.next_instance_id += 1
+ return
+
+ # return to previous file without explicit flag 2
+ if self.current_path != path:
+ if self.stack and self.stack[-1][0] == path:
+ _, _, popped_instance_id = self.stack.pop()
+ self.current_path = path
+ self.current_line = new_line
+ self.current_instance_id = popped_instance_id
+ else:
+ self.current_path = path
+ self.current_line = new_line
+ self.current_instance_id = self.next_instance_id
+ self.next_instance_id += 1
+ return
+
+ self.current_line = new_line
+
+ def get_context_string(self, target_abs, working_dir):
+ """Generate a descriptive string showing the inclusion context."""
+ if self.stack:
+ ctx_path, ctx_line, _ = self.stack[-1]
+ try:
+ rel_ctx = os.path.relpath(ctx_path, working_dir)
+ except ValueError:
+ rel_ctx = ctx_path
+ return f"{rel_ctx}:{ctx_line}"
+
+ try:
+ rel_ctx = os.path.relpath(target_abs, working_dir)
+ except ValueError:
+ rel_ctx = target_abs
+ return f"{rel_ctx} (main file)"
+
+ def add_line(self, line, line_range, target_abs, working_dir):
+ """Add a line to the sections if it is within the requested range."""
+ start_line, end_line = line_range
+ if self.current_path == target_abs:
+ if start_line <= self.current_line <= end_line:
+ if self.current_instance_id not in self.sections:
+ ctx_str = self.get_context_string(target_abs, working_dir)
+ self.sections[self.current_instance_id] = {
+ "context": ctx_str,
+ "lines": []
+ }
+ self.sections[self.current_instance_id]["lines"].append(line)
+ self.current_line += 1
+
+
+def format_output_sections(sections, target_file, start_line, end_line):
+ """Format the accumulated sections into the final output string."""
+ output_sections = []
+ for _instance_id, data in sections.items():
+ if not data["lines"]:
+ continue
+ header = f"/* Expansion from {data['context']} */"
+ body = "\n".join(data["lines"])
+ output_sections.append(f"{header}\n{body}")
+
+ if not output_sections:
+ return (f"/* Error: No lines found for {target_file} "
+ f"in range {start_line}-{end_line} */")
+
+ return "\n/* end of expansion */\n".join(output_sections)
+
+
+def extract_range(stdout, target_file, start_line, end_line, working_dir):
+ """
+ Parse the output of the pre-processor while tracking where we
+ are in the source code from the markers so we can extract the
+ range asked for.
+ """
+ state = PreprocessorState()
+ target_abs = os.path.abspath(target_file)
+ line_range = (start_line, end_line)
+
+ # The format is undocumented but see:
+ #
+ # gcc/c-family/c-ppoutput.c:print_line_1
+ #
+ # where 1 = entering file, 2 = leaving file
+ # and the 3 or 3 4 depends on linemap_location_in_system_header_p
+ line_marker_re = re.compile(r'^# (\d+) "(.*?)"(.*)')
+
+ for line in stdout.splitlines():
+ match = line_marker_re.match(line)
+ if match:
+ new_line = int(match.group(1))
+ raw_path = match.group(2)
+ flags = match.group(3).split()
+
+ path = normalize_path(raw_path, working_dir)
+ state.update_on_marker(new_line, flags, path)
+ continue
+
+ state.add_line(line, line_range, target_abs, working_dir)
+
+ return format_output_sections(state.sections, target_file,
+ start_line, end_line)
+
+
+def main():
+ """Main entry point for the script."""
+ desc = 'Expand macros in a section of a file using compile_commands.json'
+ parser = argparse.ArgumentParser(description=desc)
+ parser.add_argument('file', help='Source file to expand macros in')
+ parser.add_argument('--range', help='Line range (e.g. 100-120)')
+
+ ctx_help = ('Context file (.c) to get compilation flags from '
+ '(useful for headers)')
+ parser.add_argument('--context', help=ctx_help)
+ parser.add_argument('--compile-commands', default='compile_commands.json',
+ help='Path to compile_commands.json')
+ parser.add_argument('--show-command', action='store_true',
+ help='Print the modified compile command and exit')
+
+ args = parser.parse_args()
+
+ if not os.path.exists(args.compile_commands):
+ print(f"Error: {args.compile_commands} not found.", file=sys.stderr)
+ sys.exit(1)
+
+ with open(args.compile_commands, encoding="utf-8") as f:
+ compile_commands = json.load(f)
+
+ query_file = args.context if args.context else args.file
+ entry = find_compile_command(query_file, compile_commands)
+
+ if not entry:
+ print(f"Error: Could not find compile command for {query_file}",
+ file=sys.stderr)
+ sys.exit(1)
+
+ cmdline = process_command(entry)
+ if not cmdline:
+ print(f"Error: Failed to process command for {query_file}",
+ file=sys.stderr)
+ sys.exit(1)
+
+ if args.show_command:
+ print(shlex.join(cmdline))
+ sys.exit(0)
+
+ working_dir = entry.get('directory', '.')
+ result = subprocess.run(cmdline, stdout=subprocess.PIPE,
+ stderr=subprocess.PIPE, cwd=working_dir,
+ universal_newlines=True, check=False)
+
+ if result.returncode != 0:
+ print(f"Preprocessor failed:\n{result.stderr}", file=sys.stderr)
+ sys.exit(result.returncode)
+
+ content = result.stdout
+ if args.range:
+ try:
+ start, end = map(int, args.range.split('-'))
+ content = extract_range(content, args.file, start, end,
+ working_dir)
+ except ValueError:
+ print(f"Error: Invalid range format {args.range}. Use start-end.",
+ file=sys.stderr)
+ sys.exit(1)
+
+ print(content)
+
+
+if __name__ == "__main__":
+ main()
--
2.47.3
^ permalink raw reply related [flat|nested] 28+ messages in thread* Re: [RFC PATCH v2 02/10] scripts/expand-macro.py: helper script exploding macros
2026-05-11 17:04 ` [RFC PATCH v2 02/10] scripts/expand-macro.py: helper script exploding macros Alex Bennée
@ 2026-05-11 17:31 ` Daniel P. Berrangé
0 siblings, 0 replies; 28+ messages in thread
From: Daniel P. Berrangé @ 2026-05-11 17:31 UTC (permalink / raw)
To: Alex Bennée; +Cc: qemu-devel, John Snow, Cleber Rosa
On Mon, May 11, 2026 at 06:04:51PM +0100, Alex Bennée wrote:
> QEMU makes heavy use of C Macros which can be confusing to humans and
> seems almost impossible for AI agents to follow. In the past I've
> dealt with this by compiling with V=1 and manually copying and pasting
> the gcc command line and appending -E to run the pre-processor step.
>
> With the modern build system we now have a compile_commands.json so we
> can automate the process with a script.
>
> There is some trickiness involved in following the line markers so we
> know where in the source file we are. To handle this we implement a
> PreprocessorState object to track where in the include chain we are.
> This allows us to show the including location when we dump the
> expanded macro.
>
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> ---
> scripts/expand-macro.py | 272 ++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 272 insertions(+)
> create mode 100755 scripts/expand-macro.py
>
> diff --git a/scripts/expand-macro.py b/scripts/expand-macro.py
> new file mode 100755
> index 00000000000..581f20b9897
> --- /dev/null
> +++ b/scripts/expand-macro.py
> @@ -0,0 +1,272 @@
> +#!/usr/bin/env python3
> +#
> +# Automate the expansion of QEMU macros based on compile_commands.json.
> +#
> +# This script runs the C preprocessor over a file to expand macros
> +# in a specified line range, using the compilation flags defined in
> +# compile_commands.json.
> +#
> +# Copyright (c) Linaro 2026
SPDX-License-Identifier needed
With regards,
Daniel
--
|: https://berrange.com ~~ https://hachyderm.io/@berrange :|
|: https://libvirt.org ~~ https://entangle-photo.org :|
|: https://pixelfed.art/berrange ~~ https://fstop138.berrange.com :|
^ permalink raw reply [flat|nested] 28+ messages in thread
* [RFC PATCH v2 03/10] .agents/skills: add qemu-code-explorer skill
2026-05-11 17:04 [RFC PATCH v2 00/10] AGENTS.md and associated skills Alex Bennée
2026-05-11 17:04 ` [RFC PATCH v2 01/10] AGENTS.md: add basic AGENTS.md for QEMU Alex Bennée
2026-05-11 17:04 ` [RFC PATCH v2 02/10] scripts/expand-macro.py: helper script exploding macros Alex Bennée
@ 2026-05-11 17:04 ` Alex Bennée
2026-05-11 17:32 ` Daniel P. Berrangé
2026-05-11 17:04 ` [RFC PATCH v2 04/10] .agents/skills: add qemu-build skill Alex Bennée
` (6 subsequent siblings)
9 siblings, 1 reply; 28+ messages in thread
From: Alex Bennée @ 2026-05-11 17:04 UTC (permalink / raw)
To: qemu-devel; +Cc: John Snow, Alex Bennée, Cleber Rosa
This provides a skill detailing how to explore the QEMU code base. It
guides the agents to use the tags and git-grep by default and outlines
some of the confusions that can occur with multiple build directories.
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
---
v2
- remove personal gtag skill references, add global stanzas directly
- moved macro information from AGENTS.md into code explorer
- more imperative language to trigger its use
- add section on using scripts/expand_macro.py
- remove eca reference from evals.json (maybe we should just drop this)
---
.agents/skills/qemu-code-explorer/SKILL.md | 119 ++++++++++++++++++
.../qemu-code-explorer/evals/evals.json | 26 ++++
AGENTS.md | 1 +
3 files changed, 146 insertions(+)
create mode 100644 .agents/skills/qemu-code-explorer/SKILL.md
create mode 100644 .agents/skills/qemu-code-explorer/evals/evals.json
diff --git a/.agents/skills/qemu-code-explorer/SKILL.md b/.agents/skills/qemu-code-explorer/SKILL.md
new file mode 100644
index 00000000000..d5b7d6a35cd
--- /dev/null
+++ b/.agents/skills/qemu-code-explorer/SKILL.md
@@ -0,0 +1,119 @@
+---
+name: qemu-code-explorer
+description: Systematic framework for deep-diving into the QEMU codebase. Use this to find precise symbol definitions (functions, structs, globals), locate all call sites or references, explore subsystem architectures, or search generated code in build directories. You MUST use this skill when exploring code flow and dependencies.
+license: GPL-2.0-or-later
+---
+
+# QEMU Code Base Explorer
+
+This skill provides a systematic approach to navigating and understanding the large and complex QEMU codebase.
+
+## 1. Symbol Search with Tags (Primary)
+
+Tagging systems are the fastest and most accurate way to find global symbol definitions and references. QEMU supports `gtags`, `ctags`, `cscope`, and `TAGS` (Emacs).
+
+### GNU Global (gtags) - Recommended
+- **Best for**: Finding where a function, struct, or global variable is defined or used.
+- **Commands**:
+ - Find definition with context: `global -dx SYMBOL`
+ - Find references with context: `global -rx SYMBOL`
+ - Find related symbols (completion): `global -c PREFIX`
+- **Note**: Using `-x` provides line numbers and the matching line's content, allowing for immediate analysis. This is significantly faster and more accurate than `grep` for symbols.
+
+### Updating Tags
+If you suspect the tags are out of date:
+```bash
+make gtags # or make ctags, make cscope, make TAGS
+```
+
+## 2. Text Search with `git grep` (Secondary)
+
+`git grep` is the preferred tool for general text searches within the source tree.
+
+- **Best for**:
+ - Searching for local variables within a function.
+ - Searching for string literals or comments.
+ - Finding occurrences of symbols defined in system headers (e.g., `optarg`).
+ - Complex regex patterns that `gtags` doesn't support.
+- **Why**: It is fast, respects `.gitignore`, and avoids searching through build artifacts or other non-source files.
+- **Usage**: `git grep "pattern"` or use a grep-like tool with the `path` set to the repository root.
+
+## 3. Searching Generated Code
+
+Generated source files (e.g., from QAPI, trace-events, decodetree) do not reside in the source tree but in the build directory.
+
+- **Best for**:
+ - Finding definitions of functions generated by QAPI (e.g., `qmp_marshal_...`).
+ - Finding trace points and their implementations (e.g., `trace_..._header`).
+ - Checking configuration fragments (`config-*.h`).
+- **Tools**: Use a normal `grep` (or similar search tool) limited to the build directory.
+- **Crucial Note**: QEMU developers often have multiple build directories (e.g., `build/`, `builds/debug/`, `builds/asan/`). Always verify which build directory is active or intended.
+- **Common Paths**:
+ - `build/qapi/`: Generated QAPI headers and C files.
+ - `build/config-host.h`: Host-specific configuration.
+
+### QOM (QEMU Object Model) (see `docs/devel/qom.rst` & `include/qom/object.h`)
+- Most devices are QOM objects.
+- Key concepts: `TypeInfo`, `ClassInit`, `InstanceInit`, `InstanceFinalize`.
+- `OBJECT_DECLARE_SIMPLE_TYPE` or `OBJECT_DECLARE_TYPE` expand to boilerplate.
+- Also creates casting macros like `MY_DEVICE(obj)`.
+
+### QAPI
+- Interface definitions live in `qapi/*.json`.
+- Generated code lives in `build/qapi/`.
+
+### Tracing
+- QEMU uses a tracing framework. Events are defined in `trace-events` files.
+ - `build/trace/`: Generated trace points.
+ - `trace_my_event_name(arg1, arg2);` calls the `my_event_name` trace point.
+
+### Decodetree (see `docs/devel/decodetree.rst`)
+- QEMU uses `decodetree.py` to generate instruction decoders.
+- A pattern like `- FOO ...` in a `.decode` file will:
+ 1. Generate code in the build tree (e.g. `decode-insns.c.inc`).
+ 2. Call a handwritten `trans_FOO(DisasContext *ctx, arg_FOO *a)` in the source tree.
+ 3. The `arg_FOO` structure is automatically filled with fields from the instruction.
+- Some instructions may use a common structure if defined with `&`.
+
+### Common QEMU Macros
+- **QOM**: `OBJECT_DECLARE_SIMPLE_TYPE(InstanceType, ClassType, MODULE_OBJ_NAME, MODULE_OBJ_TYPENAME)` expands to type declarations, casting macros (`MODULE_OBJ_NAME(obj)`), and more.
+- **TCG**: `HELPER(foo)` expands to helper function declarations or calls.
+- **Error**: `ERRP_GUARD()` ensures `errp` is not NULL for easy error propagation.
+- **Bitwise**: `BIT(n)`, `MAKE_64BIT_MASK(shift, len)` for clear bit manipulation.
+- **Structs**: `container_of(ptr, type, member)` to get parent struct pointer.
+- **Memory**: `g_autofree` and `g_autoptr(Type)` for automatic cleanup (GLib).
+- **Migration**: `VMSTATE_...` macros for defining device state save/load.
+
+## 4. Expanding Complex Macros
+
+QEMU makes heavy use of macros, which can sometimes be hard to follow by "hand". To understand exactly how a macro expands in a specific file and context, you should use the `scripts/expand-macro.py` tool.
+
+- **Best for**:
+ - Expanding complex macros to see their generated C code.
+ - Understanding how nested macros evaluate.
+- **Usage**:
+ ```bash
+ python3 ./scripts/expand-macro.py FILE --context CONTEXT_FILE --range START_LINE-END_LINE
+ ```
+- **Example**:
+ To see how `partsN_canonicalize` expands in `fpu/softfloat-parts.c.inc` when included from `fpu/softfloat.c` between lines 191 and 264:
+ ```bash
+ python3 ./scripts/expand-macro.py fpu/softfloat-parts.c.inc --context fpu/softfloat.c --range 191-264
+ ```
+
+## Decision Matrix: Which tool to use?
+
+| Goal | Tool | Reason |
+|------|------|--------|
+| Find a function definition | `gtags` | Precise and fast. |
+| Find all call sites of a function | `gtags` | Comprehensive. |
+| Find a local variable usage | `git grep` | `gtags` only tracks globals. |
+| Search for a string literal | `git grep` | `gtags` doesn't index literals. |
+| Find QAPI-generated code | `grep` in `build/` | Not in source tree. |
+| Search in a specific subsystem | `git grep <path>` | Efficiently scoped. |
+| Understand complex macro expansion | `scripts/expand-macro.py` | Shows exact generated C code. |
+
+## Workflow Tips
+1. **Scope your search**: If you know you are looking for a networking issue, search `hw/net/` or `net/` first.
+2. **Beware of Macros**: QEMU uses many macros (especially in QOM). If `gtags` fails, `git grep` might find where the macro is used to define the symbol.
+3. **Verify the Build**: Before searching generated code, ensure a build has been performed in the target directory.
diff --git a/.agents/skills/qemu-code-explorer/evals/evals.json b/.agents/skills/qemu-code-explorer/evals/evals.json
new file mode 100644
index 00000000000..8eaa45b28b3
--- /dev/null
+++ b/.agents/skills/qemu-code-explorer/evals/evals.json
@@ -0,0 +1,26 @@
+# SPDX-License-Identifier: GPL-2.0-or-later
+{
+ "skill_name": "qemu-code-explorer",
+ "evals": [
+ {
+ "id": 0,
+ "prompt": "Where is the function 'qemu_mutex_lock' defined and where is it used in the block layer (block/)?",
+ "expected_output": "The definition should be found (likely in util/qemu-thread-posix.c or similar) and usages in block/ should be listed using gtags."
+ },
+ {
+ "id": 1,
+ "prompt": "I'm seeing a reference to 'qmp_marshal_query_status' in some docs but I can't find it in the source tree. Can you find where it is defined?",
+ "expected_output": "The agent should identify this as QAPI generated code and look in the build directory (e.g., build/qapi/qapi-commands-control.c)."
+ },
+ {
+ "id": 2,
+ "prompt": "Find all implementations of trace points for 'virtio_net' in the generated code.",
+ "expected_output": "The agent should search for 'trace_virtio_net_*' in the build directory, specifically in generated trace headers/sources."
+ },
+ {
+ "id": 3,
+ "prompt": "Find all occurrences of the string 'Could not open' in the 'hw/' directory.",
+ "expected_output": "The agent should use git grep scoped to hw/ to find the string literals."
+ }
+ ]
+}
diff --git a/AGENTS.md b/AGENTS.md
index a97b4df5f7f..74516c378ed 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -24,6 +24,7 @@ security stance. In brief:
## Agent Skills (see `.agents/skills`)
You should use the following specialized skills for common tasks:
+- `qemu-code-explorer`: For finding where things are defined, how they're used, or understanding a specific subsystem.
## Source Code Layout (see `docs/devel/codebase.rst`)
- **`accel/`**: Hardware accelerators (KVM, TCG, HVF, Xen, etc.) and architecture-agnostic acceleration code.
--
2.47.3
^ permalink raw reply related [flat|nested] 28+ messages in thread* Re: [RFC PATCH v2 03/10] .agents/skills: add qemu-code-explorer skill
2026-05-11 17:04 ` [RFC PATCH v2 03/10] .agents/skills: add qemu-code-explorer skill Alex Bennée
@ 2026-05-11 17:32 ` Daniel P. Berrangé
2026-05-11 18:00 ` Alex Bennée
0 siblings, 1 reply; 28+ messages in thread
From: Daniel P. Berrangé @ 2026-05-11 17:32 UTC (permalink / raw)
To: Alex Bennée; +Cc: qemu-devel, John Snow, Cleber Rosa
On Mon, May 11, 2026 at 06:04:52PM +0100, Alex Bennée wrote:
> This provides a skill detailing how to explore the QEMU code base. It
> guides the agents to use the tags and git-grep by default and outlines
> some of the confusions that can occur with multiple build directories.
>
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
>
> ---
> v2
> - remove personal gtag skill references, add global stanzas directly
> - moved macro information from AGENTS.md into code explorer
> - more imperative language to trigger its use
> - add section on using scripts/expand_macro.py
> - remove eca reference from evals.json (maybe we should just drop this)
> ---
> .agents/skills/qemu-code-explorer/SKILL.md | 119 ++++++++++++++++++
> .../qemu-code-explorer/evals/evals.json | 26 ++++
> AGENTS.md | 1 +
> 3 files changed, 146 insertions(+)
> create mode 100644 .agents/skills/qemu-code-explorer/SKILL.md
> create mode 100644 .agents/skills/qemu-code-explorer/evals/evals.json
>
> diff --git a/.agents/skills/qemu-code-explorer/SKILL.md b/.agents/skills/qemu-code-explorer/SKILL.md
> new file mode 100644
> index 00000000000..d5b7d6a35cd
> --- /dev/null
> +++ b/.agents/skills/qemu-code-explorer/SKILL.md
> @@ -0,0 +1,119 @@
> +---
> +name: qemu-code-explorer
> +description: Systematic framework for deep-diving into the QEMU codebase. Use this to find precise symbol definitions (functions, structs, globals), locate all call sites or references, explore subsystem architectures, or search generated code in build directories. You MUST use this skill when exploring code flow and dependencies.
> +license: GPL-2.0-or-later
Is "license:" a mandatory tag from a schema we're following here,
or can be used "SPDX-License-Identifier:" instead ?
With regards,
Daniel
--
|: https://berrange.com ~~ https://hachyderm.io/@berrange :|
|: https://libvirt.org ~~ https://entangle-photo.org :|
|: https://pixelfed.art/berrange ~~ https://fstop138.berrange.com :|
^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [RFC PATCH v2 03/10] .agents/skills: add qemu-code-explorer skill
2026-05-11 17:32 ` Daniel P. Berrangé
@ 2026-05-11 18:00 ` Alex Bennée
0 siblings, 0 replies; 28+ messages in thread
From: Alex Bennée @ 2026-05-11 18:00 UTC (permalink / raw)
To: Daniel P. Berrangé; +Cc: qemu-devel, John Snow, Cleber Rosa
Daniel P. Berrangé <berrange@redhat.com> writes:
> On Mon, May 11, 2026 at 06:04:52PM +0100, Alex Bennée wrote:
>> This provides a skill detailing how to explore the QEMU code base. It
>> guides the agents to use the tags and git-grep by default and outlines
>> some of the confusions that can occur with multiple build directories.
>>
>> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
>>
>> ---
>> v2
>> - remove personal gtag skill references, add global stanzas directly
>> - moved macro information from AGENTS.md into code explorer
>> - more imperative language to trigger its use
>> - add section on using scripts/expand_macro.py
>> - remove eca reference from evals.json (maybe we should just drop this)
>> ---
>> .agents/skills/qemu-code-explorer/SKILL.md | 119 ++++++++++++++++++
>> .../qemu-code-explorer/evals/evals.json | 26 ++++
>> AGENTS.md | 1 +
>> 3 files changed, 146 insertions(+)
>> create mode 100644 .agents/skills/qemu-code-explorer/SKILL.md
>> create mode 100644 .agents/skills/qemu-code-explorer/evals/evals.json
>>
>> diff --git a/.agents/skills/qemu-code-explorer/SKILL.md b/.agents/skills/qemu-code-explorer/SKILL.md
>> new file mode 100644
>> index 00000000000..d5b7d6a35cd
>> --- /dev/null
>> +++ b/.agents/skills/qemu-code-explorer/SKILL.md
>> @@ -0,0 +1,119 @@
>> +---
>> +name: qemu-code-explorer
>> +description: Systematic framework for deep-diving into the QEMU codebase. Use this to find precise symbol definitions (functions, structs, globals), locate all call sites or references, explore subsystem architectures, or search generated code in build directories. You MUST use this skill when exploring code flow and dependencies.
>> +license: GPL-2.0-or-later
>
> Is "license:" a mandatory tag from a schema we're following here,
> or can be used "SPDX-License-Identifier:" instead ?
It's from the spec: https://agentskills.io/specification#frontmatter
>
>
> With regards,
> Daniel
--
Alex Bennée
Virtualisation Tech Lead @ Linaro
^ permalink raw reply [flat|nested] 28+ messages in thread
* [RFC PATCH v2 04/10] .agents/skills: add qemu-build skill
2026-05-11 17:04 [RFC PATCH v2 00/10] AGENTS.md and associated skills Alex Bennée
` (2 preceding siblings ...)
2026-05-11 17:04 ` [RFC PATCH v2 03/10] .agents/skills: add qemu-code-explorer skill Alex Bennée
@ 2026-05-11 17:04 ` Alex Bennée
2026-05-12 14:40 ` Chao Liu
2026-05-11 17:04 ` [RFC PATCH v2 05/10] .agents/skills: add qemu-testing skill Alex Bennée
` (5 subsequent siblings)
9 siblings, 1 reply; 28+ messages in thread
From: Alex Bennée @ 2026-05-11 17:04 UTC (permalink / raw)
To: qemu-devel; +Cc: John Snow, Alex Bennée, Cleber Rosa
This provides basic instructions for building QEMU.
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
---
v2
- drop ECA/qemu-helper-agent sub-agent language
- mention configure --help
- drop mention of full paths - not needed for compilation
- moved earlier is series so code-reviewer can refer to it
---
.agents/skills/qemu-build/SKILL.md | 50 ++++++++++++++++++++++++++++++
AGENTS.md | 1 +
2 files changed, 51 insertions(+)
create mode 100644 .agents/skills/qemu-build/SKILL.md
diff --git a/.agents/skills/qemu-build/SKILL.md b/.agents/skills/qemu-build/SKILL.md
new file mode 100644
index 00000000000..91819a0992a
--- /dev/null
+++ b/.agents/skills/qemu-build/SKILL.md
@@ -0,0 +1,50 @@
+---
+name: qemu-build
+description: Provides step-by-step instructions on configuring and building QEMU. You MUST trigger this skill whenever the user asks to build QEMU or debug build failures. It includes critical details on build directory reuse and spawning sub-agents.
+license: GPL-2.0-or-later
+---
+
+# Instructions
+
+## Examining and Re-using Build Directories
+Before creating a new build directory, check if an existing one can be re-used. QEMU uses out-of-tree builds, typically in `build` or `builds/` sub-directories.
+
+1. **Check existing configs**: You can examine how an existing build directory was configured by checking its `config.log`. Run `head -n 2 builds/<dir>/config.log`. The second line typically contains the full `../configure` command line used.
+2. **Re-use and Reconfigure**: You have latitude to re-use existing directories when appropriate (e.g., `builds/debug` which is a general-purpose debug directory for whatever is currently going on). If an existing directory has the right flags (like debug/sanitizers) but the wrong target list, you can reconfigure it to keep the same config but change the `--target-list`:
+ ```bash
+ cd builds/debug
+ # Check the old config.log, then re-run configure with the new target-list
+ ../../configure <old-flags> --target-list=<new-targets>
+ ```
+
+## Launching Builds
+**Crucial**: You MUST NEVER run builds directly in the main agent context. You MUST ALWAYS launch them by spawning a sub-agent.
+Pass the specific build commands, along with the required working directory, in the `task` argument. Give the subagent explicit instructions on what to verify and what to report back to you.
+For example: `task: "Navigate to builds/debug and run ninja. If it fails, report the exact compiler errors."`
+
+## Configuring a New Build
+If no suitable build directory exists, create a new one.
+
+1. **Create build directory**: `mkdir -p builds/test-target; cd builds/test-target`
+2. **Basic Configure**: `../../configure --target-list=[list of targets]`
+ - Common targets: `x86_64-softmmu`, `aarch64-softmmu`, `riscv64-softmmu`, `x86_64-linux-user`.
+3. **Common Options**:
+ - `--enable-debug-info`: Include symbols.
+ - `--enable-debug`: Enable assertions.
+4. **Sanitizers**:
+ - `--enable-asan`: Address Sanitizer.
+ - `--enable-tsan`: Thread Sanitizer.
+ - `--enable-ubsan`: Undefined Behavior Sanitizer.
+5. **Help**:
+ - `--help`: will give a comprehensive list of options
+
+## Building
+**Important**: Always re-run the build after making changes to the source code.
+
+## Reporting Results
+**Crucial**: After completing the build task, provide a concise summary of the results to the user.
+1. **Summary**: State whether the build passed or failed.
+2. **Failure Excerpts**: If the build fails, include relevant excerpts from the logs (e.g., compiler errors).
+
+## Debugging and Environment
+- **Verbose**: `V=1` for detailed output.
diff --git a/AGENTS.md b/AGENTS.md
index 74516c378ed..08bfe13ebd2 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -25,6 +25,7 @@ security stance. In brief:
## Agent Skills (see `.agents/skills`)
You should use the following specialized skills for common tasks:
- `qemu-code-explorer`: For finding where things are defined, how they're used, or understanding a specific subsystem.
+- `qemu-build`: For configuring and building QEMU (including debug and sanitizer builds).
## Source Code Layout (see `docs/devel/codebase.rst`)
- **`accel/`**: Hardware accelerators (KVM, TCG, HVF, Xen, etc.) and architecture-agnostic acceleration code.
--
2.47.3
^ permalink raw reply related [flat|nested] 28+ messages in thread* Re: [RFC PATCH v2 04/10] .agents/skills: add qemu-build skill
2026-05-11 17:04 ` [RFC PATCH v2 04/10] .agents/skills: add qemu-build skill Alex Bennée
@ 2026-05-12 14:40 ` Chao Liu
0 siblings, 0 replies; 28+ messages in thread
From: Chao Liu @ 2026-05-12 14:40 UTC (permalink / raw)
To: Alex Bennée; +Cc: qemu-devel, John Snow, Cleber Rosa
On Mon, May 11, 2026 at 06:04:53PM +0100, Alex Bennée wrote:
> This provides basic instructions for building QEMU.
>
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
>
> ---
> v2
> - drop ECA/qemu-helper-agent sub-agent language
> - mention configure --help
> - drop mention of full paths - not needed for compilation
> - moved earlier is series so code-reviewer can refer to it
> ---
> .agents/skills/qemu-build/SKILL.md | 50 ++++++++++++++++++++++++++++++
> AGENTS.md | 1 +
> 2 files changed, 51 insertions(+)
> create mode 100644 .agents/skills/qemu-build/SKILL.md
>
> diff --git a/.agents/skills/qemu-build/SKILL.md b/.agents/skills/qemu-build/SKILL.md
> new file mode 100644
> index 00000000000..91819a0992a
> --- /dev/null
> +++ b/.agents/skills/qemu-build/SKILL.md
> @@ -0,0 +1,50 @@
> +---
> +name: qemu-build
> +description: Provides step-by-step instructions on configuring and building QEMU. You MUST trigger this skill whenever the user asks to build QEMU or debug build failures. It includes critical details on build directory reuse and spawning sub-agents.
> +license: GPL-2.0-or-later
> +---
> +
> +# Instructions
> +
> +## Examining and Re-using Build Directories
> +Before creating a new build directory, check if an existing one can be re-used. QEMU uses out-of-tree builds, typically in `build` or `builds/` sub-directories.
> +
> +1. **Check existing configs**: You can examine how an existing build directory was configured by checking its `config.log`. Run `head -n 2 builds/<dir>/config.log`. The second line typically contains the full `../configure` command line used.
> +2. **Re-use and Reconfigure**: You have latitude to re-use existing directories when appropriate (e.g., `builds/debug` which is a general-purpose debug directory for whatever is currently going on). If an existing directory has the right flags (like debug/sanitizers) but the wrong target list, you can reconfigure it to keep the same config but change the `--target-list`:
> + ```bash
> + cd builds/debug
> + # Check the old config.log, then re-run configure with the new target-list
> + ../../configure <old-flags> --target-list=<new-targets>
> + ```
> +
I tested it, and it works okay. Maybe we should add builds/ to .gitignore to
avoid accidentally committing multiple build cache files.
Tested-by: Chao Liu <chao.liu.zevorn@gmail.com>
Thanks,
Chao
> +## Launching Builds
> +**Crucial**: You MUST NEVER run builds directly in the main agent context. You MUST ALWAYS launch them by spawning a sub-agent.
> +Pass the specific build commands, along with the required working directory, in the `task` argument. Give the subagent explicit instructions on what to verify and what to report back to you.
> +For example: `task: "Navigate to builds/debug and run ninja. If it fails, report the exact compiler errors."`
> +
> +## Configuring a New Build
> +If no suitable build directory exists, create a new one.
> +
> +1. **Create build directory**: `mkdir -p builds/test-target; cd builds/test-target`
> +2. **Basic Configure**: `../../configure --target-list=[list of targets]`
> + - Common targets: `x86_64-softmmu`, `aarch64-softmmu`, `riscv64-softmmu`, `x86_64-linux-user`.
> +3. **Common Options**:
> + - `--enable-debug-info`: Include symbols.
> + - `--enable-debug`: Enable assertions.
> +4. **Sanitizers**:
> + - `--enable-asan`: Address Sanitizer.
> + - `--enable-tsan`: Thread Sanitizer.
> + - `--enable-ubsan`: Undefined Behavior Sanitizer.
> +5. **Help**:
> + - `--help`: will give a comprehensive list of options
> +
> +## Building
> +**Important**: Always re-run the build after making changes to the source code.
> +
> +## Reporting Results
> +**Crucial**: After completing the build task, provide a concise summary of the results to the user.
> +1. **Summary**: State whether the build passed or failed.
> +2. **Failure Excerpts**: If the build fails, include relevant excerpts from the logs (e.g., compiler errors).
> +
> +## Debugging and Environment
> +- **Verbose**: `V=1` for detailed output.
> diff --git a/AGENTS.md b/AGENTS.md
> index 74516c378ed..08bfe13ebd2 100644
> --- a/AGENTS.md
> +++ b/AGENTS.md
> @@ -25,6 +25,7 @@ security stance. In brief:
> ## Agent Skills (see `.agents/skills`)
> You should use the following specialized skills for common tasks:
> - `qemu-code-explorer`: For finding where things are defined, how they're used, or understanding a specific subsystem.
> +- `qemu-build`: For configuring and building QEMU (including debug and sanitizer builds).
>
> ## Source Code Layout (see `docs/devel/codebase.rst`)
> - **`accel/`**: Hardware accelerators (KVM, TCG, HVF, Xen, etc.) and architecture-agnostic acceleration code.
> --
> 2.47.3
>
>
^ permalink raw reply [flat|nested] 28+ messages in thread
* [RFC PATCH v2 05/10] .agents/skills: add qemu-testing skill
2026-05-11 17:04 [RFC PATCH v2 00/10] AGENTS.md and associated skills Alex Bennée
` (3 preceding siblings ...)
2026-05-11 17:04 ` [RFC PATCH v2 04/10] .agents/skills: add qemu-build skill Alex Bennée
@ 2026-05-11 17:04 ` Alex Bennée
2026-05-11 17:04 ` [RFC PATCH v2 06/10] .agents/skills: add qemu-code-reviewer skill Alex Bennée
` (4 subsequent siblings)
9 siblings, 0 replies; 28+ messages in thread
From: Alex Bennée @ 2026-05-11 17:04 UTC (permalink / raw)
To: qemu-devel; +Cc: John Snow, Alex Bennée, Cleber Rosa
This provides basic instructions for running tests but doesn't try to
exhaustively describe the whole setup.
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
---
v2
- add link to testing docs.
---
.agents/skills/qemu-testing/SKILL.md | 56 ++++++++++++++++++++++++++++
AGENTS.md | 1 +
2 files changed, 57 insertions(+)
create mode 100644 .agents/skills/qemu-testing/SKILL.md
diff --git a/.agents/skills/qemu-testing/SKILL.md b/.agents/skills/qemu-testing/SKILL.md
new file mode 100644
index 00000000000..e5979dfc1c5
--- /dev/null
+++ b/.agents/skills/qemu-testing/SKILL.md
@@ -0,0 +1,56 @@
+---
+name: qemu-testing
+description: Provides instructions on how to find, list, and run individual tests for QEMU (Unit, QTest, Functional, TCG). You MUST use this skill whenever the user asks about tests, wants to list available tests, or wants to run any test in a build directory, even for simple exploratory queries like "what tests can I run". It includes details about spawning sub-agents.
+license: GPL-2.0-or-later
+---
+
+# Instructions
+To run QEMU tests, you can use several different suites depending on what you are testing. **Note**: Ensure you have a recent build of QEMU before running tests. Use the `qemu-build` skill if you need to configure or run a build.
+
+For exhaustive details on the testing infrastructure, architectures, and specific test requirements, you MUST refer to the official documentation in:
+- `docs/devel/testing/` (specifically `main.rst`)
+
+## General Test Suites
+- **Unit Tests**: `make check-unit`
+- **QTest (Device emulation)**: `make check-qtest`
+- **Functional Tests (Python based)**: `make check-functional`
+- **TCG Tests (CPU instruction tests)**: `make check-tcg`
+
+## Launching Tests
+**Crucial**: You MUST NEVER run a test suites directly in the main agent context. You MUST ALWAYS launch them by spawning a sub-agent. Pass the specific build or test commands, along with the required build directory, in the `task` argument. Give the subagent explicit instructions on what to verify and what to report back to you.
+For example: `task: "Navigate to builds/debug and check what meson tests touch replay and report back."` or `task: "Run make check-tcg in builds/arm and summarize any failing tests."`
+
+### From the Build Directory
+Most individual tests from within a build directory. Most (unit, qtest, block, functional) can be individually selected and run via meson.
+
+As QEMU often needs a newer meson than the build host you should use the build `pyenv` to launch it:
+- **Example**: `./pyvenv/bin/meson test --suite thorough --list` to see what tests are in the thorough test suite
+
+## Running Individual Tests
+
+### Meson Test Runner (Unit, QTest, Functional, softfloat etc)
+To run a single test, you can use the meson test runner from within your pyvenv:
+`./pyvenv/bin/meson test [testname]`
+Example: `./pyvenv/bin/meson test qtest-x86_64/boot-serial-test`
+
+### TCG Tests
+To run individual TCG tests for a specific architecture:
+1. Navigate to the relevant build directory, e.g.: `cd tests/tcg/aarch64-softmmu`
+2. Run a specific test with make: `make run-[testname]`
+ Example: `make run-memory-sve`
+3. Use `make help` within the architecture directory to see the full list of available tests.
+
+### Functional Tests
+Individual functional tests can be run directly using the run script although from the source directory:
+- **Example**: `./builds/all/run tests/functional/aarch64/test_virt_vbsa.py`
+
+### Environment Variables
+- `V=1` for verbose output from tests.
+- `SPEED=slow` to run slower tests that are normally skipped.
+
+## Reporting Results
+**Crucial**: After completing the build and test tasks, provide a concise summary of the results to the calling agent.
+1. **Summary**: State whether the build and tests passed or failed.
+2. **Failure Excerpts**: If any task fails, include relevant excerpts from the logs (e.g., compiler errors, test failures).
+3. **Full Paths**: Always provide the **absolute file paths** to the full logs and result sets for further inspection.
+
diff --git a/AGENTS.md b/AGENTS.md
index 08bfe13ebd2..d9d1964d45a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -26,6 +26,7 @@ security stance. In brief:
You should use the following specialized skills for common tasks:
- `qemu-code-explorer`: For finding where things are defined, how they're used, or understanding a specific subsystem.
- `qemu-build`: For configuring and building QEMU (including debug and sanitizer builds).
+- `qemu-testing`: For finding, listing, and running individual tests (Unit, QTest, Functional, TCG).
## Source Code Layout (see `docs/devel/codebase.rst`)
- **`accel/`**: Hardware accelerators (KVM, TCG, HVF, Xen, etc.) and architecture-agnostic acceleration code.
--
2.47.3
^ permalink raw reply related [flat|nested] 28+ messages in thread* [RFC PATCH v2 06/10] .agents/skills: add qemu-code-reviewer skill
2026-05-11 17:04 [RFC PATCH v2 00/10] AGENTS.md and associated skills Alex Bennée
` (4 preceding siblings ...)
2026-05-11 17:04 ` [RFC PATCH v2 05/10] .agents/skills: add qemu-testing skill Alex Bennée
@ 2026-05-11 17:04 ` Alex Bennée
2026-05-12 3:21 ` Chao Liu
2026-05-11 17:04 ` [RFC PATCH v2 07/10] .agents/skills: add qemu-mail-thread skill Alex Bennée
` (3 subsequent siblings)
9 siblings, 1 reply; 28+ messages in thread
From: Alex Bennée @ 2026-05-11 17:04 UTC (permalink / raw)
To: qemu-devel; +Cc: John Snow, Alex Bennée, Cleber Rosa
This provides basic instructions for how to download and apply a
patch series from the mailing list.
Currently it is only taught about checkpatch but we could consider
adding common code smells and review comments that come up frequently.
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
---
v2
- merge checkpatch skill
- moved later in series to leverage build and test skills
- properly reference qemu-build and qemu-tester skills
- mention the qemu-code-explorer skill for navigation
---
.agents/skills/qemu-code-reviewer/SKILL.md | 93 ++++++++++++++++++++++
AGENTS.md | 1 +
2 files changed, 94 insertions(+)
create mode 100644 .agents/skills/qemu-code-reviewer/SKILL.md
diff --git a/.agents/skills/qemu-code-reviewer/SKILL.md b/.agents/skills/qemu-code-reviewer/SKILL.md
new file mode 100644
index 00000000000..48ec6b07520
--- /dev/null
+++ b/.agents/skills/qemu-code-reviewer/SKILL.md
@@ -0,0 +1,93 @@
+---
+name: qemu-code-reviewer
+description: Pull and apply patch series from mailing lists for review and testing in QEMU, including style and build validation.
+license: GPL-2.0-or-later
+---
+
+# QEMU Code Reviewer Skill
+
+This skill provides instructions on how to retrieve patch series submitted to the QEMU mailing list (`qemu-devel@nongnu.org`) using `b4` or manual methods.
+
+## Using b4 (Recommended)
+
+`b4` is the preferred tool for working with patch series from public-inbox instances like `lore.kernel.org`.
+
+### 1. Fetching a series
+To download a series and prepare it for `git am`:
+```bash
+b4 am <message-id-or-url>
+```
+This creates a `.mbx` file containing the entire series, properly ordered.
+
+### 2. Applying a series directly
+To apply a series directly to your current branch:
+```bash
+b4 shazam <message-id-or-url>
+```
+This is often the fastest way to get a series ready for testing.
+
+### 3. Creating a local branch for the series
+```bash
+b4 am -t <message-id-or-url>
+git am ./*.mbx
+```
+The `-t` flag (or `--trust-all`) can be useful if you know the source.
+
+## Manual mbox Retrieval (Alternative)
+
+If `b4` is unavailable, you can fetch the mbox manually from `lore.kernel.org`.
+
+### 1. Locate the thread
+Find the patch series on [lore.kernel.org/qemu-devel/](https://lore.kernel.org/qemu-devel/).
+
+### 2. Download the mbox
+Every thread on lore has an `mbox.gz` link. You can use `curl` or `wget`:
+```bash
+curl -L "https://lore.kernel.org/qemu-devel/<message-id>/raw" -o series.mbox
+```
+*Note: Appending `/raw` to the message URL usually provides the mbox format.*
+
+### 3. Apply with git am
+```bash
+git am series.mbox
+```
+
+## Post-Application Steps
+
+Once the patches are applied, you should perform initial validation:
+
+### 1. Style Check
+Run the QEMU checkpatch script to ensure the patches follow the project's coding style.
+
+- **Check applied patches**:
+ ```bash
+ ./scripts/checkpatch.pl master..HEAD
+ ```
+- **Check a specific commit**:
+ ```bash
+ ./scripts/checkpatch.pl <commit-hash>^..
+ ```
+- **Check a specific file**:
+ ```bash
+ ./scripts/checkpatch.pl -f <file-path>
+ ```
+- **Strict mode** (often required for new code or specific subsystems):
+ ```bash
+ ./scripts/checkpatch.pl --strict <commit-range>
+ ```
+
+### 2. Build and Test
+Refer to the `AGENTS.md` or the `qemu-build` and `qemu-testing` skills for build and test instructions.
+- Ensure you are in a clean build directory.
+- Run `ninja` or `make`.
+- Run relevant tests (e.g., `make check-qtest`).
+
+### 3. Reviewing Patches
+Refer to the `qemu-code-explorer` skill for navigating the code base and resolving functions and where they are called from.
+
+
+
+## Common Troubleshooting
+
+- **Applying fails**: If `git am` fails due to conflicts, you may need to use `git am --3way` or manually resolve conflicts.
+- **Missing dependencies**: Ensure your tree is up to date with the base branch the patches were intended for (usually `master`).
diff --git a/AGENTS.md b/AGENTS.md
index d9d1964d45a..fbbc3b65ed0 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -27,6 +27,7 @@ You should use the following specialized skills for common tasks:
- `qemu-code-explorer`: For finding where things are defined, how they're used, or understanding a specific subsystem.
- `qemu-build`: For configuring and building QEMU (including debug and sanitizer builds).
- `qemu-testing`: For finding, listing, and running individual tests (Unit, QTest, Functional, TCG).
+- `qemu-code-reviewer`: For pulling and applying patch series from mailing lists.
## Source Code Layout (see `docs/devel/codebase.rst`)
- **`accel/`**: Hardware accelerators (KVM, TCG, HVF, Xen, etc.) and architecture-agnostic acceleration code.
--
2.47.3
^ permalink raw reply related [flat|nested] 28+ messages in thread* Re: [RFC PATCH v2 06/10] .agents/skills: add qemu-code-reviewer skill
2026-05-11 17:04 ` [RFC PATCH v2 06/10] .agents/skills: add qemu-code-reviewer skill Alex Bennée
@ 2026-05-12 3:21 ` Chao Liu
2026-05-12 9:19 ` Alex Bennée
0 siblings, 1 reply; 28+ messages in thread
From: Chao Liu @ 2026-05-12 3:21 UTC (permalink / raw)
To: Alex Bennée; +Cc: qemu-devel, John Snow, Cleber Rosa
On Mon, May 11, 2026 at 06:04:55PM +0100, Alex Bennée wrote:
> This provides basic instructions for how to download and apply a
> patch series from the mailing list.
>
> Currently it is only taught about checkpatch but we could consider
> adding common code smells and review comments that come up frequently.
>
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
>
> ---
> v2
> - merge checkpatch skill
> - moved later in series to leverage build and test skills
> - properly reference qemu-build and qemu-tester skills
> - mention the qemu-code-explorer skill for navigation
> ---
> .agents/skills/qemu-code-reviewer/SKILL.md | 93 ++++++++++++++++++++++
> AGENTS.md | 1 +
> 2 files changed, 94 insertions(+)
> create mode 100644 .agents/skills/qemu-code-reviewer/SKILL.md
>
> diff --git a/.agents/skills/qemu-code-reviewer/SKILL.md b/.agents/skills/qemu-code-reviewer/SKILL.md
> new file mode 100644
> index 00000000000..48ec6b07520
> --- /dev/null
> +++ b/.agents/skills/qemu-code-reviewer/SKILL.md
> @@ -0,0 +1,93 @@
> +---
> +name: qemu-code-reviewer
> +description: Pull and apply patch series from mailing lists for review and testing in QEMU, including style and build validation.
> +license: GPL-2.0-or-later
> +---
> +
> +# QEMU Code Reviewer Skill
> +
> +This skill provides instructions on how to retrieve patch series submitted to the QEMU mailing list (`qemu-devel@nongnu.org`) using `b4` or manual methods.
> +
> +## Using b4 (Recommended)
> +
> +`b4` is the preferred tool for working with patch series from public-inbox instances like `lore.kernel.org`.
> +
> +### 1. Fetching a series
> +To download a series and prepare it for `git am`:
> +```bash
> +b4 am <message-id-or-url>
> +```
> +This creates a `.mbx` file containing the entire series, properly ordered.
> +
> +### 2. Applying a series directly
> +To apply a series directly to your current branch:
> +```bash
> +b4 shazam <message-id-or-url>
> +```
> +This is often the fastest way to get a series ready for testing.
> +
> +### 3. Creating a local branch for the series
> +```bash
> +b4 am -t <message-id-or-url>
> +git am ./*.mbx
> +```
> +The `-t` flag (or `--trust-all`) can be useful if you know the source.
I suggest using the git worktree command for workspace isolation before
applying patches.
> +
> +## Manual mbox Retrieval (Alternative)
> +
> +If `b4` is unavailable, you can fetch the mbox manually from `lore.kernel.org`.
> +
> +### 1. Locate the thread
> +Find the patch series on [lore.kernel.org/qemu-devel/](https://lore.kernel.org/qemu-devel/).
> +
> +### 2. Download the mbox
> +Every thread on lore has an `mbox.gz` link. You can use `curl` or `wget`:
> +```bash
> +curl -L "https://lore.kernel.org/qemu-devel/<message-id>/raw" -o series.mbox
> +```
> +*Note: Appending `/raw` to the message URL usually provides the mbox format.*
> +
> +### 3. Apply with git am
> +```bash
> +git am series.mbox
> +```
> +
> +## Post-Application Steps
> +
> +Once the patches are applied, you should perform initial validation:
> +
> +### 1. Style Check
> +Run the QEMU checkpatch script to ensure the patches follow the project's coding style.
> +
> +- **Check applied patches**:
> + ```bash
> + ./scripts/checkpatch.pl master..HEAD
> + ```
> +- **Check a specific commit**:
> + ```bash
> + ./scripts/checkpatch.pl <commit-hash>^..
> + ```
> +- **Check a specific file**:
> + ```bash
> + ./scripts/checkpatch.pl -f <file-path>
> + ```
> +- **Strict mode** (often required for new code or specific subsystems):
> + ```bash
> + ./scripts/checkpatch.pl --strict <commit-range>
> + ```
> +
> +### 2. Build and Test
> +Refer to the `AGENTS.md` or the `qemu-build` and `qemu-testing` skills for build and test instructions.
> +- Ensure you are in a clean build directory.
> +- Run `ninja` or `make`.
> +- Run relevant tests (e.g., `make check-qtest`).
> +
> +### 3. Reviewing Patches
> +Refer to the `qemu-code-explorer` skill for navigating the code base and resolving functions and where they are called from.
> +
If the patches have multiple versions, should we ask the agent to summarize
the review history of the previous versions, as well as briefly summarize
the discussion across the current patch thread? This can be easy to miss
during manual review, but an agent can handle it well.
However, this seems better suited as a new skill.
Thanks,
Chao
> +
> +
> +## Common Troubleshooting
> +
> +- **Applying fails**: If `git am` fails due to conflicts, you may need to use `git am --3way` or manually resolve conflicts.
> +- **Missing dependencies**: Ensure your tree is up to date with the base branch the patches were intended for (usually `master`).
> diff --git a/AGENTS.md b/AGENTS.md
> index d9d1964d45a..fbbc3b65ed0 100644
> --- a/AGENTS.md
> +++ b/AGENTS.md
> @@ -27,6 +27,7 @@ You should use the following specialized skills for common tasks:
> - `qemu-code-explorer`: For finding where things are defined, how they're used, or understanding a specific subsystem.
> - `qemu-build`: For configuring and building QEMU (including debug and sanitizer builds).
> - `qemu-testing`: For finding, listing, and running individual tests (Unit, QTest, Functional, TCG).
> +- `qemu-code-reviewer`: For pulling and applying patch series from mailing lists.
>
> ## Source Code Layout (see `docs/devel/codebase.rst`)
> - **`accel/`**: Hardware accelerators (KVM, TCG, HVF, Xen, etc.) and architecture-agnostic acceleration code.
> --
> 2.47.3
>
>
^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [RFC PATCH v2 06/10] .agents/skills: add qemu-code-reviewer skill
2026-05-12 3:21 ` Chao Liu
@ 2026-05-12 9:19 ` Alex Bennée
2026-05-12 14:43 ` Chao Liu
0 siblings, 1 reply; 28+ messages in thread
From: Alex Bennée @ 2026-05-12 9:19 UTC (permalink / raw)
To: Chao Liu; +Cc: qemu-devel, John Snow, Cleber Rosa
Chao Liu <chao.liu.zevorn@gmail.com> writes:
> On Mon, May 11, 2026 at 06:04:55PM +0100, Alex Bennée wrote:
>> This provides basic instructions for how to download and apply a
>> patch series from the mailing list.
>>
>> Currently it is only taught about checkpatch but we could consider
>> adding common code smells and review comments that come up frequently.
>>
>> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
>>
>> ---
>> v2
>> - merge checkpatch skill
>> - moved later in series to leverage build and test skills
>> - properly reference qemu-build and qemu-tester skills
>> - mention the qemu-code-explorer skill for navigation
>> ---
>> .agents/skills/qemu-code-reviewer/SKILL.md | 93 ++++++++++++++++++++++
>> AGENTS.md | 1 +
>> 2 files changed, 94 insertions(+)
>> create mode 100644 .agents/skills/qemu-code-reviewer/SKILL.md
>>
>> diff --git a/.agents/skills/qemu-code-reviewer/SKILL.md b/.agents/skills/qemu-code-reviewer/SKILL.md
>> new file mode 100644
>> index 00000000000..48ec6b07520
>> --- /dev/null
>> +++ b/.agents/skills/qemu-code-reviewer/SKILL.md
>> @@ -0,0 +1,93 @@
>> +---
>> +name: qemu-code-reviewer
>> +description: Pull and apply patch series from mailing lists for review and testing in QEMU, including style and build validation.
>> +license: GPL-2.0-or-later
>> +---
>> +
>> +# QEMU Code Reviewer Skill
>> +
>> +This skill provides instructions on how to retrieve patch series submitted to the QEMU mailing list (`qemu-devel@nongnu.org`) using `b4` or manual methods.
>> +
>> +## Using b4 (Recommended)
>> +
>> +`b4` is the preferred tool for working with patch series from public-inbox instances like `lore.kernel.org`.
>> +
>> +### 1. Fetching a series
>> +To download a series and prepare it for `git am`:
>> +```bash
>> +b4 am <message-id-or-url>
>> +```
>> +This creates a `.mbx` file containing the entire series, properly ordered.
>> +
>> +### 2. Applying a series directly
>> +To apply a series directly to your current branch:
>> +```bash
>> +b4 shazam <message-id-or-url>
>> +```
>> +This is often the fastest way to get a series ready for testing.
>> +
>> +### 3. Creating a local branch for the series
>> +```bash
>> +b4 am -t <message-id-or-url>
>> +git am ./*.mbx
>> +```
>> +The `-t` flag (or `--trust-all`) can be useful if you know the source.
> I suggest using the git worktree command for workspace isolation before
> applying patches.
I don't know if this gets too much into the weeds of per-developer
preference. Everyone has slightly different ways of working but they do
want confidence that when they hand the wheel to their agent it isn't go
to mess up their nice flow.
>
>> +
>> +## Manual mbox Retrieval (Alternative)
>> +
>> +If `b4` is unavailable, you can fetch the mbox manually from `lore.kernel.org`.
>> +
>> +### 1. Locate the thread
>> +Find the patch series on [lore.kernel.org/qemu-devel/](https://lore.kernel.org/qemu-devel/).
>> +
>> +### 2. Download the mbox
>> +Every thread on lore has an `mbox.gz` link. You can use `curl` or `wget`:
>> +```bash
>> +curl -L "https://lore.kernel.org/qemu-devel/<message-id>/raw" -o series.mbox
>> +```
>> +*Note: Appending `/raw` to the message URL usually provides the mbox format.*
>> +
>> +### 3. Apply with git am
>> +```bash
>> +git am series.mbox
>> +```
>> +
>> +## Post-Application Steps
>> +
>> +Once the patches are applied, you should perform initial validation:
>> +
>> +### 1. Style Check
>> +Run the QEMU checkpatch script to ensure the patches follow the project's coding style.
>> +
>> +- **Check applied patches**:
>> + ```bash
>> + ./scripts/checkpatch.pl master..HEAD
>> + ```
>> +- **Check a specific commit**:
>> + ```bash
>> + ./scripts/checkpatch.pl <commit-hash>^..
>> + ```
>> +- **Check a specific file**:
>> + ```bash
>> + ./scripts/checkpatch.pl -f <file-path>
>> + ```
>> +- **Strict mode** (often required for new code or specific subsystems):
>> + ```bash
>> + ./scripts/checkpatch.pl --strict <commit-range>
>> + ```
>> +
>> +### 2. Build and Test
>> +Refer to the `AGENTS.md` or the `qemu-build` and `qemu-testing` skills for build and test instructions.
>> +- Ensure you are in a clean build directory.
>> +- Run `ninja` or `make`.
>> +- Run relevant tests (e.g., `make check-qtest`).
>> +
>> +### 3. Reviewing Patches
>> +Refer to the `qemu-code-explorer` skill for navigating the code base and resolving functions and where they are called from.
>> +
> If the patches have multiple versions, should we ask the agent to summarize
> the review history of the previous versions, as well as briefly summarize
> the discussion across the current patch thread? This can be easy to miss
> during manual review, but an agent can handle it well.
That's a good idea. I've had good success in getting agents to review
threads and summarise what was asked for. I have even had them apply the
changes for me to review before committing.
>
> However, this seems better suited as a new skill.
The qemu-mail-thread skill is a general purpose thread handling skill we
could teach about versioning?
>
> Thanks,
> Chao
>> +
>> +
>> +## Common Troubleshooting
>> +
>> +- **Applying fails**: If `git am` fails due to conflicts, you may need to use `git am --3way` or manually resolve conflicts.
>> +- **Missing dependencies**: Ensure your tree is up to date with the base branch the patches were intended for (usually `master`).
>> diff --git a/AGENTS.md b/AGENTS.md
>> index d9d1964d45a..fbbc3b65ed0 100644
>> --- a/AGENTS.md
>> +++ b/AGENTS.md
>> @@ -27,6 +27,7 @@ You should use the following specialized skills for common tasks:
>> - `qemu-code-explorer`: For finding where things are defined, how they're used, or understanding a specific subsystem.
>> - `qemu-build`: For configuring and building QEMU (including debug and sanitizer builds).
>> - `qemu-testing`: For finding, listing, and running individual tests (Unit, QTest, Functional, TCG).
>> +- `qemu-code-reviewer`: For pulling and applying patch series from mailing lists.
>>
>> ## Source Code Layout (see `docs/devel/codebase.rst`)
>> - **`accel/`**: Hardware accelerators (KVM, TCG, HVF, Xen, etc.) and architecture-agnostic acceleration code.
>> --
>> 2.47.3
>>
>>
--
Alex Bennée
Virtualisation Tech Lead @ Linaro
^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [RFC PATCH v2 06/10] .agents/skills: add qemu-code-reviewer skill
2026-05-12 9:19 ` Alex Bennée
@ 2026-05-12 14:43 ` Chao Liu
0 siblings, 0 replies; 28+ messages in thread
From: Chao Liu @ 2026-05-12 14:43 UTC (permalink / raw)
To: Alex Bennée; +Cc: qemu-devel, John Snow, Cleber Rosa
On Tue, May 12, 2026 at 10:19:02AM +0100, Alex Bennée wrote:
> Chao Liu <chao.liu.zevorn@gmail.com> writes:
>
> > On Mon, May 11, 2026 at 06:04:55PM +0100, Alex Bennée wrote:
> >> This provides basic instructions for how to download and apply a
> >> patch series from the mailing list.
> >>
> >> Currently it is only taught about checkpatch but we could consider
> >> adding common code smells and review comments that come up frequently.
> >>
> >> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> >>
> >> ---
> >> v2
> >> - merge checkpatch skill
> >> - moved later in series to leverage build and test skills
> >> - properly reference qemu-build and qemu-tester skills
> >> - mention the qemu-code-explorer skill for navigation
> >> ---
> >> .agents/skills/qemu-code-reviewer/SKILL.md | 93 ++++++++++++++++++++++
> >> AGENTS.md | 1 +
> >> 2 files changed, 94 insertions(+)
> >> create mode 100644 .agents/skills/qemu-code-reviewer/SKILL.md
> >>
> >> diff --git a/.agents/skills/qemu-code-reviewer/SKILL.md b/.agents/skills/qemu-code-reviewer/SKILL.md
> >> new file mode 100644
> >> index 00000000000..48ec6b07520
> >> --- /dev/null
> >> +++ b/.agents/skills/qemu-code-reviewer/SKILL.md
> >> @@ -0,0 +1,93 @@
> >> +---
> >> +name: qemu-code-reviewer
> >> +description: Pull and apply patch series from mailing lists for review and testing in QEMU, including style and build validation.
> >> +license: GPL-2.0-or-later
> >> +---
> >> +
> >> +# QEMU Code Reviewer Skill
> >> +
> >> +This skill provides instructions on how to retrieve patch series submitted to the QEMU mailing list (`qemu-devel@nongnu.org`) using `b4` or manual methods.
> >> +
> >> +## Using b4 (Recommended)
> >> +
> >> +`b4` is the preferred tool for working with patch series from public-inbox instances like `lore.kernel.org`.
> >> +
> >> +### 1. Fetching a series
> >> +To download a series and prepare it for `git am`:
> >> +```bash
> >> +b4 am <message-id-or-url>
> >> +```
> >> +This creates a `.mbx` file containing the entire series, properly ordered.
> >> +
> >> +### 2. Applying a series directly
> >> +To apply a series directly to your current branch:
> >> +```bash
> >> +b4 shazam <message-id-or-url>
> >> +```
> >> +This is often the fastest way to get a series ready for testing.
> >> +
> >> +### 3. Creating a local branch for the series
> >> +```bash
> >> +b4 am -t <message-id-or-url>
> >> +git am ./*.mbx
> >> +```
> >> +The `-t` flag (or `--trust-all`) can be useful if you know the source.
> > I suggest using the git worktree command for workspace isolation before
> > applying patches.
>
> I don't know if this gets too much into the weeds of per-developer
> preference. Everyone has slightly different ways of working but they do
> want confidence that when they hand the wheel to their agent it isn't go
> to mess up their nice flow.
>
You’re right. It looks like keeping it as it is now is good enough.
Thanks,
Chao
> >
> >> +
> >> +## Manual mbox Retrieval (Alternative)
> >> +
> >> +If `b4` is unavailable, you can fetch the mbox manually from `lore.kernel.org`.
> >> +
> >> +### 1. Locate the thread
> >> +Find the patch series on [lore.kernel.org/qemu-devel/](https://lore.kernel.org/qemu-devel/).
> >> +
> >> +### 2. Download the mbox
> >> +Every thread on lore has an `mbox.gz` link. You can use `curl` or `wget`:
> >> +```bash
> >> +curl -L "https://lore.kernel.org/qemu-devel/<message-id>/raw" -o series.mbox
> >> +```
> >> +*Note: Appending `/raw` to the message URL usually provides the mbox format.*
> >> +
> >> +### 3. Apply with git am
> >> +```bash
> >> +git am series.mbox
> >> +```
> >> +
> >> +## Post-Application Steps
> >> +
> >> +Once the patches are applied, you should perform initial validation:
> >> +
> >> +### 1. Style Check
> >> +Run the QEMU checkpatch script to ensure the patches follow the project's coding style.
> >> +
> >> +- **Check applied patches**:
> >> + ```bash
> >> + ./scripts/checkpatch.pl master..HEAD
> >> + ```
> >> +- **Check a specific commit**:
> >> + ```bash
> >> + ./scripts/checkpatch.pl <commit-hash>^..
> >> + ```
> >> +- **Check a specific file**:
> >> + ```bash
> >> + ./scripts/checkpatch.pl -f <file-path>
> >> + ```
> >> +- **Strict mode** (often required for new code or specific subsystems):
> >> + ```bash
> >> + ./scripts/checkpatch.pl --strict <commit-range>
> >> + ```
> >> +
> >> +### 2. Build and Test
> >> +Refer to the `AGENTS.md` or the `qemu-build` and `qemu-testing` skills for build and test instructions.
> >> +- Ensure you are in a clean build directory.
> >> +- Run `ninja` or `make`.
> >> +- Run relevant tests (e.g., `make check-qtest`).
> >> +
> >> +### 3. Reviewing Patches
> >> +Refer to the `qemu-code-explorer` skill for navigating the code base and resolving functions and where they are called from.
> >> +
> > If the patches have multiple versions, should we ask the agent to summarize
> > the review history of the previous versions, as well as briefly summarize
> > the discussion across the current patch thread? This can be easy to miss
> > during manual review, but an agent can handle it well.
>
> That's a good idea. I've had good success in getting agents to review
> threads and summarise what was asked for. I have even had them apply the
> changes for me to review before committing.
>
> >
> > However, this seems better suited as a new skill.
>
> The qemu-mail-thread skill is a general purpose thread handling skill we
> could teach about versioning?
>
> >
> > Thanks,
> > Chao
> >> +
> >> +
> >> +## Common Troubleshooting
> >> +
> >> +- **Applying fails**: If `git am` fails due to conflicts, you may need to use `git am --3way` or manually resolve conflicts.
> >> +- **Missing dependencies**: Ensure your tree is up to date with the base branch the patches were intended for (usually `master`).
> >> diff --git a/AGENTS.md b/AGENTS.md
> >> index d9d1964d45a..fbbc3b65ed0 100644
> >> --- a/AGENTS.md
> >> +++ b/AGENTS.md
> >> @@ -27,6 +27,7 @@ You should use the following specialized skills for common tasks:
> >> - `qemu-code-explorer`: For finding where things are defined, how they're used, or understanding a specific subsystem.
> >> - `qemu-build`: For configuring and building QEMU (including debug and sanitizer builds).
> >> - `qemu-testing`: For finding, listing, and running individual tests (Unit, QTest, Functional, TCG).
> >> +- `qemu-code-reviewer`: For pulling and applying patch series from mailing lists.
> >>
> >> ## Source Code Layout (see `docs/devel/codebase.rst`)
> >> - **`accel/`**: Hardware accelerators (KVM, TCG, HVF, Xen, etc.) and architecture-agnostic acceleration code.
> >> --
> >> 2.47.3
> >>
> >>
>
> --
> Alex Bennée
> Virtualisation Tech Lead @ Linaro
^ permalink raw reply [flat|nested] 28+ messages in thread
* [RFC PATCH v2 07/10] .agents/skills: add qemu-mail-thread skill
2026-05-11 17:04 [RFC PATCH v2 00/10] AGENTS.md and associated skills Alex Bennée
` (5 preceding siblings ...)
2026-05-11 17:04 ` [RFC PATCH v2 06/10] .agents/skills: add qemu-code-reviewer skill Alex Bennée
@ 2026-05-11 17:04 ` Alex Bennée
2026-05-11 18:01 ` Alex Bennée
2026-05-12 3:07 ` Chao Liu
2026-05-11 17:04 ` [RFC PATCH v2 08/10] .agents/skills: add qemu-issue-helper skill Alex Bennée
` (2 subsequent siblings)
9 siblings, 2 replies; 28+ messages in thread
From: Alex Bennée @ 2026-05-11 17:04 UTC (permalink / raw)
To: qemu-devel; +Cc: John Snow, Alex Bennée, Cleber Rosa
Teach agents how to fetch and deal with archives of mail threads.
Just YOLO'ing the entire mail thread into an LLM context is quite
expensive especially if reviewing a thread against your current tree
state. This skill allows the agent to extract just the comments and
tags saving tokens.
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
---
v2
- rename to qemu-mail-thread
- add instructions on fetching threads via b4
- refactor the metadata handling in the script
- mention in AGENTS skill list
---
.agents/skills/qemu-mail-thread/SKILL.md | 34 +++++++
.../scripts/qemu_mail_parser.py | 98 +++++++++++++++++++
AGENTS.md | 1 +
3 files changed, 133 insertions(+)
create mode 100644 .agents/skills/qemu-mail-thread/SKILL.md
create mode 100644 .agents/skills/qemu-mail-thread/scripts/qemu_mail_parser.py
diff --git a/.agents/skills/qemu-mail-thread/SKILL.md b/.agents/skills/qemu-mail-thread/SKILL.md
new file mode 100644
index 00000000000..58e7c833a27
--- /dev/null
+++ b/.agents/skills/qemu-mail-thread/SKILL.md
@@ -0,0 +1,34 @@
+# QEMU Mail Thread
+
+This skill helps you fetch and extract reviewer comments from QEMU mailing list threads. It can handle standard `mbox` files (e.g., from `b4 mbox`) or raw text dumps from the user.
+
+## How to fetch a mail thread
+
+If you have a Message-ID (e.g., from a patch series), use `b4` to fetch the entire thread:
+
+```bash
+b4 mbox <message-id>
+```
+
+This will typically save an `.mbx` file in your current directory.
+
+## How to parse comments
+
+Use the included Python script to extract feedback, filtering out quoted text and diffs.
+
+```bash
+python .agents/skills/qemu-mail-thread/scripts/qemu_mail_parser.py <path_to_mail_thread_file>
+```
+
+The script automatically detects whether the input is a standard mbox or a raw text dump.
+
+## Expected Output
+The script generates `parsed_comments.txt` in the current working directory:
+```
+--- REPLY FROM Reviewer Name <email@example.com> ---
+Subject: Re: [PATCH 01/10] ...
+Comment text here...
+============================================================
+```
+
+Use this structured text to efficiently analyze the feedback and identify outstanding suggestions.
diff --git a/.agents/skills/qemu-mail-thread/scripts/qemu_mail_parser.py b/.agents/skills/qemu-mail-thread/scripts/qemu_mail_parser.py
new file mode 100644
index 00000000000..fdaac57ac15
--- /dev/null
+++ b/.agents/skills/qemu-mail-thread/scripts/qemu_mail_parser.py
@@ -0,0 +1,98 @@
+# SPDX-License-Identifier: GPL-2.0-or-later
+import sys
+import os
+import mailbox
+
+
+def is_metadata_line(line):
+ """Check if a line is metadata (quotes, diff, etc.)"""
+ return (line.startswith(">") or
+ line.startswith("---") or
+ line.startswith("diff "))
+
+
+def parse_raw_text(text, output_f):
+ # Split by the separator used in lore.kernel.org / b4 dumps
+ messages = text.split("----------------------------------------")
+ for msg in messages:
+ if not msg.strip(): continue
+
+ lines = msg.strip().split('\n')
+ author = ""
+ subject = ""
+ body_start = 0
+ for i, line in enumerate(lines):
+ if line.startswith("From: "): author = line[6:]
+ if line.startswith("Subject: "): subject = line[9:]
+ if not line.strip() and body_start == 0:
+ body_start = i + 1
+ break
+
+ is_reply = subject and ("Re: " in subject or subject.startswith("Re:"))
+
+ if is_reply and author != "" and not author.startswith("qemu-devel"):
+ output_f.write(f"--- REPLY FROM {author} ---\nSubject: {subject}\n")
+
+ for line in lines[body_start:]:
+ if not is_metadata_line(line):
+ output_f.write(line + "\n")
+ output_f.write("="*60 + "\n\n")
+
+
+def parse_mbox(mbox_path, output_f):
+ mbox = mailbox.mbox(mbox_path)
+ for message in mbox:
+ subject = message['subject']
+ if subject and 'Re: ' in subject:
+ author = message['from']
+ output_f.write(f"--- REPLY FROM {author} ---\nSubject: {subject}\n")
+
+ payload = message.get_payload()
+ body = ""
+ if isinstance(payload, list):
+ # Handle multipart
+ for part in payload:
+ if part.get_content_type() == 'text/plain':
+ body = part.get_payload(decode=True).decode('utf-8', errors='ignore')
+ break
+ else:
+ body = message.get_payload(decode=True).decode('utf-8', errors='ignore')
+
+ # Simple heuristic to extract comments
+ for line in body.split('\n'):
+ if line.strip() and not is_metadata_line(line.strip()):
+ output_f.write(line + "\n")
+ output_f.write("="*60 + "\n\n")
+
+
+def main():
+ if len(sys.argv) < 2:
+ print("Usage: python qemu_mail_parser.py <mail_thread_file>")
+ sys.exit(1)
+
+ input_file = sys.argv[1]
+ output_file = "parsed_comments.txt"
+
+ if not os.path.exists(input_file):
+ print(f"Error: File not found - {input_file}")
+ sys.exit(1)
+
+ with open(output_file, "w", encoding="utf-8") as out_f:
+ # Detect if it's an mbox or raw text
+ with open(input_file, 'rb') as f:
+ header = f.read(15)
+ is_mbox = header.startswith(b'From mboxrd@z ')
+
+ if is_mbox:
+ print(f"Parsing {input_file} as mbox...")
+ parse_mbox(input_file, out_f)
+ else:
+ print(f"Parsing {input_file} as raw text dump...")
+ with open(input_file, "r", encoding="utf-8", errors='ignore') as f:
+ text = f.read()
+ parse_raw_text(text, out_f)
+
+ print(f"Done. Extracted comments saved to {output_file}")
+
+if __name__ == "__main__":
+ main()
diff --git a/AGENTS.md b/AGENTS.md
index fbbc3b65ed0..d99d3078378 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -28,6 +28,7 @@ You should use the following specialized skills for common tasks:
- `qemu-build`: For configuring and building QEMU (including debug and sanitizer builds).
- `qemu-testing`: For finding, listing, and running individual tests (Unit, QTest, Functional, TCG).
- `qemu-code-reviewer`: For pulling and applying patch series from mailing lists.
+- `qemu-mail-thread`: For analyzing and parsing mailing list threads.
## Source Code Layout (see `docs/devel/codebase.rst`)
- **`accel/`**: Hardware accelerators (KVM, TCG, HVF, Xen, etc.) and architecture-agnostic acceleration code.
--
2.47.3
^ permalink raw reply related [flat|nested] 28+ messages in thread* Re: [RFC PATCH v2 07/10] .agents/skills: add qemu-mail-thread skill
2026-05-11 17:04 ` [RFC PATCH v2 07/10] .agents/skills: add qemu-mail-thread skill Alex Bennée
@ 2026-05-11 18:01 ` Alex Bennée
2026-05-12 3:07 ` Chao Liu
1 sibling, 0 replies; 28+ messages in thread
From: Alex Bennée @ 2026-05-11 18:01 UTC (permalink / raw)
To: qemu-devel; +Cc: John Snow, Cleber Rosa
Alex Bennée <alex.bennee@linaro.org> writes:
> Teach agents how to fetch and deal with archives of mail threads.
>
> Just YOLO'ing the entire mail thread into an LLM context is quite
> expensive especially if reviewing a thread against your current tree
> state. This skill allows the agent to extract just the comments and
> tags saving tokens.
>
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
>
> ---
> v2
> - rename to qemu-mail-thread
> - add instructions on fetching threads via b4
> - refactor the metadata handling in the script
> - mention in AGENTS skill list
> ---
> .agents/skills/qemu-mail-thread/SKILL.md | 34 +++++++
> .../scripts/qemu_mail_parser.py | 98 +++++++++++++++++++
> AGENTS.md | 1 +
> 3 files changed, 133 insertions(+)
> create mode 100644 .agents/skills/qemu-mail-thread/SKILL.md
> create mode 100644 .agents/skills/qemu-mail-thread/scripts/qemu_mail_parser.py
>
> diff --git a/.agents/skills/qemu-mail-thread/SKILL.md b/.agents/skills/qemu-mail-thread/SKILL.md
> new file mode 100644
> index 00000000000..58e7c833a27
> --- /dev/null
> +++ b/.agents/skills/qemu-mail-thread/SKILL.md
Amazingly I was testing this fine (probably because it was in the
context) but missed:
---
name: qemu-mail-thread
description: Fetch and extract reviewer comments from QEMU mailing list threads, handling mbox files or raw text dumps.
license: GPL-2.0-or-later
---
> @@ -0,0 +1,34 @@
> +# QEMU Mail Thread
> +
> +This skill helps you fetch and extract reviewer comments from QEMU mailing list threads. It can handle standard `mbox` files (e.g., from `b4 mbox`) or raw text dumps from the user.
> +
> +## How to fetch a mail thread
> +
> +If you have a Message-ID (e.g., from a patch series), use `b4` to fetch the entire thread:
> +
> +```bash
> +b4 mbox <message-id>
> +```
> +
> +This will typically save an `.mbx` file in your current directory.
> +
> +## How to parse comments
> +
> +Use the included Python script to extract feedback, filtering out quoted text and diffs.
> +
> +```bash
> +python .agents/skills/qemu-mail-thread/scripts/qemu_mail_parser.py <path_to_mail_thread_file>
> +```
> +
> +The script automatically detects whether the input is a standard mbox or a raw text dump.
> +
> +## Expected Output
> +The script generates `parsed_comments.txt` in the current working directory:
> +```
> +--- REPLY FROM Reviewer Name <email@example.com> ---
> +Subject: Re: [PATCH 01/10] ...
> +Comment text here...
> +============================================================
> +```
> +
> +Use this structured text to efficiently analyze the feedback and identify outstanding suggestions.
> diff --git a/.agents/skills/qemu-mail-thread/scripts/qemu_mail_parser.py b/.agents/skills/qemu-mail-thread/scripts/qemu_mail_parser.py
> new file mode 100644
> index 00000000000..fdaac57ac15
> --- /dev/null
> +++ b/.agents/skills/qemu-mail-thread/scripts/qemu_mail_parser.py
> @@ -0,0 +1,98 @@
> +# SPDX-License-Identifier: GPL-2.0-or-later
> +import sys
> +import os
> +import mailbox
> +
> +
> +def is_metadata_line(line):
> + """Check if a line is metadata (quotes, diff, etc.)"""
> + return (line.startswith(">") or
> + line.startswith("---") or
> + line.startswith("diff "))
> +
> +
> +def parse_raw_text(text, output_f):
> + # Split by the separator used in lore.kernel.org / b4 dumps
> + messages = text.split("----------------------------------------")
> + for msg in messages:
> + if not msg.strip(): continue
> +
> + lines = msg.strip().split('\n')
> + author = ""
> + subject = ""
> + body_start = 0
> + for i, line in enumerate(lines):
> + if line.startswith("From: "): author = line[6:]
> + if line.startswith("Subject: "): subject = line[9:]
> + if not line.strip() and body_start == 0:
> + body_start = i + 1
> + break
> +
> + is_reply = subject and ("Re: " in subject or subject.startswith("Re:"))
> +
> + if is_reply and author != "" and not author.startswith("qemu-devel"):
> + output_f.write(f"--- REPLY FROM {author} ---\nSubject: {subject}\n")
> +
> + for line in lines[body_start:]:
> + if not is_metadata_line(line):
> + output_f.write(line + "\n")
> + output_f.write("="*60 + "\n\n")
> +
> +
> +def parse_mbox(mbox_path, output_f):
> + mbox = mailbox.mbox(mbox_path)
> + for message in mbox:
> + subject = message['subject']
> + if subject and 'Re: ' in subject:
> + author = message['from']
> + output_f.write(f"--- REPLY FROM {author} ---\nSubject: {subject}\n")
> +
> + payload = message.get_payload()
> + body = ""
> + if isinstance(payload, list):
> + # Handle multipart
> + for part in payload:
> + if part.get_content_type() == 'text/plain':
> + body = part.get_payload(decode=True).decode('utf-8', errors='ignore')
> + break
> + else:
> + body = message.get_payload(decode=True).decode('utf-8', errors='ignore')
> +
> + # Simple heuristic to extract comments
> + for line in body.split('\n'):
> + if line.strip() and not is_metadata_line(line.strip()):
> + output_f.write(line + "\n")
> + output_f.write("="*60 + "\n\n")
> +
> +
> +def main():
> + if len(sys.argv) < 2:
> + print("Usage: python qemu_mail_parser.py <mail_thread_file>")
> + sys.exit(1)
> +
> + input_file = sys.argv[1]
> + output_file = "parsed_comments.txt"
> +
> + if not os.path.exists(input_file):
> + print(f"Error: File not found - {input_file}")
> + sys.exit(1)
> +
> + with open(output_file, "w", encoding="utf-8") as out_f:
> + # Detect if it's an mbox or raw text
> + with open(input_file, 'rb') as f:
> + header = f.read(15)
> + is_mbox = header.startswith(b'From mboxrd@z ')
> +
> + if is_mbox:
> + print(f"Parsing {input_file} as mbox...")
> + parse_mbox(input_file, out_f)
> + else:
> + print(f"Parsing {input_file} as raw text dump...")
> + with open(input_file, "r", encoding="utf-8", errors='ignore') as f:
> + text = f.read()
> + parse_raw_text(text, out_f)
> +
> + print(f"Done. Extracted comments saved to {output_file}")
> +
> +if __name__ == "__main__":
> + main()
> diff --git a/AGENTS.md b/AGENTS.md
> index fbbc3b65ed0..d99d3078378 100644
> --- a/AGENTS.md
> +++ b/AGENTS.md
> @@ -28,6 +28,7 @@ You should use the following specialized skills for common tasks:
> - `qemu-build`: For configuring and building QEMU (including debug and sanitizer builds).
> - `qemu-testing`: For finding, listing, and running individual tests (Unit, QTest, Functional, TCG).
> - `qemu-code-reviewer`: For pulling and applying patch series from mailing lists.
> +- `qemu-mail-thread`: For analyzing and parsing mailing list threads.
>
> ## Source Code Layout (see `docs/devel/codebase.rst`)
> - **`accel/`**: Hardware accelerators (KVM, TCG, HVF, Xen, etc.) and architecture-agnostic acceleration code.
--
Alex Bennée
Virtualisation Tech Lead @ Linaro
^ permalink raw reply [flat|nested] 28+ messages in thread* Re: [RFC PATCH v2 07/10] .agents/skills: add qemu-mail-thread skill
2026-05-11 17:04 ` [RFC PATCH v2 07/10] .agents/skills: add qemu-mail-thread skill Alex Bennée
2026-05-11 18:01 ` Alex Bennée
@ 2026-05-12 3:07 ` Chao Liu
1 sibling, 0 replies; 28+ messages in thread
From: Chao Liu @ 2026-05-12 3:07 UTC (permalink / raw)
To: Alex Bennée; +Cc: qemu-devel, John Snow, Cleber Rosa
Hi Alex,
On Mon, May 11, 2026 at 06:04:56PM +0100, Alex Bennée wrote:
> Teach agents how to fetch and deal with archives of mail threads.
>
> Just YOLO'ing the entire mail thread into an LLM context is quite
> expensive especially if reviewing a thread against your current tree
> state. This skill allows the agent to extract just the comments and
> tags saving tokens.
>
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
>
> ---
> v2
> - rename to qemu-mail-thread
> - add instructions on fetching threads via b4
> - refactor the metadata handling in the script
> - mention in AGENTS skill list
> ---
> .agents/skills/qemu-mail-thread/SKILL.md | 34 +++++++
> .../scripts/qemu_mail_parser.py | 98 +++++++++++++++++++
> AGENTS.md | 1 +
> 3 files changed, 133 insertions(+)
> create mode 100644 .agents/skills/qemu-mail-thread/SKILL.md
> create mode 100644 .agents/skills/qemu-mail-thread/scripts/qemu_mail_parser.py
>
> diff --git a/.agents/skills/qemu-mail-thread/SKILL.md b/.agents/skills/qemu-mail-thread/SKILL.md
> new file mode 100644
> index 00000000000..58e7c833a27
> --- /dev/null
> +++ b/.agents/skills/qemu-mail-thread/SKILL.md
> @@ -0,0 +1,34 @@
> +# QEMU Mail Thread
> +
> +This skill helps you fetch and extract reviewer comments from QEMU mailing list threads. It can handle standard `mbox` files (e.g., from `b4 mbox`) or raw text dumps from the user.
> +
OpenAI Codex (v0.129.0-alpha.2) shows a warning when loading this skill:
⚠ Skipped loading 1 skill(s) due to invalid SKILL.md files.
⚠ /home/zevorn/qemu/.agents/skills/qemu-mail-thread/SKILL.md: missing YAML frontmatter delimited by ---
I suggest adding a check-skill script that validates skill format.
Thanks,
Chao
> +## How to fetch a mail thread
> +
> +If you have a Message-ID (e.g., from a patch series), use `b4` to fetch the entire thread:
> +
> +```bash
> +b4 mbox <message-id>
> +```
> +
> +This will typically save an `.mbx` file in your current directory.
> +
> +## How to parse comments
> +
> +Use the included Python script to extract feedback, filtering out quoted text and diffs.
> +
> +```bash
> +python .agents/skills/qemu-mail-thread/scripts/qemu_mail_parser.py <path_to_mail_thread_file>
> +```
> +
> +The script automatically detects whether the input is a standard mbox or a raw text dump.
> +
> +## Expected Output
> +The script generates `parsed_comments.txt` in the current working directory:
> +```
> +--- REPLY FROM Reviewer Name <email@example.com> ---
> +Subject: Re: [PATCH 01/10] ...
> +Comment text here...
> +============================================================
> +```
> +
> +Use this structured text to efficiently analyze the feedback and identify outstanding suggestions.
> diff --git a/.agents/skills/qemu-mail-thread/scripts/qemu_mail_parser.py b/.agents/skills/qemu-mail-thread/scripts/qemu_mail_parser.py
> new file mode 100644
> index 00000000000..fdaac57ac15
> --- /dev/null
> +++ b/.agents/skills/qemu-mail-thread/scripts/qemu_mail_parser.py
> @@ -0,0 +1,98 @@
> +# SPDX-License-Identifier: GPL-2.0-or-later
> +import sys
> +import os
> +import mailbox
> +
> +
> +def is_metadata_line(line):
> + """Check if a line is metadata (quotes, diff, etc.)"""
> + return (line.startswith(">") or
> + line.startswith("---") or
> + line.startswith("diff "))
> +
> +
> +def parse_raw_text(text, output_f):
> + # Split by the separator used in lore.kernel.org / b4 dumps
> + messages = text.split("----------------------------------------")
> + for msg in messages:
> + if not msg.strip(): continue
> +
> + lines = msg.strip().split('\n')
> + author = ""
> + subject = ""
> + body_start = 0
> + for i, line in enumerate(lines):
> + if line.startswith("From: "): author = line[6:]
> + if line.startswith("Subject: "): subject = line[9:]
> + if not line.strip() and body_start == 0:
> + body_start = i + 1
> + break
> +
> + is_reply = subject and ("Re: " in subject or subject.startswith("Re:"))
> +
> + if is_reply and author != "" and not author.startswith("qemu-devel"):
> + output_f.write(f"--- REPLY FROM {author} ---\nSubject: {subject}\n")
> +
> + for line in lines[body_start:]:
> + if not is_metadata_line(line):
> + output_f.write(line + "\n")
> + output_f.write("="*60 + "\n\n")
> +
> +
> +def parse_mbox(mbox_path, output_f):
> + mbox = mailbox.mbox(mbox_path)
> + for message in mbox:
> + subject = message['subject']
> + if subject and 'Re: ' in subject:
> + author = message['from']
> + output_f.write(f"--- REPLY FROM {author} ---\nSubject: {subject}\n")
> +
> + payload = message.get_payload()
> + body = ""
> + if isinstance(payload, list):
> + # Handle multipart
> + for part in payload:
> + if part.get_content_type() == 'text/plain':
> + body = part.get_payload(decode=True).decode('utf-8', errors='ignore')
> + break
> + else:
> + body = message.get_payload(decode=True).decode('utf-8', errors='ignore')
> +
> + # Simple heuristic to extract comments
> + for line in body.split('\n'):
> + if line.strip() and not is_metadata_line(line.strip()):
> + output_f.write(line + "\n")
> + output_f.write("="*60 + "\n\n")
> +
> +
> +def main():
> + if len(sys.argv) < 2:
> + print("Usage: python qemu_mail_parser.py <mail_thread_file>")
> + sys.exit(1)
> +
> + input_file = sys.argv[1]
> + output_file = "parsed_comments.txt"
> +
> + if not os.path.exists(input_file):
> + print(f"Error: File not found - {input_file}")
> + sys.exit(1)
> +
> + with open(output_file, "w", encoding="utf-8") as out_f:
> + # Detect if it's an mbox or raw text
> + with open(input_file, 'rb') as f:
> + header = f.read(15)
> + is_mbox = header.startswith(b'From mboxrd@z ')
> +
> + if is_mbox:
> + print(f"Parsing {input_file} as mbox...")
> + parse_mbox(input_file, out_f)
> + else:
> + print(f"Parsing {input_file} as raw text dump...")
> + with open(input_file, "r", encoding="utf-8", errors='ignore') as f:
> + text = f.read()
> + parse_raw_text(text, out_f)
> +
> + print(f"Done. Extracted comments saved to {output_file}")
> +
> +if __name__ == "__main__":
> + main()
> diff --git a/AGENTS.md b/AGENTS.md
> index fbbc3b65ed0..d99d3078378 100644
> --- a/AGENTS.md
> +++ b/AGENTS.md
> @@ -28,6 +28,7 @@ You should use the following specialized skills for common tasks:
> - `qemu-build`: For configuring and building QEMU (including debug and sanitizer builds).
> - `qemu-testing`: For finding, listing, and running individual tests (Unit, QTest, Functional, TCG).
> - `qemu-code-reviewer`: For pulling and applying patch series from mailing lists.
> +- `qemu-mail-thread`: For analyzing and parsing mailing list threads.
>
> ## Source Code Layout (see `docs/devel/codebase.rst`)
> - **`accel/`**: Hardware accelerators (KVM, TCG, HVF, Xen, etc.) and architecture-agnostic acceleration code.
> --
> 2.47.3
>
>
^ permalink raw reply [flat|nested] 28+ messages in thread
* [RFC PATCH v2 08/10] .agents/skills: add qemu-issue-helper skill
2026-05-11 17:04 [RFC PATCH v2 00/10] AGENTS.md and associated skills Alex Bennée
` (6 preceding siblings ...)
2026-05-11 17:04 ` [RFC PATCH v2 07/10] .agents/skills: add qemu-mail-thread skill Alex Bennée
@ 2026-05-11 17:04 ` Alex Bennée
2026-05-11 17:04 ` [RFC PATCH v2 09/10] .agents/skills: add qemu-issue-triage agent skill Alex Bennée
2026-05-11 17:04 ` [RFC PATCH v2 10/10] MAINTAINERS: add a section for AI agents Alex Bennée
9 siblings, 0 replies; 28+ messages in thread
From: Alex Bennée @ 2026-05-11 17:04 UTC (permalink / raw)
To: qemu-devel; +Cc: John Snow, Alex Bennée, Cleber Rosa
This provides basic instructions for fetching issue details and
summarising details about the issue for other agents.
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
---
.agents/skills/qemu-issue-helper/SKILL.md | 47 +++++++++++++++++++++++
AGENTS.md | 1 +
2 files changed, 48 insertions(+)
create mode 100644 .agents/skills/qemu-issue-helper/SKILL.md
diff --git a/.agents/skills/qemu-issue-helper/SKILL.md b/.agents/skills/qemu-issue-helper/SKILL.md
new file mode 100644
index 00000000000..725097bac36
--- /dev/null
+++ b/.agents/skills/qemu-issue-helper/SKILL.md
@@ -0,0 +1,47 @@
+---
+name: qemu-issue-helper
+description: Summarize QEMU issue analysis for main agent. Helps sub-agents report findings including build config, CLI, tests, and GitLab issue data. Trigger when analyzing QEMU bugs or issues reported on GitLab.
+license: GPL-2.0-or-later
+---
+
+# QEMU Issue Helper
+
+Assist sub-agent in summarizing issue analysis for main agent.
+
+## Fetching Issue Data
+
+Use `glab` to retrieve issue details from GitLab. QEMU primary repo: `qemu-project/qemu`.
+
+### Commands
+- **View issue**: `glab issue view <ID_OR_URL> -R qemu-project/qemu`
+- **View comments**: `glab issue view <ID_OR_URL> -R qemu-project/qemu --comments`
+- **Search issues**: `glab issue list -R qemu-project/qemu --search "<KEYWORDS>"`
+
+## Report Format
+
+Sub-agent MUST provide a summary of the GitLab issue discussion and findings in this format:
+
+### 1. Issue Context
+- **Source**: GitLab URL/ID.
+- **Title**: Short issue description.
+- **Reporter**: User who found it.
+- **Relevant Commits**: List any commits mentioned in the issue that are related to the bug or previous attempts to fix it.
+
+### 2. Build & Reproduction (from issue)
+- **Reported Environment**: Host OS, CPU, QEMU version.
+- **Build Configuration**: Required `configure` flags mentioned in the issue.
+- **Reproduction CLI**: Exact QEMU command used to reproduce.
+
+### 3. Proposed Fixes & Series
+- **Proposed Fixes**: Flag any specific code snippets or logic fixes suggested in the comments.
+- **Patch Series**: Note if any patch series or Merge Requests have been linked.
+
+### 4. Discussion Summary
+- **Current Consensus**: What is the community's current understanding of the bug?
+- **Key Constraints**: Note any blockers, requirements, or specific feedback from maintainers.
+- **Next Steps**: What is needed to move the issue forward?
+
+## Rules
+- **No Independent Analysis**: Do not perform your own root cause analysis. Summarize ONLY what is present in the issue tracker.
+- **Terse**: Use brief technical English.
+- **Links**: Provide direct links to relevant comments or patches if available.
diff --git a/AGENTS.md b/AGENTS.md
index d99d3078378..ca292460403 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -29,6 +29,7 @@ You should use the following specialized skills for common tasks:
- `qemu-testing`: For finding, listing, and running individual tests (Unit, QTest, Functional, TCG).
- `qemu-code-reviewer`: For pulling and applying patch series from mailing lists.
- `qemu-mail-thread`: For analyzing and parsing mailing list threads.
+- `qemu-issue-helper`: For fetching and summarising issue details from the bug tracker.
## Source Code Layout (see `docs/devel/codebase.rst`)
- **`accel/`**: Hardware accelerators (KVM, TCG, HVF, Xen, etc.) and architecture-agnostic acceleration code.
--
2.47.3
^ permalink raw reply related [flat|nested] 28+ messages in thread* [RFC PATCH v2 09/10] .agents/skills: add qemu-issue-triage agent skill
2026-05-11 17:04 [RFC PATCH v2 00/10] AGENTS.md and associated skills Alex Bennée
` (7 preceding siblings ...)
2026-05-11 17:04 ` [RFC PATCH v2 08/10] .agents/skills: add qemu-issue-helper skill Alex Bennée
@ 2026-05-11 17:04 ` Alex Bennée
2026-05-11 17:04 ` [RFC PATCH v2 10/10] MAINTAINERS: add a section for AI agents Alex Bennée
9 siblings, 0 replies; 28+ messages in thread
From: Alex Bennée @ 2026-05-11 17:04 UTC (permalink / raw)
To: qemu-devel; +Cc: John Snow, Alex Bennée, Cleber Rosa
While triaging the issue tracker I wondered if this would be a
suitable job for an AI agent. Unfortunately the OSS program doesn't
give any credits to run agents in gitlab. However I do have access to
models from my editor and ECA so I built one and tested it on a few
issues.
We might want to consider adding some common "issue smells" for common
problems in issues. For example triggering asserts that have been
added to the code and other such annoyances.
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
---
v4
- fix a bunch of typos in SKILL
- update evals
- remove mentions of ECA
- fix typo referencing old skill name
- remove eca__spawn_agent reference
- clean-up authentication handling
- teach it about scoped labels
- make less chatty in the comments
- updated commit msg
- suggest running things in parallel (use agents)
- more pointers to incompleteness
v3
- more imperative phrasing
v2
- prefer sub-agent
- mention parameters
- don't be over eager to tag host or target for generic bugs
- signoff comments as an agent on behalf of the user
- detect patch available and apply appropriate tags
---
.agents/skills/qemu-issue-triage/SKILL.md | 112 +++++++++++++++
.../qemu-issue-triage/assets/labels.txt | 133 ++++++++++++++++++
.../skills/qemu-issue-triage/evals/evals.json | 18 +++
.../scripts/update_labels.sh | 16 +++
AGENTS.md | 1 +
5 files changed, 280 insertions(+)
create mode 100644 .agents/skills/qemu-issue-triage/SKILL.md
create mode 100644 .agents/skills/qemu-issue-triage/assets/labels.txt
create mode 100644 .agents/skills/qemu-issue-triage/evals/evals.json
create mode 100755 .agents/skills/qemu-issue-triage/scripts/update_labels.sh
diff --git a/.agents/skills/qemu-issue-triage/SKILL.md b/.agents/skills/qemu-issue-triage/SKILL.md
new file mode 100644
index 00000000000..a0802e24dd3
--- /dev/null
+++ b/.agents/skills/qemu-issue-triage/SKILL.md
@@ -0,0 +1,112 @@
+---
+name: qemu-issue-triage
+description: Use this skill to triage and label GitLab issues for the QEMU project
+license: GPL-2.0-or-later
+---
+
+# Instructions
+
+This skill provides specialized instructions for triaging GitLab issues for the QEMU project.
+
+## Parameter Handling & Execution Strategy (CRITICAL)
+1. **Parameters**: If the user invokes this skill with multiple arguments or a list of IDs (e.g., `#3430, #3426`), treat each as an independent target.
+2. **Sub-Agent Mandate**: To prevent polluting the main conversation context, **you MUST ALWAYS spawn a sub-agent** to perform the actual triage.
+ - **Parallelization**: When multiple IDs are provided, spawn one sub-agent per issue in parallel to improve efficiency.
+ - Do NOT run `glab` commands or read the label cache directly in the main context.
+ - In the `task` parameter for the sub-agent, provide the target `<issue-id>` and explicitly instruct the sub-agent to follow the "Triage Workflow" and "Asset Management" rules defined below.
+ - Wait for the sub-agent to finish and simply report its summary to the user.
+
+## Goal
+Automate the initial triage of new bug reports and feature requests in the QEMU GitLab repository.
+
+## Prerequisites
+- `glab` CLI tool installed.
+- An authentication method: Use `glab auth status` to check. You can pass a token by using `env GITLAB_TOKEN=<token>` in front of commands if you have it.
+- Target Repo: Use `-R qemu-project/qemu` if not in a clone, or ensure the remote is set correctly.
+
+## Asset Management (Label Cache)
+This skill uses a cached list of labels to avoid unnecessary API calls and ensure consistent labeling.
+- **Cache Location:** `assets/labels.txt` relative to this skill.
+- **Updating the Cache:** If the user asks to update the labels, or if you suspect a label is missing, run the provided script:
+ ```bash
+ cd .agents/skills/qemu-issue-triage/scripts && ./update_labels.sh
+ ```
+- **Using the Cache:** Before applying labels, ALWAYS read `assets/labels.txt` (or use `grep` on it) to review the available labels and their descriptions. This ensures you use the exact spelling and understand the intent behind the label (e.g., `kind::Bug`, `Storage`). Do NOT guess label names.
+
+## Triage Workflow
+
+### 1. Information Gathering
+Fetch the issue details:
+```bash
+glab issue view <issue-id> -R qemu-project/qemu --comments
+```
+
+### 2. Evaluate Completeness
+Analyze the issue against the bug template requirements:
+- **Host Arch/OS**: Is the host environment specified?
+- **Guest Arch/OS**: Is the guest environment specified?
+- **QEMU Version**: Is the version mentioned?
+- **Reproduction Steps**: Are there clear steps to reproduce?
+- **Expected vs Actual**: Is the bug clearly described?
+
+**Workflow::Needs Info Triggers (CRITICAL):**
+Request more information and apply the `workflow::Needs Info` label if any of the following are true:
+- **Missing Command Line**: The full QEMU command line (`qemu-system-* ...`) used to reproduce the issue is missing.
+- **Old QEMU Version**: The reported version is older than the last two major releases. Ask the reporter to re-test with the current upstream master or the latest stable release.
+- **Distro Version**: The version string suggests a downstream/distro-specific package (e.g., contains suffixes like `.el9`, `.fc40`, `-ubuntu`, or long strings like `7.2.0-14.sc05...`). Ask the reporter to reproduce the issue using a clean build from the current upstream source to rule out distro-specific patches.
+
+**Actions:**
+- If information is missing based on the triggers above, add the `workflow::Needs Info` label and post a polite comment asking for the specific missing details. (Remember to sign the comment as "Issue Agent Bot on behalf of the user" per the Guidelines).
+- If the issue is well-defined and uses a recent upstream version, proceed to categorization.
+
+### 3. Categorization & Labelling
+Apply labels based on the issue content. **Crucially, consult `assets/labels.txt` to find the exact matching labels for the categories below.**
+
+#### Scoped Labels (Prefix::Label)
+QEMU uses scoped labels (e.g., `kind::Bug`, `workflow::Triaged`) to group related categories.
+- **Prefixes:** Common prefixes include `kind::`, `workflow::`, `Closed::`, `Audit Tooling::`, `GUI::`.
+- **Constraint:** Only one label from that scope can be active at a time. Applying a new scoped label of the same type (e.g `workflow::`) will remove the other.
+
+#### Kinds
+- `kind::Bug`: For unexpected behavior.
+- `kind::Feature Request`: For new functionality.
+- `kind::Task`: For research, investigations, and miscellaneous issues.
+
+#### Targets (target: *) and Hosts (host: *)
+Detect the guest architecture (`target: *`) or host environment (`host: *`).
+**IMPORTANT:** Be conservative when applying `target:` and `host:` labels. Many bugs (e.g., in generic devices like USB, PCI, or block controllers) apply to ANY guest that includes the device. The reproducer (like a `qtest` invocation) might just use a convenient target (e.g., `i386`) as an example. ONLY apply `target:` or `host:` labels if the bug is strictly architecture- or host-dependent (e.g., a bug in ARM CPU emulation, or a macOS-specific build failure).
+
+#### Accelerators (accel: *)
+Detect the accelerator mentioned (e.g., `accel: KVM`, `accel: TCG`, `accel: HVF`).
+
+#### Subsystems
+Identify the relevant subsystem (e.g., `Storage`, `Networking`, `device:virtio`, `Migration`).
+
+#### Testcases
+- If the issue provides a minimal C program, a shell script, or a specific disk image to reproduce the bug, apply the `TestCase` label.
+
+#### Patches and Fixes
+- If the issue description or comments contain a link to a patch on the mailing list (e.g., `lore.kernel.org`, `patchew.org`), or explicitly mention that a patch/fix has been submitted, apply the `workflow::Patch available` label.
+
+#### Workflow Management
+The `workflow::` labels track the lifecycle of an issue.
+- **Single Workflow Label:** An issue can only have one `workflow::` label at a time.
+- **Transitioning:** Adding a new workflow label will automatically remove the old one (e.g., adding `workflow::Patch available` will remove `workflow::Triaged`).
+
+#### Other comments
+- If other developers have commented see if those comments imply additional tags should be applied.
+
+### 4. Updating the Issue
+Apply the labels and optionally assign a priority if clear.
+**Transitioning Workflow Example:**
+```bash
+glab issue update <issue-id> -R qemu-project/qemu --label "workflow::Triaged,kind::Bug"
+```
+
+## Guidelines
+- Be polite and professional in comments.
+- **IMPORTANT:** Any comments added to the issue MUST include the phrase: "Issue Agent Bot on behalf of the user" (e.g., as a sign-off at the end of the message).
+- Avoid commenting unless additional information is needed, specifically a comment to acknowledge the report is superfluous.
+- Use `workflow::Triaged` once categorization is complete.
+- Avoid assigning issues to specific people unless they are explicitly mentioned or are the known maintainer for a very specific subsystem.
+- Use the `scripts/get_maintainer.pl` logic (via file paths mentioned in the issue) to identify potential subsystems.
diff --git a/.agents/skills/qemu-issue-triage/assets/labels.txt b/.agents/skills/qemu-issue-triage/assets/labels.txt
new file mode 100644
index 00000000000..12d3cc7e6f0
--- /dev/null
+++ b/.agents/skills/qemu-issue-triage/assets/labels.txt
@@ -0,0 +1,133 @@
+ACPI Power Management related (ACPI / SMBIOS / HEST / GHES)
+Audio Audio devices; both backend (host audio) and frontend (guest audio)
+Audit Tooling::AI For bugs found with AI assisted tools such as Mythos and other similar things
+Audit Tooling::Fuzzer Issues found via fuzzing. For security issues, please consult https://www.qemu.org/contribute/security-process/
+Audit Tooling::Other Some unknown/unclassified type of audit tooling.
+Audit Tooling::Sanitizer For issues found using sanitizers such as asan, lsan and tsan
+Audit Tooling::Static Analysis Static analysis such as Coverity or more modern compilers.
+Bite Sized Candidates for first contributions; see also https://wiki.qemu.org/Contribute/BiteSizedTasks
+Build System configure, make, Meson, ninja, gcc, clang, ccache, etc.
+CI Continuous Integration; gitlab, patchew, etc.
+CLI Command Line Interface
+Chardev Character device backends and related issues
+Closed::Duplicate There is already another ticket that is about the same issue
+Closed::Fixed The issue was fixed. Yay!
+Closed::Invalid This issue was not really a problem
+Closed::NotOurBug This is a bug, but not a bug in QEMU. Please report it and/or include a link to the report.
+Closed::NotReproducible This issue was not reproducible
+Closed::UnbackedFeature Nobody was willing to work on this feature request
+Closed::WontFix The issue was acknowledged, but the fix would be too complex, too expensive, or would introduce other problems.
+Cryptography
+Documentation Sphinx documentation, man pages, the wiki, --help output, etc.
+GDB Issues relating to using GDB via the gdbstub
+GUI Graphical User Interface (gtk, SDL, curses, VNC, spice, ...)
+GUI::Cocoa Cocoa
+GUI::DBus DBus
+GUI::GTK GTK
+GUI::SDL SDL
+GUI::SPICE SPICE
+GUI::VNC
+Guest Agent Issues related to the qemu-guest-agent binary. https://wiki.qemu.org/Features/GuestAgent
+Hard
+Launchpad Issues migrated from Launchpad
+Migration
+Modules
+Networking
+Python Python library issues (./python/)
+QAPI/QMP QEMU API / QEMU Machine Protocol, HMP and CLI, etc.
+QOM QEMU Object Model
+Regression This is a regression from previously working behaviour
+Security This is a security issue - see https://www.qemu.org/docs/master/system/security.html for guidance
+Semihosting Semihosting calls provide a simple ABI for early bring-up of embedded devices, see https://www.qemu.org/docs/master/about/emulation.html#semihosting
+Softfloat QEMU's FPU emulation code (TCG only)
+Stable::can't fix The bug was reported on a stable branch but the fix is too invasive for backporting
+Stable::obsolete The bug was reported on a stable branch that is not maintained anymore
+Stable::to backport The bug was reported on a stable branch and needs to be backported on the next release from the branch
+Storage Block subsystem, Storage devices, etc.
+TCG plugins Anything related to the TCG plugins feature
+TestCase The report includes a testcase
+Tests qtests, iotests, acceptance tests, VM tests, docker tests, and more. See https://www.qemu.org/docs/master/devel/testing/index.html
+USB
+VFIO
+accel: HAX Intel's Hardware Accelerated Execution Manager (HAXM)
+accel: HVF Apple Hypervisor Framework
+accel: KVM Linux Kernel-based Virtual Machine
+accel: TCG QEMU Tiny Code Generator
+accel: WHPX Microsoft Windows Hypervisor Platform (WHPX)
+accel: Xen Xen Hypervisor
+block:9p The 9p network file system
+block:NVMe
+block:curl
+block:nbd
+block:nfs Issues related to the NFS backend
+block:qcow2
+block:ssh
+block:vmdk
+bsd-user
+device: PCI
+device: TPM Trusted Platform Module (TPM) devices
+device: iommu
+device: mmio mmio and other directly emulated devices
+device:graphics Issues relating to display device emulation, or rendering in general. See also "GUI".
+device:input Keyboards, Mice, Touchscreens, HIDs, etc.
+device:iommu IOMMU and SMMU
+device:pflash Parallel NOR flashes emulation
+device:sdmmc SD or (e)MMC cards emulation
+device:virtio virtio-related issues. https://www.linux-kvm.org/page/Virtio
+device:watchdog
+efi EFI firmware related issues
+flaky-ci For test cases that are flaky when run under our CI
+gitlab
+guest: AIX
+guest: BSD Guest OS is BSD (NetBSD/FreeBSD/OpenBSD/etc)
+guest: Linux Guest OS is Linux/Linux-based
+guest: Windows Microsoft Windows guest
+guest: macOS Apple macOS / Darwin as guest OS
+guest: os2
+host: aarch64 Bugs reproducible on AArch64 hosts
+host: arm Bugs reproducible on ARM hosts
+host: loongarch64 Bugs reproducible on LoongArch64 hosts.
+host: mips Bugs reproducible on MIPS hosts
+host: ppc Bugs reproducible on Power hosts
+host: riscv Bugs reproducible on RISC-V hosts
+host: s390 Bugs reproducible on s390 hosts
+host: sparc64 Bugs specific to Sparc64 hosts
+host: x86 Bugs reproducible on x86 hosts
+host:32bit These are mostly TCG related bugs where we sometimes struggle with emulating larger guests, especially atomic and address space issues.
+hostos: BSD FreeBSD, OpenBSD, NetBSD, and derivatives as host OSes
+hostos: Linux Linux-based host operating systems (Fedora, RHEL/CentOS, Debian, Ubuntu, openSuSE et al)
+hostos: Windows Microsoft Windows host OS
+hostos: macOS Apple macOS / Darwin as a host OS
+icount issues relating to icount, deterministic execution and record/replay functionality
+kind::Bug Bug or defect in functionality.
+kind::Feature Request Feature request or new functionality.
+kind::Task Research, investigations, and miscellaneous issues.
+libvfio-user
+linux-user issues with QEMU's lightweight user-mode emulator
+qemu-img
+sysadmin Issues related to QEMU project infrastructure. You should probably also check on the projects IRC channel if the issue is urgent - https://www.qemu.org/support/
+target: alpha DEC Alpha [alpha]
+target: arm Arm AArch32 or AArch64 [arm, aarch64]
+target: avr Atmel AVR [avr]
+target: hexagon Qualcomm Hexagon [hexagon]
+target: hppa Hewlett-Packard Precision Architecture; HP/HP, PA-RISC [hppa]
+target: i386 Intel/AMD x86 [i386, x86_64]
+target: loongarch loongarch64 target architecture
+target: m68k Motorola 68000 [m68k]
+target: microblaze Xilinx MicroBlaze [microblaze, microblazeel]
+target: mips MIPS [mips, mipsel, mips64, mips64el]
+target: nios2 Altera Nios II [nios2]
+target: openrisc OpenRISC [or1k]
+target: ppc IBM Power Architecture, PowerPC [ppc, ppc64, ppc64le]
+target: riscv RISC-V [riscv32, riscv64]
+target: rx Renesas RX [rx]
+target: s390x IBM Z, SystemZ, zSeries [s390x]
+target: sh4 Renesas SuperH [sh4, sh4eb]
+target: sparc Sun Microsystems SPARC [sparc, sparc64]
+target: tricore Infineon TriCore [tricore]
+target: xtensa Tensilica Xtensa [xtensa, xtensaeb]
+workflow::Confirmed Bugs that have been confirmed and reproduced.
+workflow::In Progress Someone is working on this issue.
+workflow::Needs Info Issue has insufficient information to verify.
+workflow::Patch available A patch is available
+workflow::Triaged Issue has been triaged and given a topic label.
diff --git a/.agents/skills/qemu-issue-triage/evals/evals.json b/.agents/skills/qemu-issue-triage/evals/evals.json
new file mode 100644
index 00000000000..572c0723fd4
--- /dev/null
+++ b/.agents/skills/qemu-issue-triage/evals/evals.json
@@ -0,0 +1,18 @@
+# SPDX-License-Identifier: GPL-2.0-or-later
+{
+ "skill_name": "qemu-issue-triage",
+ "evals": [
+ {
+ "id": 1,
+ "prompt": "Update the cached list of GitLab labels for the QEMU project.",
+ "expected_output": "The skill should fetch the latest labels from GitLab and save them to the skill's assets directory.",
+ "files": []
+ },
+ {
+ "id": 2,
+ "prompt": "Triage issue #1234. Assume the user provided clear steps but no subsystem label is obvious.",
+ "expected_output": "The skill should read the cached label list (not fetch from GitLab) and apply relevant kind/target labels.",
+ "files": []
+ }
+ ]
+}
\ No newline at end of file
diff --git a/.agents/skills/qemu-issue-triage/scripts/update_labels.sh b/.agents/skills/qemu-issue-triage/scripts/update_labels.sh
new file mode 100755
index 00000000000..1605eab4de5
--- /dev/null
+++ b/.agents/skills/qemu-issue-triage/scripts/update_labels.sh
@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: GPL-2.0-or-later
+set -e
+
+if [ -z "$GITLAB_TOKEN" ]; then
+ echo "GITLAB_TOKEN is not set. Attempting to fetch via pass..."
+ export GITLAB_TOKEN=$(pass gitlab-api)
+fi
+
+echo "Fetching labels from qemu-project/qemu..."
+# Fetch labels using API and format as "Name Description"
+glab api /projects/qemu-project%2Fqemu/labels --paginate | \
+ jq -r '.[] | [ .name, .description ] | @tsv' | \
+ column -t -s $'\t' > ../assets/labels.txt
+
+echo "Labels cached in assets/labels.txt"
diff --git a/AGENTS.md b/AGENTS.md
index ca292460403..6387d164816 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -30,6 +30,7 @@ You should use the following specialized skills for common tasks:
- `qemu-code-reviewer`: For pulling and applying patch series from mailing lists.
- `qemu-mail-thread`: For analyzing and parsing mailing list threads.
- `qemu-issue-helper`: For fetching and summarising issue details from the bug tracker.
+- `qemu-issue-triage`: For helping triage issues in the bug tracker.
## Source Code Layout (see `docs/devel/codebase.rst`)
- **`accel/`**: Hardware accelerators (KVM, TCG, HVF, Xen, etc.) and architecture-agnostic acceleration code.
--
2.47.3
^ permalink raw reply related [flat|nested] 28+ messages in thread* [RFC PATCH v2 10/10] MAINTAINERS: add a section for AI agents
2026-05-11 17:04 [RFC PATCH v2 00/10] AGENTS.md and associated skills Alex Bennée
` (8 preceding siblings ...)
2026-05-11 17:04 ` [RFC PATCH v2 09/10] .agents/skills: add qemu-issue-triage agent skill Alex Bennée
@ 2026-05-11 17:04 ` Alex Bennée
2026-05-11 17:33 ` Daniel P. Berrangé
9 siblings, 1 reply; 28+ messages in thread
From: Alex Bennée @ 2026-05-11 17:04 UTC (permalink / raw)
To: qemu-devel; +Cc: John Snow, Alex Bennée, Cleber Rosa
For completeness add a section to MAINTAINERS to catch changes should
we decide to merge this.
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
---
MAINTAINERS | 6 ++++++
1 file changed, 6 insertions(+)
diff --git a/MAINTAINERS b/MAINTAINERS
index 9d3d6459537..6f98db096b4 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -4565,6 +4565,12 @@ M: Pierrick Bouvier <pierrick.bouvier@oss.qualcomm.com>
S: Maintained
F: docs/
+AI Agent Skills
+M: Alex Bennée <alex.bennee@linaro.org>
+S: Maintained
+F: .agents/skills/
+F: AGENTS.md
+
Build System
------------
Meson
--
2.47.3
^ permalink raw reply related [flat|nested] 28+ messages in thread