Re: [RFC PATCH v2 04/10] .agents/skills: add qemu-build skill

[Chao Liu <chao.liu.zevorn@gmail.com>]

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