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

["Daniel P. Berrangé" <berrange@redhat.com>]

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