Re: [RFC PATCH v2 01/10] AGENTS.md: add basic AGENTS.md for QEMU

["Alex Bennée" <alex.bennee@linaro.org>]

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