{"id":2233111,"url":"http://patchwork.ozlabs.org/api/1.2/patches/2233111/?format=json","web_url":"http://patchwork.ozlabs.org/project/qemu-devel/patch/20260505170105.228162-3-alex.bennee@linaro.org/","project":{"id":14,"url":"http://patchwork.ozlabs.org/api/1.2/projects/14/?format=json","name":"QEMU Development","link_name":"qemu-devel","list_id":"qemu-devel.nongnu.org","list_email":"qemu-devel@nongnu.org","web_url":"","scm_url":"","webscm_url":"","list_archive_url":"","list_archive_url_format":"","commit_url_format":""},"msgid":"<20260505170105.228162-3-alex.bennee@linaro.org>","list_archive_url":null,"date":"2026-05-05T17:00:57","name":"[RFC,02/10] .agents/skills: add qemu-code-explorer skill","commit_ref":null,"pull_url":null,"state":"new","archived":false,"hash":"be9b96f323fa9c28a315de275d970a566b5d33aa","submitter":{"id":39532,"url":"http://patchwork.ozlabs.org/api/1.2/people/39532/?format=json","name":"Alex Bennée","email":"alex.bennee@linaro.org"},"delegate":null,"mbox":"http://patchwork.ozlabs.org/project/qemu-devel/patch/20260505170105.228162-3-alex.bennee@linaro.org/mbox/","series":[{"id":502869,"url":"http://patchwork.ozlabs.org/api/1.2/series/502869/?format=json","web_url":"http://patchwork.ozlabs.org/project/qemu-devel/list/?series=502869","date":"2026-05-05T17:01:00","name":"AGENTS.md and associated skills","version":1,"mbox":"http://patchwork.ozlabs.org/series/502869/mbox/"}],"comments":"http://patchwork.ozlabs.org/api/patches/2233111/comments/","check":"pending","checks":"http://patchwork.ozlabs.org/api/patches/2233111/checks/","tags":{},"related":[],"headers":{"Return-Path":"","X-Original-To":"incoming@patchwork.ozlabs.org","Delivered-To":"patchwork-incoming@legolas.ozlabs.org","Authentication-Results":["legolas.ozlabs.org;\n\tdkim=pass (2048-bit key;\n unprotected) header.d=linaro.org header.i=@linaro.org header.a=rsa-sha256\n header.s=google header.b=D854Vgzr;\n\tdkim-atps=neutral","legolas.ozlabs.org;\n spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org\n (client-ip=209.51.188.17; helo=lists1p.gnu.org;\n envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org;\n receiver=patchwork.ozlabs.org)"],"Received":["from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17])\n\t(using TLSv1.2 with cipher ECDHE-ECDSA-AES256-GCM-SHA384 (256/256 bits))\n\t(No client certificate requested)\n\tby legolas.ozlabs.org (Postfix) with ESMTPS id 4g94bX4pt6z1yJ0\n\tfor ; Wed, 06 May 2026 03:03:36 +1000 (AEST)","from localhost ([::1] helo=lists1p.gnu.org)\n\tby lists1p.gnu.org with esmtp (Exim 4.90_1)\n\t(envelope-from )\n\tid 1wKJ9A-0007xm-Vs; Tue, 05 May 2026 13:01:25 -0400","from eggs.gnu.org ([2001:470:142:3::10])\n by lists1p.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)\n (Exim 4.90_1) (envelope-from )\n id 1wKJ92-0007wL-MU\n for qemu-devel@nongnu.org; Tue, 05 May 2026 13:01:18 -0400","from mail-wr1-x42b.google.com ([2a00:1450:4864:20::42b])\n by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128)\n (Exim 4.90_1) (envelope-from )\n id 1wKJ8w-0003SR-LG\n for qemu-devel@nongnu.org; Tue, 05 May 2026 13:01:15 -0400","by mail-wr1-x42b.google.com with SMTP id\n ffacd0b85a97d-44a044cb827so3897697f8f.0\n for ; Tue, 05 May 2026 10:01:09 -0700 (PDT)","from draig.lan ([185.124.0.195]) by smtp.gmail.com with ESMTPSA id\n ffacd0b85a97d-45055960fd6sm6287780f8f.31.2026.05.05.10.01.06\n (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256);\n Tue, 05 May 2026 10:01:07 -0700 (PDT)","from draig.lan (localhost [IPv6:::1])\n by draig.lan (Postfix) with ESMTP id 31DFC5FC70;\n Tue, 05 May 2026 18:01:06 +0100 (BST)"],"DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/relaxed;\n d=linaro.org; s=google; t=1778000468; x=1778605268; darn=nongnu.org;\n h=content-transfer-encoding:mime-version:references:in-reply-to\n :message-id:date:subject:cc:to:from:from:to:cc:subject:date\n :message-id:reply-to;\n bh=2qLWLCHwx9ItOitd3ZI8FQhHr7e9U0+nImoOwCxcB9Y=;\n b=D854VgzrdTcNdFjRPjtBFPewYGHeZI/wVcK1s94bl0PqQr10nXsYjm3L2g1UYdFu3p\n oCLtkrldtELrwXBLOD11osQMasqac481QUgZTFknZERSryIcOm5LT2nncmwz+nrpqYxU\n y/0WcEI975EKcj/0uNiAk7FC+gAYEo/x0CsYdAt6BGlu9LFi9g0IQcNnc1pzjJAHKmJB\n HGtDI0ehBsDH6jPRVlcgXriU9yK6I5PIr9CtlM3YcdTVMFoUPNKbXQQOMD8OsDpYPK+h\n oztBcdw5Y+MyD4wDs5nfQOzChPaKcGBKqM5JWUtwzqWT054415ezEBVWpv73hjGKkg8k\n xNGg==","X-Google-DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/relaxed;\n d=1e100.net; s=20251104; t=1778000468; x=1778605268;\n h=content-transfer-encoding:mime-version:references:in-reply-to\n :message-id:date:subject:cc:to:from:x-gm-gg:x-gm-message-state:from\n :to:cc:subject:date:message-id:reply-to;\n bh=2qLWLCHwx9ItOitd3ZI8FQhHr7e9U0+nImoOwCxcB9Y=;\n b=oB2zZC6PBJss+sUdMufGn9PP8nSOXURBD8jacTUBcaSAsa7UDGON8kPszeu/1zR74z\n cg6UDR9aH4gnRGd1ODXe2u6YT3rS5r2R2KTpT62M2i/VFks5YUYsAyPjHy/0ElLH45wD\n 3/8ctDpuE+YBt8xtAPGHcglc1lCDVR6PhKBvLP248h88umYpoxySju1ZozroIfNNEPFQ\n 2ATISnR61/TOi2zVGlzJDnp1B2fnY1WubEMOn7k9iOxg8L3Plp+jjlQvWSGs5ARvLYL2\n 6W0jhr/an+zqyDwQQjmaOzgLdoBh3oyLNwYgCQpttHKqRZFCS/z7RIcvmq9a7P2aP05A\n b49w==","X-Gm-Message-State":"AOJu0YzOv0ehw5UO/OPoPoSjSG3RBS78SF0GZ6x7IkM7MoMJ1EB9Xigt\n UqsUSp1f9vQqH8PeW3j8I3JdZyt7LEgc6JiEzwszTTOC5ggfmyW0RHu4cXegmQhEm0bYwD2jDgs\n zeqmiMa4=","X-Gm-Gg":"AeBDietxnLF2BQOdH3457YfrB+FWdKETeYUhqVFNu8KF7IEhpnK/EdTaoRnV7qT+1pU\n RtCd1a3DvG44cHJnKKdKRrgjyfX7oaIe8TpCpesfQ1jRgVeot/iuj0srq+qEjjCPXcMok277MGI\n c5QNrTXgZh9foKWAYq5NVyU86C0RgG8JvRJ5T1VDRjs56GtvyTLxNdf0JogLNgFdQXCOmKs/V3s\n 2WRDZEzkjOE5pEmXyIzVUCt7rZQv8Vyut6icZNHzR6cVHz15wVeHGN7brr66iZm+O/Obo5VUX9J\n bX3Nm0zEVzj33gNQXMeSWzjQM85g2qGw3qJoemV7/RK9acAE52dvaxkjcD1oMeq9enbcX4GqMYr\n EyUIH0RYt6Cs408T5XGRbyUuTfLGz9a5xXsbva19UeTEaHjxpK4yVenzYi0JxO0R8FGnJD0W7Uj\n j9XDylz/nD2WPT+RfyDDhx89a0Tnqa5jHVCA==","X-Received":"by 2002:a05:6000:2f83:b0:43b:8f4e:27f8 with SMTP id\n ffacd0b85a97d-44bb4817dc1mr25010341f8f.12.1778000468032;\n Tue, 05 May 2026 10:01:08 -0700 (PDT)","From":"=?utf-8?q?Alex_Benn=C3=A9e?= ","To":"qemu-devel@nongnu.org","Cc":"=?utf-8?q?Alex_Benn=C3=A9e?= ","Subject":"[RFC PATCH 02/10] .agents/skills: add qemu-code-explorer skill","Date":"Tue, 5 May 2026 18:00:57 +0100","Message-ID":"<20260505170105.228162-3-alex.bennee@linaro.org>","X-Mailer":"git-send-email 2.47.3","In-Reply-To":"<20260505170105.228162-1-alex.bennee@linaro.org>","References":"<20260505170105.228162-1-alex.bennee@linaro.org>","MIME-Version":"1.0","Content-Type":"text/plain; charset=UTF-8","Content-Transfer-Encoding":"8bit","Received-SPF":"pass client-ip=2a00:1450:4864:20::42b;\n envelope-from=alex.bennee@linaro.org; helo=mail-wr1-x42b.google.com","X-Spam_score_int":"-20","X-Spam_score":"-2.1","X-Spam_bar":"--","X-Spam_report":"(-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1,\n DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1,\n RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001,\n SPF_PASS=-0.001 autolearn=ham autolearn_force=no","X-Spam_action":"no action","X-BeenThere":"qemu-devel@nongnu.org","X-Mailman-Version":"2.1.29","Precedence":"list","List-Id":"qemu development ","List-Unsubscribe":",\n ","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n ","Errors-To":"qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org","Sender":"qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org"},"content":"This provides a skill detailing how to explore the QEMU code base. It\nguides the agents to use the tags and git-grep by default and outlines\nsome of the confusions that can occur with multiple build directories.\n\nSigned-off-by: Alex Bennée \n---\n .agents/skills/qemu-code-explorer/SKILL.md | 66 +++++++++++++++++++\n .../qemu-code-explorer/evals/evals.json | 25 +++++++\n AGENTS.md | 1 +\n 3 files changed, 92 insertions(+)\n create mode 100644 .agents/skills/qemu-code-explorer/SKILL.md\n create mode 100644 .agents/skills/qemu-code-explorer/evals/evals.json","diff":"diff --git a/.agents/skills/qemu-code-explorer/SKILL.md b/.agents/skills/qemu-code-explorer/SKILL.md\nnew file mode 100644\nindex 00000000000..d41b21179c1\n--- /dev/null\n+++ b/.agents/skills/qemu-code-explorer/SKILL.md\n@@ -0,0 +1,66 @@\n+---\n+name: qemu-code-explorer\n+description: Comprehensive guide for exploring the QEMU codebase using tagging systems (gtags, ctags, cscope), git grep, and build-directory grep for generated files. Use this skill when the user asks to find where something is defined, how it's used, or wants to understand a specific subsystem.\n+---\n+\n+# QEMU Code Base Explorer\n+\n+This skill provides a systematic approach to navigating and understanding the large and complex QEMU codebase.\n+\n+## 1. Symbol Search with Tags (Primary)\n+\n+Tagging systems are the fastest and most accurate way to find global symbol definitions and references. QEMU supports `gtags`, `ctags`, `cscope`, and `TAGS` (Emacs).\n+\n+### GNU Global (gtags) - Recommended\n+- **Best for**: Finding where a function, struct, or global variable is defined or used.\n+- **Tools**: Use `gtag_find_symbol_definition` and `gtag_find_symbol_references`.\n+- **Note**: This is significantly faster and more accurate than `grep` for symbols. It handles static variables and functions correctly.\n+\n+### Updating Tags\n+If you suspect the tags are out of date:\n+```bash\n+make gtags # or make ctags, make cscope, make TAGS\n+```\n+\n+## 2. Text Search with `git grep` (Secondary)\n+\n+`git grep` is the preferred tool for general text searches within the source tree.\n+\n+- **Best for**: \n+ - Searching for local variables within a function.\n+ - Searching for string literals or comments.\n+ - Finding occurrences of symbols defined in system headers (e.g., `optarg`).\n+ - Complex regex patterns that `gtags` doesn't support.\n+- **Why**: It is fast, respects `.gitignore`, and avoids searching through build artifacts or other non-source files.\n+- **Usage**: `git grep \"pattern\"` or use a grep-like tool with the `path` set to the repository root.\n+\n+## 3. Searching Generated Code\n+\n+Generated source files (e.g., from QAPI or trace-events) do not reside in the source tree but in the build directory.\n+\n+- **Best for**:\n+ - Finding definitions of functions generated by QAPI (e.g., `qmp_marshal_...`).\n+ - Finding trace points and their implementations (e.g., `trace_..._header`).\n+ - Checking configuration fragments (`config-*.h`).\n+- **Tools**: Use a normal `grep` (or similar search tool) limited to the build directory.\n+- **Crucial Note**: QEMU developers often have multiple build directories (e.g., `build/`, `builds/debug/`, `builds/asan/`). Always verify which build directory is active or intended.\n+- **Common Paths**:\n+ - `build/qapi/`: Generated QAPI headers and C files.\n+ - `build/trace/`: Generated trace points.\n+ - `build/config-host.h`: Host-specific configuration.\n+\n+## Decision Matrix: Which tool to use?\n+\n+| Goal | Tool | Reason |\n+|------|------|--------|\n+| Find a function definition | `gtags` | Precise and fast. |\n+| Find all call sites of a function | `gtags` | Comprehensive. |\n+| Find a local variable usage | `git grep` | `gtags` only tracks globals. |\n+| Search for a string literal | `git grep` | `gtags` doesn't index literals. |\n+| Find QAPI-generated code | `grep` in `build/` | Not in source tree. |\n+| Search in a specific subsystem | `git grep ` | Efficiently scoped. |\n+\n+## Workflow Tips\n+1. **Scope your search**: If you know you are looking for a networking issue, search `hw/net/` or `net/` first.\n+2. **Beware of Macros**: QEMU uses many macros (especially in QOM). If `gtags` fails, `git grep` might find where the macro is used to define the symbol.\n+3. **Verify the Build**: Before searching generated code, ensure a build has been performed in the target directory.\ndiff --git a/.agents/skills/qemu-code-explorer/evals/evals.json b/.agents/skills/qemu-code-explorer/evals/evals.json\nnew file mode 100644\nindex 00000000000..dff7afa52fa\n--- /dev/null\n+++ b/.agents/skills/qemu-code-explorer/evals/evals.json\n@@ -0,0 +1,25 @@\n+{\n+ \"skill_name\": \"qemu-code-explorer\",\n+ \"evals\": [\n+ {\n+ \"id\": 0,\n+ \"prompt\": \"Where is the function 'qemu_mutex_lock' defined and where is it used in the block layer (block/)?\",\n+ \"expected_output\": \"The definition should be found (likely in util/qemu-thread-posix.c or similar) and usages in block/ should be listed using gtags.\"\n+ },\n+ {\n+ \"id\": 1,\n+ \"prompt\": \"I'm seeing a reference to 'qmp_marshal_query_status' in some docs but I can't find it in the source tree. Can you find where it is defined?\",\n+ \"expected_output\": \"The agent should identify this as QAPI generated code and look in the build directory (e.g., build/qapi/qapi-commands-control.c).\"\n+ },\n+ {\n+ \"id\": 2,\n+ \"prompt\": \"Find all implementations of trace points for 'virtio_net' in the generated code.\",\n+ \"expected_output\": \"The agent should search for 'trace_virtio_net_*' in the build directory, specifically in generated trace headers/sources.\"\n+ },\n+ {\n+ \"id\": 3,\n+ \"prompt\": \"Find all occurrences of the string 'Could not open' in the 'hw/' directory.\",\n+ \"expected_output\": \"The agent should use git grep or eca__grep scoped to hw/ to find the string literals.\"\n+ }\n+ ]\n+}\ndiff --git a/AGENTS.md b/AGENTS.md\nindex 401c48da810..e4b65b06067 100644\n--- a/AGENTS.md\n+++ b/AGENTS.md\n@@ -11,6 +11,7 @@ of AI-generated content.\n - **Multiple Builds**: Developers might create a `builds` directory with different configurations in subdirs (e.g. `builds/debug`, `builds/asan`).\n - **Documentation**: Developer docs live in `docs/devel`.\n - **Plan Files**: Plan files should be placed in `.plan`, they are not included in commits. Use them to track complex multi-step tasks.\n+- **Agent Skills**: These can be found in `.agents/skills`\n \n ## Agent Skills (see `.agents/skills`)\n You should use the following specialized skills for common tasks:\n","prefixes":["RFC","02/10"]}