[PATCH v2] agents: Add a skill for finding your way around QEMU

[PATCH v2] agents: Add a skill for finding your way around QEMU

[Paolo Bonzini]

As a side effect, establish scaffolding for the .agents/.claude/.gemini
directories, as a base for future patches to build on.

Some parts of this skill are based on
https://lore.kernel.org/r/20260529101437.410181-4-alex.bennee@linaro.org/.

Co-authored-by: Alex Bennée <alex.bennee@linaro.org>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
---
v1->v2: add .claude/.gitignore.  Suggest using get_maintainer.pl and ./run.
        Fix thinko around build/source directory


 .agents/skills/qemu-codebase/SKILL.md | 100 ++++++++++++++++++++++++++
 .claude/.gitignore                    |   2 +
 .claude/skills                        |   1 +
 .gemini/skills                        |   1 +
 4 files changed, 104 insertions(+)
 create mode 100644 .agents/skills/qemu-codebase/SKILL.md
 create mode 100644 .claude/.gitignore
 create mode 120000 .claude/skills
 create mode 120000 .gemini/skills

diff --git a/.agents/skills/qemu-codebase/SKILL.md b/.agents/skills/qemu-codebase/SKILL.md
new file mode 100644
index 00000000000..17fb55b5289
--- /dev/null
+++ b/.agents/skills/qemu-codebase/SKILL.md
@@ -0,0 +1,100 @@
+---
+name: qemu-codebase
+description: Orientation for QEMU — tree structure, build system, documentation pointers
+---
+
+# Useful reminders for working on QEMU
+
+## Finding things
+
+`MAINTAINERS` is the authoritative list of subsystems.  You can
+use it and `scripts/get_maintainer.pl --nogit` to query it, for example
+
+```
+$ scripts/get_maintainer.pl --nogit -f block/
+```
+
+`docs/devel/codebase.rst` is a guided tour of every top-level directory.
+Here are some important ones:
+
+- **target/** holds CPU models and the TCG frontends
+- **tcg/** holds the backends and the IR. See `docs/devel/tcg.rst`,
+  `docs/devel/tcg-ops.rst`.
+- **hw/** is devices and boards, categorized by type.
+- **linux-user/** and **bsd-user/** are almost entirely separate, and only
+  have parts of **hw/core/** and **accel/**'s CPU emulation infrastructure
+  in common with system emulation
+
+Other directories include the back-end subsystems, for example **`block/`**
+for the block layer.
+
+The `include/` tree mostly mirrors the top-level tree.
+
+## Build layout
+
+Build is always out-of-tree; the build directory is created by
+`configure` and a checkout can have several. Determine it from context
+(`ls */meson-info`) rather than assuming.
+
+The `run` script in the root of the build dir wraps `meson devenv` and
+should be used to execute commands in the build directory.  It activates
+the build tree's venv `pyvenv/`, adds various Python modules from
+the source tree to `PYTHONPATH`, and defines a `MESON_BUILD_ROOT`
+variable for general use.
+
+`make` at the top level forwards to `ninja` in the configured build
+directory, and any `build.ninja` target can be invoked that way.
+
+## Build & Test
+- **Build**: `ninja` or `make -jN` from build directory
+- **Test All**: `make check`
+- **Suites**: `make check-unit`, `make check-qtest`, `make check-functional`, `make check-rust`
+- **Single Test**: `./run meson test <testname>` (e.g., `./run meson test qtest-x86_64/boot-serial-test`)
+- **Debug**: Append `V=1` for verbose output or `DEBUG=1` for interactive test debugging.
+
+## Code Style
+- **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 and functions; `CamelCase` for types and enums.
+- **Memory**: Use GLib (`g_malloc`, `g_free`, `g_autofree`) or QEMU (`qemu_memalign`) APIs. No `malloc`.
+- **Errors**: Use `error_report()` or `error_setg()`. Avoid `printf` for errors.
+- **Lints**: Run `./scripts/checkpatch.pl`.  On top, `make clippy` and `make rustfmt` for Rust.
+
+# Documentation pointers
+
+Developer docs live in `docs/devel`.  A `kernel-doc::` directive includes
+documentation comments from source files when Sphinx builds the documentation.
+These comments be consulted just as easily in the source tree without going
+through e.g. `make html`.
+
+Here are some useful pointers.
+
+## Core abstractions
+
+- **QOM** (`qom/`, `include/qom/`) is the type/object system underneath
+  everything.  It includes class and interface hierarchies, properties, and
+  the object composition tree.  See `docs/devel/qom.rst`.
+- **qdev** builds devices on top of QOM, adding for example buses, the
+  realize/unrealize lifecycle (including hot-plug/unplug), and reset.  See
+  `docs/devel/qdev-api.rst` and `docs/devel/reset.rst`.
+- **MemoryRegion** (`system/memory.c`, `include/system/memory.h`) is the
+  guest address-space model: regions, aliases, address spaces, dirty tracking,
+  load/store and map/unmap operations, etc.  See `docs/devel/memory.rst`.
+
+## Concurrency
+
+Getting the threading model wrong is a common source of subtle bugs here.
+
+- The **BQL** (big QEMU lock) protects most device emulation; vCPU threads
+  hold it when exiting to emulation.  See `include/qemu/main-loop.h`.
+  Memory regions can (carefully) opt out of the BQL.
+- **AioContext**/iothreads: block devices and their virtio front-ends can run
+  outside the BQL.  See `docs/devel/multiple-iothreads.rst`.
+- The **block layer** is coroutine-based.  `co_` prefixes and `coroutine_fn`
+  annotations are advisory but relevant for reviewers.  Coroutines have their
+  own locking primitives.
+- **RCU** is used for hot, rarely-modified structures such as memory maps.
+  Because of the BQL, RCU is mostly used with `call_rcu()` rather than
+  `synchronize_rcu()`.  See `docs/devel/rcu.rst` and `docs/devel/atomics.rst`.
diff --git a/.claude/.gitignore b/.claude/.gitignore
new file mode 100644
index 00000000000..b0a57a19c01
--- /dev/null
+++ b/.claude/.gitignore
@@ -0,0 +1,2 @@
+# reserved for the user to add their own per-project rules
+/CLAUDE.md
diff --git a/.claude/skills b/.claude/skills
new file mode 120000
index 00000000000..a7540c24423
--- /dev/null
+++ b/.claude/skills
@@ -0,0 +1 @@
+.agents/skills/
\ No newline at end of file
diff --git a/.gemini/skills b/.gemini/skills
new file mode 120000
index 00000000000..a7540c24423
--- /dev/null
+++ b/.gemini/skills
@@ -0,0 +1 @@
+.agents/skills/
\ No newline at end of file
-- 
2.55.0

Re: [PATCH v2] agents: Add a skill for finding your way around QEMU

[Philippe Mathieu-Daudé]

On 4/9/26 09:43, Paolo Bonzini wrote:
> As a side effect, establish scaffolding for the .agents/.claude/.gemini
> directories, as a base for future patches to build on.
> 
> Some parts of this skill are based on
> https://lore.kernel.org/r/20260529101437.410181-4-alex.bennee@linaro.org/.
> 
> Co-authored-by: Alex Bennée <alex.bennee@linaro.org>
> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
> ---
> v1->v2: add .claude/.gitignore.  Suggest using get_maintainer.pl and ./run.
>          Fix thinko around build/source directory
> 
> 
>   .agents/skills/qemu-codebase/SKILL.md | 100 ++++++++++++++++++++++++++
>   .claude/.gitignore                    |   2 +
>   .claude/skills                        |   1 +
>   .gemini/skills                        |   1 +
>   4 files changed, 104 insertions(+)
>   create mode 100644 .agents/skills/qemu-codebase/SKILL.md
>   create mode 100644 .claude/.gitignore
>   create mode 120000 .claude/skills
>   create mode 120000 .gemini/skills


> +- **target/** holds CPU models and the TCG frontends
> +- **tcg/** holds the backends and the IR. See `docs/devel/tcg.rst`,
> +  `docs/devel/tcg-ops.rst`.
> +- **hw/** is devices and boards, categorized by type.
> +- **linux-user/** and **bsd-user/** are almost entirely separate,

common-user/ is where we are moving their common code.

> and only
> +  have parts of **hw/core/** and **accel/**'s CPU emulation infrastructure
> +  in common with system emulation
> +
> +Other directories include the back-end subsystems, for example **`block/`**
> +for the block layer.
> +
> +The `include/` tree mostly mirrors the top-level tree.
> +
> +## Build layout
> +
> +Build is always out-of-tree; the build directory is created by
> +`configure` and a checkout can have several. Determine it from context
> +(`ls */meson-info`) rather than assuming.
> +
> +The `run` script in the root of the build dir wraps `meson devenv` and
> +should be used to execute commands in the build directory.  It activates
> +the build tree's venv `pyvenv/`, adds various Python modules from
> +the source tree to `PYTHONPATH`, and defines a `MESON_BUILD_ROOT`
> +variable for general use.
> +
> +`make` at the top level forwards to `ninja` in the configured build
> +directory, and any `build.ninja` target can be invoked that way.
> +
> +## Build & Test
> +- **Build**: `ninja` or `make -jN` from build directory
> +- **Test All**: `make check`
> +- **Suites**: `make check-unit`, `make check-qtest`, `make check-functional`, `make check-rust`
> +- **Single Test**: `./run meson test <testname>` (e.g., `./run meson test qtest-x86_64/boot-serial-test`)
> +- **Debug**: Append `V=1` for verbose output or `DEBUG=1` for interactive test debugging.
> +
> +## Code Style

Ref to 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 and functions; `CamelCase` for types and enums.
> +- **Memory**: Use GLib (`g_malloc`, `g_free`, `g_autofree`) or QEMU (`qemu_memalign`) APIs. No `malloc`.
> +- **Errors**: Use `error_report()` or `error_setg()`. Avoid `printf` for errors.
> +- **Lints**: Run `./scripts/checkpatch.pl`.  On top, `make clippy` and `make rustfmt` for Rust.
> +
> +# Documentation pointers
> +
> +Developer docs live in `docs/devel`.  A `kernel-doc::` directive includes
> +documentation comments from source files when Sphinx builds the documentation.
> +These comments be consulted just as easily in the source tree without going
> +through e.g. `make html`.
> +
> +Here are some useful pointers.
> +
> +## Core abstractions
> +
> +- **QOM** (`qom/`, `include/qom/`) is the type/object system underneath
> +  everything.  It includes class and interface hierarchies, properties, and
> +  the object composition tree.  See `docs/devel/qom.rst`.
> +- **qdev** builds devices on top of QOM, adding for example buses, 

GPIOs / IRQs,

> the
> +  realize/unrealize lifecycle (including hot-plug/unplug), and reset.  See
> +  `docs/devel/qdev-api.rst` and `docs/devel/reset.rst`.
> +- **MemoryRegion** (`system/memory.c`, `include/system/memory.h`) is the
> +  guest address-space model: regions, aliases, address spaces, dirty tracking,
> +  load/store and map/unmap operations, etc.  See `docs/devel/memory.rst`.
> +
> +## Concurrency
> +
> +Getting the threading model wrong is a common source of subtle bugs here.
> +
> +- The **BQL** (big QEMU lock) protects most device emulation; vCPU threads
> +  hold it when exiting to emulation.  See `include/qemu/main-loop.h`.
> +  Memory regions can (carefully) opt out of the BQL.

(I'd move the RCU entry here)

> +- **AioContext**/iothreads: block devices and their virtio front-ends can run
> +  outside the BQL.  See `docs/devel/multiple-iothreads.rst`.
> +- The **block layer** is coroutine-based.  `co_` prefixes and `coroutine_fn`
> +  annotations are advisory but relevant for reviewers.  Coroutines have their
> +  own locking primitives.
> +- **RCU** is used for hot, rarely-modified structures such as memory maps.
> +  Because of the BQL, RCU is mostly used with `call_rcu()` rather than
> +  `synchronize_rcu()`.  See `docs/devel/rcu.rst` and `docs/devel/atomics.rst`.

(move earlier)

Re: [PATCH v2] agents: Add a skill for finding your way around QEMU

[Daniel P. Berrangé]

On Fri, Sep 04, 2026 at 09:43:13AM +0200, Paolo Bonzini wrote:
> As a side effect, establish scaffolding for the .agents/.claude/.gemini
> directories, as a base for future patches to build on.

FWIW, While researching the AGENTS.md stuff I came across this

  https://arxiv.org/pdf/2602.11988

which suggests that providing code tree overviews may not be as
helpful as people suspect, while causing the agents to consume
more tokens in their work.

It is pretty hard to benchmark / evaluate this, but it does
suggest the "Finding things" / "Core abstractions" sections
might be overkill/counterproductive. Aspects that are less
discoverable or describing QEMU specific policies/practices
ought to remain valuable.

> 
> Some parts of this skill are based on
> https://lore.kernel.org/r/20260529101437.410181-4-alex.bennee@linaro.org/.
> 
> Co-authored-by: Alex Bennée <alex.bennee@linaro.org>
> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
> ---
> v1->v2: add .claude/.gitignore.  Suggest using get_maintainer.pl and ./run.
>         Fix thinko around build/source directory
> 
> 
>  .agents/skills/qemu-codebase/SKILL.md | 100 ++++++++++++++++++++++++++
>  .claude/.gitignore                    |   2 +
>  .claude/skills                        |   1 +
>  .gemini/skills                        |   1 +
>  4 files changed, 104 insertions(+)
>  create mode 100644 .agents/skills/qemu-codebase/SKILL.md
>  create mode 100644 .claude/.gitignore
>  create mode 120000 .claude/skills
>  create mode 120000 .gemini/skills
> 
> diff --git a/.agents/skills/qemu-codebase/SKILL.md b/.agents/skills/qemu-codebase/SKILL.md
> new file mode 100644
> index 00000000000..17fb55b5289
> --- /dev/null
> +++ b/.agents/skills/qemu-codebase/SKILL.md
> @@ -0,0 +1,100 @@
> +---
> +name: qemu-codebase
> +description: Orientation for QEMU — tree structure, build system, documentation pointers
> +---
> +
> +# Useful reminders for working on QEMU
> +
> +## Finding things
> +
> +`MAINTAINERS` is the authoritative list of subsystems.  You can
> +use it and `scripts/get_maintainer.pl --nogit` to query it, for example
> +
> +```
> +$ scripts/get_maintainer.pl --nogit -f block/
> +```
> +
> +`docs/devel/codebase.rst` is a guided tour of every top-level directory.
> +Here are some important ones:
> +
> +- **target/** holds CPU models and the TCG frontends
> +- **tcg/** holds the backends and the IR. See `docs/devel/tcg.rst`,
> +  `docs/devel/tcg-ops.rst`.
> +- **hw/** is devices and boards, categorized by type.
> +- **linux-user/** and **bsd-user/** are almost entirely separate, and only
> +  have parts of **hw/core/** and **accel/**'s CPU emulation infrastructure
> +  in common with system emulation
> +
> +Other directories include the back-end subsystems, for example **`block/`**
> +for the block layer.
> +
> +The `include/` tree mostly mirrors the top-level tree.
> +
> +## Build layout
> +
> +Build is always out-of-tree; the build directory is created by
> +`configure` and a checkout can have several. Determine it from context
> +(`ls */meson-info`) rather than assuming.
> +
> +The `run` script in the root of the build dir wraps `meson devenv` and
> +should be used to execute commands in the build directory.  It activates
> +the build tree's venv `pyvenv/`, adds various Python modules from
> +the source tree to `PYTHONPATH`, and defines a `MESON_BUILD_ROOT`
> +variable for general use.
> +
> +`make` at the top level forwards to `ninja` in the configured build
> +directory, and any `build.ninja` target can be invoked that way.
> +
> +## Build & Test
> +- **Build**: `ninja` or `make -jN` from build directory
> +- **Test All**: `make check`
> +- **Suites**: `make check-unit`, `make check-qtest`, `make check-functional`, `make check-rust`
> +- **Single Test**: `./run meson test <testname>` (e.g., `./run meson test qtest-x86_64/boot-serial-test`)
> +- **Debug**: Append `V=1` for verbose output or `DEBUG=1` for interactive test debugging.
> +
> +## Code Style
> +- **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 and functions; `CamelCase` for types and enums.
> +- **Memory**: Use GLib (`g_malloc`, `g_free`, `g_autofree`) or QEMU (`qemu_memalign`) APIs. No `malloc`.
> +- **Errors**: Use `error_report()` or `error_setg()`. Avoid `printf` for errors.
> +- **Lints**: Run `./scripts/checkpatch.pl`.  On top, `make clippy` and `make rustfmt` for Rust.
> +
> +# Documentation pointers
> +
> +Developer docs live in `docs/devel`.  A `kernel-doc::` directive includes
> +documentation comments from source files when Sphinx builds the documentation.
> +These comments be consulted just as easily in the source tree without going
> +through e.g. `make html`.
> +
> +Here are some useful pointers.
> +
> +## Core abstractions
> +
> +- **QOM** (`qom/`, `include/qom/`) is the type/object system underneath
> +  everything.  It includes class and interface hierarchies, properties, and
> +  the object composition tree.  See `docs/devel/qom.rst`.
> +- **qdev** builds devices on top of QOM, adding for example buses, the
> +  realize/unrealize lifecycle (including hot-plug/unplug), and reset.  See
> +  `docs/devel/qdev-api.rst` and `docs/devel/reset.rst`.
> +- **MemoryRegion** (`system/memory.c`, `include/system/memory.h`) is the
> +  guest address-space model: regions, aliases, address spaces, dirty tracking,
> +  load/store and map/unmap operations, etc.  See `docs/devel/memory.rst`.
> +
> +## Concurrency
> +
> +Getting the threading model wrong is a common source of subtle bugs here.
> +
> +- The **BQL** (big QEMU lock) protects most device emulation; vCPU threads
> +  hold it when exiting to emulation.  See `include/qemu/main-loop.h`.
> +  Memory regions can (carefully) opt out of the BQL.
> +- **AioContext**/iothreads: block devices and their virtio front-ends can run
> +  outside the BQL.  See `docs/devel/multiple-iothreads.rst`.
> +- The **block layer** is coroutine-based.  `co_` prefixes and `coroutine_fn`
> +  annotations are advisory but relevant for reviewers.  Coroutines have their
> +  own locking primitives.
> +- **RCU** is used for hot, rarely-modified structures such as memory maps.
> +  Because of the BQL, RCU is mostly used with `call_rcu()` rather than
> +  `synchronize_rcu()`.  See `docs/devel/rcu.rst` and `docs/devel/atomics.rst`.
> diff --git a/.claude/.gitignore b/.claude/.gitignore
> new file mode 100644
> index 00000000000..b0a57a19c01
> --- /dev/null
> +++ b/.claude/.gitignore
> @@ -0,0 +1,2 @@
> +# reserved for the user to add their own per-project rules
> +/CLAUDE.md
> diff --git a/.claude/skills b/.claude/skills
> new file mode 120000
> index 00000000000..a7540c24423
> --- /dev/null
> +++ b/.claude/skills
> @@ -0,0 +1 @@
> +.agents/skills/
> \ No newline at end of file
> diff --git a/.gemini/skills b/.gemini/skills
> new file mode 120000
> index 00000000000..a7540c24423
> --- /dev/null
> +++ b/.gemini/skills
> @@ -0,0 +1 @@
> +.agents/skills/
> \ No newline at end of file
> -- 
> 2.55.0
> 

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 :|

Re: [PATCH v2] agents: Add a skill for finding your way around QEMU

[Paolo Bonzini]

On 9/4/26 12:46, Daniel P. Berrangé wrote:
> On Fri, Sep 04, 2026 at 09:43:13AM +0200, Paolo Bonzini wrote:
>> As a side effect, establish scaffolding for the .agents/.claude/.gemini
>> directories, as a base for future patches to build on.
> 
> FWIW, While researching the AGENTS.md stuff I came across this
> 
>    https://arxiv.org/pdf/2602.11988
> 
> which suggests that providing code tree overviews may not be as
> helpful as people suspect, while causing the agents to consume
> more tokens in their work.

I found the... skill creator skill, which suggests: "assume the agent 
can navigate code, keep discovery cheap, and load documentation only 
when it changes a decision."  It does seem like it should be possible to 
shorten this.

Thanks!

Paolo

> It is pretty hard to benchmark / evaluate this, but it does
> suggest the "Finding things" / "Core abstractions" sections
> might be overkill/counterproductive. Aspects that are less
> discoverable or describing QEMU specific policies/practices
> ought to remain valuable.
> 
>>
>> Some parts of this skill are based on
>> https://lore.kernel.org/r/20260529101437.410181-4-alex.bennee@linaro.org/.
>>
>> Co-authored-by: Alex Bennée <alex.bennee@linaro.org>
>> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
>> ---
>> v1->v2: add .claude/.gitignore.  Suggest using get_maintainer.pl and ./run.
>>          Fix thinko around build/source directory
>>
>>
>>   .agents/skills/qemu-codebase/SKILL.md | 100 ++++++++++++++++++++++++++
>>   .claude/.gitignore                    |   2 +
>>   .claude/skills                        |   1 +
>>   .gemini/skills                        |   1 +
>>   4 files changed, 104 insertions(+)
>>   create mode 100644 .agents/skills/qemu-codebase/SKILL.md
>>   create mode 100644 .claude/.gitignore
>>   create mode 120000 .claude/skills
>>   create mode 120000 .gemini/skills
>>
>> diff --git a/.agents/skills/qemu-codebase/SKILL.md b/.agents/skills/qemu-codebase/SKILL.md
>> new file mode 100644
>> index 00000000000..17fb55b5289
>> --- /dev/null
>> +++ b/.agents/skills/qemu-codebase/SKILL.md
>> @@ -0,0 +1,100 @@
>> +---
>> +name: qemu-codebase
>> +description: Orientation for QEMU — tree structure, build system, documentation pointers
>> +---
>> +
>> +# Useful reminders for working on QEMU
>> +
>> +## Finding things
>> +
>> +`MAINTAINERS` is the authoritative list of subsystems.  You can
>> +use it and `scripts/get_maintainer.pl --nogit` to query it, for example
>> +
>> +```
>> +$ scripts/get_maintainer.pl --nogit -f block/
>> +```
>> +
>> +`docs/devel/codebase.rst` is a guided tour of every top-level directory.
>> +Here are some important ones:
>> +
>> +- **target/** holds CPU models and the TCG frontends
>> +- **tcg/** holds the backends and the IR. See `docs/devel/tcg.rst`,
>> +  `docs/devel/tcg-ops.rst`.
>> +- **hw/** is devices and boards, categorized by type.
>> +- **linux-user/** and **bsd-user/** are almost entirely separate, and only
>> +  have parts of **hw/core/** and **accel/**'s CPU emulation infrastructure
>> +  in common with system emulation
>> +
>> +Other directories include the back-end subsystems, for example **`block/`**
>> +for the block layer.
>> +
>> +The `include/` tree mostly mirrors the top-level tree.
>> +
>> +## Build layout
>> +
>> +Build is always out-of-tree; the build directory is created by
>> +`configure` and a checkout can have several. Determine it from context
>> +(`ls */meson-info`) rather than assuming.
>> +
>> +The `run` script in the root of the build dir wraps `meson devenv` and
>> +should be used to execute commands in the build directory.  It activates
>> +the build tree's venv `pyvenv/`, adds various Python modules from
>> +the source tree to `PYTHONPATH`, and defines a `MESON_BUILD_ROOT`
>> +variable for general use.
>> +
>> +`make` at the top level forwards to `ninja` in the configured build
>> +directory, and any `build.ninja` target can be invoked that way.
>> +
>> +## Build & Test
>> +- **Build**: `ninja` or `make -jN` from build directory
>> +- **Test All**: `make check`
>> +- **Suites**: `make check-unit`, `make check-qtest`, `make check-functional`, `make check-rust`
>> +- **Single Test**: `./run meson test <testname>` (e.g., `./run meson test qtest-x86_64/boot-serial-test`)
>> +- **Debug**: Append `V=1` for verbose output or `DEBUG=1` for interactive test debugging.
>> +
>> +## Code Style
>> +- **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 and functions; `CamelCase` for types and enums.
>> +- **Memory**: Use GLib (`g_malloc`, `g_free`, `g_autofree`) or QEMU (`qemu_memalign`) APIs. No `malloc`.
>> +- **Errors**: Use `error_report()` or `error_setg()`. Avoid `printf` for errors.
>> +- **Lints**: Run `./scripts/checkpatch.pl`.  On top, `make clippy` and `make rustfmt` for Rust.
>> +
>> +# Documentation pointers
>> +
>> +Developer docs live in `docs/devel`.  A `kernel-doc::` directive includes
>> +documentation comments from source files when Sphinx builds the documentation.
>> +These comments be consulted just as easily in the source tree without going
>> +through e.g. `make html`.
>> +
>> +Here are some useful pointers.
>> +
>> +## Core abstractions
>> +
>> +- **QOM** (`qom/`, `include/qom/`) is the type/object system underneath
>> +  everything.  It includes class and interface hierarchies, properties, and
>> +  the object composition tree.  See `docs/devel/qom.rst`.
>> +- **qdev** builds devices on top of QOM, adding for example buses, the
>> +  realize/unrealize lifecycle (including hot-plug/unplug), and reset.  See
>> +  `docs/devel/qdev-api.rst` and `docs/devel/reset.rst`.
>> +- **MemoryRegion** (`system/memory.c`, `include/system/memory.h`) is the
>> +  guest address-space model: regions, aliases, address spaces, dirty tracking,
>> +  load/store and map/unmap operations, etc.  See `docs/devel/memory.rst`.
>> +
>> +## Concurrency
>> +
>> +Getting the threading model wrong is a common source of subtle bugs here.
>> +
>> +- The **BQL** (big QEMU lock) protects most device emulation; vCPU threads
>> +  hold it when exiting to emulation.  See `include/qemu/main-loop.h`.
>> +  Memory regions can (carefully) opt out of the BQL.
>> +- **AioContext**/iothreads: block devices and their virtio front-ends can run
>> +  outside the BQL.  See `docs/devel/multiple-iothreads.rst`.
>> +- The **block layer** is coroutine-based.  `co_` prefixes and `coroutine_fn`
>> +  annotations are advisory but relevant for reviewers.  Coroutines have their
>> +  own locking primitives.
>> +- **RCU** is used for hot, rarely-modified structures such as memory maps.
>> +  Because of the BQL, RCU is mostly used with `call_rcu()` rather than
>> +  `synchronize_rcu()`.  See `docs/devel/rcu.rst` and `docs/devel/atomics.rst`.
>> diff --git a/.claude/.gitignore b/.claude/.gitignore
>> new file mode 100644
>> index 00000000000..b0a57a19c01
>> --- /dev/null
>> +++ b/.claude/.gitignore
>> @@ -0,0 +1,2 @@
>> +# reserved for the user to add their own per-project rules
>> +/CLAUDE.md
>> diff --git a/.claude/skills b/.claude/skills
>> new file mode 120000
>> index 00000000000..a7540c24423
>> --- /dev/null
>> +++ b/.claude/skills
>> @@ -0,0 +1 @@
>> +.agents/skills/
>> \ No newline at end of file
>> diff --git a/.gemini/skills b/.gemini/skills
>> new file mode 120000
>> index 00000000000..a7540c24423
>> --- /dev/null
>> +++ b/.gemini/skills
>> @@ -0,0 +1 @@
>> +.agents/skills/
>> \ No newline at end of file
>> -- 
>> 2.55.0
>>
> 
> With regards,
> Daniel

Re: [PATCH v2] agents: Add a skill for finding your way around QEMU

[Alex Bennée]

Daniel P. Berrangé <berrange@redhat.com> writes:

> On Fri, Sep 04, 2026 at 09:43:13AM +0200, Paolo Bonzini wrote:
>> As a side effect, establish scaffolding for the .agents/.claude/.gemini
>> directories, as a base for future patches to build on.
>
> FWIW, While researching the AGENTS.md stuff I came across this
>
>   https://arxiv.org/pdf/2602.11988
>
> which suggests that providing code tree overviews may not be as
> helpful as people suspect, while causing the agents to consume
> more tokens in their work.
>
> It is pretty hard to benchmark / evaluate this, but it does
> suggest the "Finding things" / "Core abstractions" sections
> might be overkill/counterproductive.

I've been using local rules to try and force using semcode which allows
for a more tied together browsing of the code as well as interrogating
lore instead of lots of shell grepping. But yes it seems the tree
overview doesn't help as much as it could. We could just point to
docs/devel/codebase.rst and let the agent read that if it needs to. 

> Aspects that are less
> discoverable or describing QEMU specific policies/practices
> ought to remain valuable.
>
>> 
>> Some parts of this skill are based on
>> https://lore.kernel.org/r/20260529101437.410181-4-alex.bennee@linaro.org/.
>> 
>> Co-authored-by: Alex Bennée <alex.bennee@linaro.org>
>> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
>> ---
>> v1->v2: add .claude/.gitignore.  Suggest using get_maintainer.pl and ./run.
>>         Fix thinko around build/source directory
>> 
>> 
>>  .agents/skills/qemu-codebase/SKILL.md | 100 ++++++++++++++++++++++++++
>>  .claude/.gitignore                    |   2 +
>>  .claude/skills                        |   1 +
>>  .gemini/skills                        |   1 +
>>  4 files changed, 104 insertions(+)
>>  create mode 100644 .agents/skills/qemu-codebase/SKILL.md
>>  create mode 100644 .claude/.gitignore
>>  create mode 120000 .claude/skills
>>  create mode 120000 .gemini/skills
>> 
>> diff --git a/.agents/skills/qemu-codebase/SKILL.md b/.agents/skills/qemu-codebase/SKILL.md
>> new file mode 100644
>> index 00000000000..17fb55b5289
>> --- /dev/null
>> +++ b/.agents/skills/qemu-codebase/SKILL.md
>> @@ -0,0 +1,100 @@
>> +---
>> +name: qemu-codebase
>> +description: Orientation for QEMU — tree structure, build system, documentation pointers
>> +---
>> +
>> +# Useful reminders for working on QEMU
>> +
>> +## Finding things
>> +
>> +`MAINTAINERS` is the authoritative list of subsystems.  You can
>> +use it and `scripts/get_maintainer.pl --nogit` to query it, for example
>> +
>> +```
>> +$ scripts/get_maintainer.pl --nogit -f block/
>> +```
>> +
>> +`docs/devel/codebase.rst` is a guided tour of every top-level directory.
>> +Here are some important ones:
>> +
>> +- **target/** holds CPU models and the TCG frontends
>> +- **tcg/** holds the backends and the IR. See `docs/devel/tcg.rst`,
>> +  `docs/devel/tcg-ops.rst`.
>> +- **hw/** is devices and boards, categorized by type.
>> +- **linux-user/** and **bsd-user/** are almost entirely separate, and only
>> +  have parts of **hw/core/** and **accel/**'s CPU emulation infrastructure
>> +  in common with system emulation
>> +
>> +Other directories include the back-end subsystems, for example **`block/`**
>> +for the block layer.
>> +
>> +The `include/` tree mostly mirrors the top-level tree.
>> +
>> +## Build layout
>> +
>> +Build is always out-of-tree; the build directory is created by
>> +`configure` and a checkout can have several. Determine it from context
>> +(`ls */meson-info`) rather than assuming.
>> +
>> +The `run` script in the root of the build dir wraps `meson devenv` and
>> +should be used to execute commands in the build directory.  It activates
>> +the build tree's venv `pyvenv/`, adds various Python modules from
>> +the source tree to `PYTHONPATH`, and defines a `MESON_BUILD_ROOT`
>> +variable for general use.
>> +
>> +`make` at the top level forwards to `ninja` in the configured build
>> +directory, and any `build.ninja` target can be invoked that way.
>> +
>> +## Build & Test
>> +- **Build**: `ninja` or `make -jN` from build directory
>> +- **Test All**: `make check`
>> +- **Suites**: `make check-unit`, `make check-qtest`, `make check-functional`, `make check-rust`
>> +- **Single Test**: `./run meson test <testname>` (e.g., `./run meson test qtest-x86_64/boot-serial-test`)
>> +- **Debug**: Append `V=1` for verbose output or `DEBUG=1` for interactive test debugging.
>> +
>> +## Code Style
>> +- **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 and functions; `CamelCase` for types and enums.
>> +- **Memory**: Use GLib (`g_malloc`, `g_free`, `g_autofree`) or QEMU (`qemu_memalign`) APIs. No `malloc`.
>> +- **Errors**: Use `error_report()` or `error_setg()`. Avoid `printf` for errors.
>> +- **Lints**: Run `./scripts/checkpatch.pl`.  On top, `make clippy` and `make rustfmt` for Rust.
>> +
>> +# Documentation pointers
>> +
>> +Developer docs live in `docs/devel`.  A `kernel-doc::` directive includes
>> +documentation comments from source files when Sphinx builds the documentation.
>> +These comments be consulted just as easily in the source tree without going
>> +through e.g. `make html`.
>> +
>> +Here are some useful pointers.
>> +
>> +## Core abstractions
>> +
>> +- **QOM** (`qom/`, `include/qom/`) is the type/object system underneath
>> +  everything.  It includes class and interface hierarchies, properties, and
>> +  the object composition tree.  See `docs/devel/qom.rst`.
>> +- **qdev** builds devices on top of QOM, adding for example buses, the
>> +  realize/unrealize lifecycle (including hot-plug/unplug), and reset.  See
>> +  `docs/devel/qdev-api.rst` and `docs/devel/reset.rst`.
>> +- **MemoryRegion** (`system/memory.c`, `include/system/memory.h`) is the
>> +  guest address-space model: regions, aliases, address spaces, dirty tracking,
>> +  load/store and map/unmap operations, etc.  See `docs/devel/memory.rst`.
>> +
>> +## Concurrency
>> +
>> +Getting the threading model wrong is a common source of subtle bugs here.
>> +
>> +- The **BQL** (big QEMU lock) protects most device emulation; vCPU threads
>> +  hold it when exiting to emulation.  See `include/qemu/main-loop.h`.
>> +  Memory regions can (carefully) opt out of the BQL.
>> +- **AioContext**/iothreads: block devices and their virtio front-ends can run
>> +  outside the BQL.  See `docs/devel/multiple-iothreads.rst`.
>> +- The **block layer** is coroutine-based.  `co_` prefixes and `coroutine_fn`
>> +  annotations are advisory but relevant for reviewers.  Coroutines have their
>> +  own locking primitives.
>> +- **RCU** is used for hot, rarely-modified structures such as memory maps.
>> +  Because of the BQL, RCU is mostly used with `call_rcu()` rather than
>> +  `synchronize_rcu()`.  See `docs/devel/rcu.rst` and `docs/devel/atomics.rst`.
>> diff --git a/.claude/.gitignore b/.claude/.gitignore
>> new file mode 100644
>> index 00000000000..b0a57a19c01
>> --- /dev/null
>> +++ b/.claude/.gitignore
>> @@ -0,0 +1,2 @@
>> +# reserved for the user to add their own per-project rules
>> +/CLAUDE.md
>> diff --git a/.claude/skills b/.claude/skills
>> new file mode 120000
>> index 00000000000..a7540c24423
>> --- /dev/null
>> +++ b/.claude/skills
>> @@ -0,0 +1 @@
>> +.agents/skills/
>> \ No newline at end of file
>> diff --git a/.gemini/skills b/.gemini/skills
>> new file mode 120000
>> index 00000000000..a7540c24423
>> --- /dev/null
>> +++ b/.gemini/skills
>> @@ -0,0 +1 @@
>> +.agents/skills/
>> \ No newline at end of file
>> -- 
>> 2.55.0
>> 
>
> With regards,
> Daniel

-- 
Alex Bennée
Virtualisation Tech Lead @ Linaro