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

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

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

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

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

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

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

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