[PATCH v4 0/5] agents: add skills for Fixes tags, stable tags, similar bugs, and commit messages

[PATCH v4 0/5] agents: add skills for Fixes tags, stable tags, similar bugs, and commit messages

[Sasha Levin]

At the Maintainers Summit, Ted asked whether the stable trees have a way
to deal with incorrect Fixes tags. Hannes estimated that 15-20% of them
are wrong, often because the author ran git blame and took the first
commit that touched the line [1]. We use LLM workflows to find the
commit that actually introduced a bug, and others asked us to share
them.

This series adds them as agent skills under agents/skills/, together
with a skill for writing commit messages. Each skill is a short SKILL.md
that points the agent at the process documents for its task and adds
only the checks agents tend to get wrong:

 - find-fixes determines the commit for a Fixes tag, following the
   history past code moves and refactors.

 - stable-tag decides whether a fix should go to stable and generates the
   tag. It finds the first release with the bug and checks that the fix
   applies there.

 - find-siblings looks for the same bug elsewhere in the tree, with a
   Coccinelle semantic patch when Coccinelle is available, verifies each
   candidate, and reports whether the interface itself invites the bug.

 - commit-message writes, rewrites, or reviews a commit message or cover
   letter, and writes the text of a pull request. It follows the P:
   profiles for the changed files and keeps the text short and in the
   imperative voice, as Linus asked [2].

Rules that people need as much as agents go into the existing documents
instead, in two patches sent separately: one says in
submitting-patches.rst which commit a Fixes tag names [5], and the other
drops the 100 line limit, the rule against theoretical issues, and the
requirement that a fix be obviously correct from stable-kernel-rules.rst,
none of which the stable trees apply [6].

Most of the skills only point at Documentation/. The exception is
stable-tag, which also lists the kinds of changes the stable trees take
and leave out. The lists describe how the stable rules are applied, not
new rules, and they save smaller models from working that out on every
fix. To keep agents/ consistent with Documentation/, I'll check one
against the other every release and trim anything in agents/ that
duplicates or contradicts it, as Kees suggested [4].

The skills only inspect and report. The calling workflow writes the
commit, creates the tag, and sends the mail. coding-assistants.rst tells
agents when to use each skill. Tools do not load agents/skills/ on their
own; to have a tool load them automatically, link the skill directories
into its skills directory.

Changes since v3:
 - find-siblings: when the same defect turns up in several places, also
   report whether the interface invites it, and leave the choice between
   fixing the interface and fixing each site to the developer (Alexei).
 - find-siblings returns the semantic patch it used, and commit-message
   includes it in the commit message, or names it if it is under
   scripts/coccinelle/ (Julia).
 - find-fixes also returns a Fixes tag for a later commit that exposed
   the bug, to match Thorsten's rewording of the Fixes paragraph
   (Thorsten).
 - Send the submitting-patches.rst and stable-kernel-rules.rst patches
   separately [5][6].
 - Add the Reviewed-by tags given on v3.

Changes since v2:
 - Keep the skills in agents/. They are now short pointers into
   Documentation/ rather than documentation of their own; see the
   discussion on v1 [3].
 - Cut each skill to a single short SKILL.md that points at the existing
   documentation, and drop the git how-to (Kees). The skill text went
   from about 960 lines to 250.
 - find-siblings: describe how to search with Coccinelle in a separate
   file that agents read only when Coccinelle is available.
 - Say in submitting-patches.rst which commit to name when a later commit
   exposed the bug or more than one commit introduced it, and which trees
   need the fix (Michael, Thorsten, Dan).
 - Drop the 100 line limit and the exclusion of theoretical issues from
   stable-kernel-rules.rst, and require a fix to be correct rather than
   obviously correct.
 - State once, in coding-assistants.rst, that skills only inspect and
   report.

v3: https://lore.kernel.org/r/20261016152828.3765695-1-sashal@kernel.org
v2: https://lore.kernel.org/r/20261012213452.1863248-1-sashal@kernel.org
v1: https://lore.kernel.org/r/cover.1791499378.git.sashal@kernel.org
[1] https://lore.kernel.org/r/askTmFZC6RJKAE_p@mit.edu
[2] https://lore.kernel.org/r/CAHk-=wgXU50=KgZNZc1JDxsSxg9Z+DjG1_2yU-fNXpZtUe4XDw@mail.gmail.com
[3] https://lore.kernel.org/r/87y0bzq8oe.fsf@trenco.lwn.net
[4] https://lore.kernel.org/r/202610150832.58E80C02A@keescook
[5] https://lore.kernel.org/r/20261020142534.3533478-1-sashal@kernel.org
[6] https://lore.kernel.org/r/20261020142537.3533510-1-sashal@kernel.org

Sasha Levin (5):
  agents: add infrastructure for agent resources
  agents: add a skill to determine Fixes tags
  agents: add a skill to determine stable tags
  agents: add a skill to find other instances of a fixed bug
  agents: add a skill to write commit messages

 Documentation/process/coding-assistants.rst   | 35 +++++++--
 MAINTAINERS                                   |  6 ++
 agents/skills/commit-message/SKILL.md         | 45 ++++++++++++
 agents/skills/find-fixes/SKILL.md             | 39 ++++++++++
 agents/skills/find-siblings/SKILL.md          | 36 ++++++++++
 .../find-siblings/references/coccinelle.md    | 66 +++++++++++++++++
 agents/skills/stable-tag/SKILL.md             | 72 +++++++++++++++++++
 7 files changed, 295 insertions(+), 4 deletions(-)
 create mode 100644 agents/skills/commit-message/SKILL.md
 create mode 100644 agents/skills/find-fixes/SKILL.md
 create mode 100644 agents/skills/find-siblings/SKILL.md
 create mode 100644 agents/skills/find-siblings/references/coccinelle.md
 create mode 100644 agents/skills/stable-tag/SKILL.md


base-commit: 3857c2fe5449541e24afc5efdb0f81a8a8f9a3a0
-- 
2.53.0

[PATCH v4 1/5] agents: add infrastructure for agent resources

[Sasha Levin]

Add agents/ as a home for skills and other resources for
coding assistants. Describe the skill layout in coding-assistants.rst,
together with the rule that skills only inspect and report, and add a
MAINTAINERS entry covering the directory.

Assisted-by: LLM
Signed-off-by: Sasha Levin <sashal@kernel.org>
Reviewed-by: Bradley Morgan <brads@mainlining.org>
---
 Documentation/process/coding-assistants.rst | 14 ++++++++++++++
 MAINTAINERS                                 |  6 ++++++
 2 files changed, 20 insertions(+)

diff --git a/Documentation/process/coding-assistants.rst b/Documentation/process/coding-assistants.rst
index 051f0d819f68e..1efc7b08f09f8 100644
--- a/Documentation/process/coding-assistants.rst
+++ b/Documentation/process/coding-assistants.rst
@@ -19,6 +19,20 @@ For guidelines on content generated by AI coding assistants see:
 
 * Documentation/process/generated-content.rst
 
+Agent resources
+===============
+
+Skills for coding assistants live under ``agents/skills/``, one directory per
+skill with a ``SKILL.md`` entry point in the `Agent Skills format
+<https://agentskills.io/specification>`_. Each skill points at the process
+documents that apply to its task and adds only what assistants tend to get
+wrong.
+
+Skills inspect and report. They do not change files, create commits or tags,
+or send mail. A skill returns its result with the evidence for it, or says what
+is missing. Do not fill a missing result with a guess or a placeholder, and do
+not finalize the work until it is resolved.
+
 Licensing and Legal Requirements
 ================================
 
diff --git a/MAINTAINERS b/MAINTAINERS
index f53047aa8d3c1..9e522cda56f1b 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -713,6 +713,12 @@ F:	Documentation/filesystems/afs.rst
 F:	fs/afs/
 F:	include/trace/events/afs.h
 
+AGENT RESOURCES
+M:	Sasha Levin <sashal@kernel.org>
+L:	workflows@vger.kernel.org
+S:	Maintained
+F:	agents/
+
 AGPGART DRIVER
 M:	David Airlie <airlied@redhat.com>
 L:	dri-devel@lists.freedesktop.org
-- 
2.53.0

[PATCH v4 2/5] agents: add a skill to determine Fixes tags

[Sasha Levin]

Blame and existing Fixes tags can point to code movement instead of the
change that introduced a bug. Add a skill that sends the agent to the
description of the Fixes: tag in submitting-patches.rst, and adds the
checks agents tend to skip: pinning down the bug before searching,
following the code past moves and refactors, comparing each candidate
with its parent, tagging a later commit that only exposed the bug as
well, handling merges, reverts, backports and bugs older than the Git
history, and taking the commit ID and subject from the commit rather
than typing them.

If the origin cannot be established, the skill returns no tag. Point the
bug-fix procedure in coding-assistants.rst at the skill.

Assisted-by: LLM
Signed-off-by: Sasha Levin <sashal@kernel.org>
---
 Documentation/process/coding-assistants.rst |  9 +++--
 agents/skills/find-fixes/SKILL.md           | 39 +++++++++++++++++++++
 2 files changed, 46 insertions(+), 2 deletions(-)
 create mode 100644 agents/skills/find-fixes/SKILL.md

diff --git a/Documentation/process/coding-assistants.rst b/Documentation/process/coding-assistants.rst
index 1efc7b08f09f8..ddff951856dce 100644
--- a/Documentation/process/coding-assistants.rst
+++ b/Documentation/process/coding-assistants.rst
@@ -33,6 +33,11 @@ or send mail. A skill returns its result with the evidence for it, or says what
 is missing. Do not fill a missing result with a guess or a placeholder, and do
 not finalize the work until it is resolved.
 
+The following skills are available:
+
+* agents/skills/find-fixes/SKILL.md determines the Fixes tag of a bug fix, or
+  checks an existing one.
+
 Licensing and Legal Requirements
 ================================
 
@@ -96,8 +101,8 @@ these steps:
    another one. The fix must not add build warnings and must pass the
    checkpatch.pl checks (see submitting-patches.rst).
 6. Commit the working fix with a detailed message describing the problem, the
-   solution and a Fixes tag. Do not add a Signed-off-by tag, and add an
-   Assisted-by tag, as described above.
+   solution and a Fixes tag determined with the find-fixes skill. Do not add a
+   Signed-off-by tag, and add an Assisted-by tag, as described above.
 7. Identify the maintainers and lists using scripts/get_maintainer.pl.
    Documentation/process/security-bugs.rst shows how to do that.
 8. Indicate what could not be done. If the fix could not be built or tested, or
diff --git a/agents/skills/find-fixes/SKILL.md b/agents/skills/find-fixes/SKILL.md
new file mode 100644
index 0000000000000..12b6ea83876d9
--- /dev/null
+++ b/agents/skills/find-fixes/SKILL.md
@@ -0,0 +1,39 @@
+---
+# SPDX-License-Identifier: GPL-2.0-only
+name: find-fixes
+description: >-
+  Determine the bug-introducing commit and return a verified Fixes tag for
+  a Linux kernel fix. Use when preparing or reviewing bug-fix patches,
+  drafting their commit messages, or checking an existing Fixes tag.
+---
+
+# Determine a Fixes tag
+
+Read the description of the Fixes: tag in
+Documentation/process/submitting-patches.rst. It says which commit to name
+and how to format the tag. Follow the rules for skills in
+Documentation/process/coding-assistants.rst.
+
+- First establish exactly which bug the fix addresses: the failure, how it is
+  triggered and the code involved. Trace only that bug. If the search leads
+  to a different bug or subsystem, go back to the fix.
+- Name a commit from the history of the tree the fix applies to. A stable
+  backport of that commit, or a commit that exists only on another branch, is
+  not a valid tag.
+- Treat blame output, an existing Fixes tag and a bisection result as leads,
+  not answers. Follow the code back through moves, renames, file splits and
+  older implementations to the commit that made it wrong.
+- For each candidate, compare the commit with its parent and explain why the
+  code was correct before and wrong after. Keep apart the commit that added
+  the code, the commit that made it wrong, and a later commit that only made
+  the bug reachable, which gets a tag of its own.
+- Check each parent of a merge, whether the bug was reverted and later
+  reintroduced, and whether a backport differs from its upstream commit.
+- If the bug is already present in the first commit of the Git history, name
+  that commit: Fixes: 1da177e4c3f4 ("Linux-2.6.12-rc2"). Confirm that the bug
+  exists there instead of using it as a default. A shallow clone boundary is
+  not an introducing commit; report the limit instead.
+
+Take the commit ID and subject from the commit itself instead of typing them.
+Return the tags with that explanation and the candidates you rejected. If the
+origin cannot be established, return no tag and say what is missing.
-- 
2.53.0

[PATCH v4 3/5] agents: add a skill to determine stable tags

[Sasha Levin]

Whether a fix needs a stable tag, and which releases it should reach, is
decided by hand and is often missed or left too broad. Add a skill that
sends the agent to stable-kernel-rules.rst for the decision and the tag
format, lists the kinds of changes the stable trees take and leave out
in practice, and adds the checks agents tend to get wrong: finding the
first release that contains each introducing commit, checking that the
fix applies to the oldest affected release, giving every stable tag the
same version, and following the subsystem's stable policy.

If the decision cannot be made, the skill returns no tag. Point the
bug-fix procedure in coding-assistants.rst at the skill.

Assisted-by: LLM
Signed-off-by: Sasha Levin <sashal@kernel.org>
Reviewed-by: Bradley Morgan <brads@mainlining.org>
---
 Documentation/process/coding-assistants.rst |  7 +-
 agents/skills/stable-tag/SKILL.md           | 72 +++++++++++++++++++++
 2 files changed, 77 insertions(+), 2 deletions(-)
 create mode 100644 agents/skills/stable-tag/SKILL.md

diff --git a/Documentation/process/coding-assistants.rst b/Documentation/process/coding-assistants.rst
index ddff951856dce..fc4e98fd96e11 100644
--- a/Documentation/process/coding-assistants.rst
+++ b/Documentation/process/coding-assistants.rst
@@ -37,6 +37,8 @@ The following skills are available:
 
 * agents/skills/find-fixes/SKILL.md determines the Fixes tag of a bug fix, or
   checks an existing one.
+* agents/skills/stable-tag/SKILL.md decides whether a fix goes to stable and
+  returns its stable tag, or checks an existing one.
 
 Licensing and Legal Requirements
 ================================
@@ -101,8 +103,9 @@ these steps:
    another one. The fix must not add build warnings and must pass the
    checkpatch.pl checks (see submitting-patches.rst).
 6. Commit the working fix with a detailed message describing the problem, the
-   solution and a Fixes tag determined with the find-fixes skill. Do not add a
-   Signed-off-by tag, and add an Assisted-by tag, as described above.
+   solution, a Fixes tag determined with the find-fixes skill, and a stable tag
+   if the stable-tag skill calls for one. Do not add a Signed-off-by tag, and
+   add an Assisted-by tag, as described above.
 7. Identify the maintainers and lists using scripts/get_maintainer.pl.
    Documentation/process/security-bugs.rst shows how to do that.
 8. Indicate what could not be done. If the fix could not be built or tested, or
diff --git a/agents/skills/stable-tag/SKILL.md b/agents/skills/stable-tag/SKILL.md
new file mode 100644
index 0000000000000..d87bcc95089d3
--- /dev/null
+++ b/agents/skills/stable-tag/SKILL.md
@@ -0,0 +1,72 @@
+---
+# SPDX-License-Identifier: GPL-2.0-only
+name: stable-tag
+description: >-
+  Decide whether a Linux kernel fix should be backported to stable kernels
+  and return verified Cc: stable tag lines. Use when preparing or reviewing
+  bug-fix patches, drafting their commit messages, or checking an existing
+  stable tag.
+---
+
+# Determine a stable tag
+
+Read Documentation/process/stable-kernel-rules.rst. It says which changes go
+to stable and how to write the tag, its prerequisites and its version. Follow
+the rules for skills in Documentation/process/coding-assistants.rst.
+
+Judge a change by what it does, not by how its description labels it: a
+"cleanup" that releases a resource on an error path fixes a leak. In practice,
+the stable trees take:
+
+- Fixes for crashes, oopses, BUG and WARN splats, hangs, lockups, RCU stalls,
+  deadlocks, data corruption and security issues.
+- Fixes for use-after-free, double free, NULL pointer dereferences,
+  out-of-bounds accesses, integer overflows, uninitialized data, reference
+  counting errors, and memory or resource leaks.
+- Fixes for races, including data races.
+- Fixes for incorrect behavior, such as wrong results, wrong hardware
+  programming, or endianness and type errors.
+- Fixes for problems reported by syzbot, other fuzzers, or the KASAN, KMSAN,
+  KCSAN and UBSAN sanitizers.
+- New device IDs and quirks for drivers that exist in the stable trees, device
+  tree fixes, and device tree additions for hardware that existing drivers
+  support.
+- Corrections to documentation that is wrong.
+- Performance fixes that prevent lockups, stalls or hangs.
+- Reverts of commits that are in a released kernel.
+- Fixes for bugs introduced by commits that were backported to stable.
+
+They do not take the following, unless a fix that is taken depends on it:
+
+- New features, new user-visible interfaces or behavior, new drivers, and new
+  module parameters or sysfs attributes.
+- Refactoring, code movement and other preparation patches.
+- Optimizations that do not prevent lockups, stalls or hangs.
+- Cleanups that do not change behavior, such as style, renames and comment
+  changes.
+
+Then work out which releases need the fix:
+
+- Determine the Fixes tags with the find-fixes skill first. A change with no
+  introducing commit, such as a new device ID, a quirk or a build fix, or a
+  bug older than the available history, affects every release that contains
+  the code it changes. Otherwise, if the Fixes tags are unresolved, so is the
+  stable decision.
+- For each Fixes tag, find the first release that contains the commit, not the
+  release it was based on. If no release contains it, check whether the
+  commit was itself backported to stable.
+- Check that everything the fix uses exists in the oldest affected release.
+  If something is missing, list the commit that added it as a prerequisite
+  if it is small and fit for stable, or start the tag at the first release
+  that has it.
+- Give every stable tag in a commit the same version: a tag without a version
+  asks for every stable tree and overrides the versions in the other tags.
+  The stable tooling reads the first version number in a tag comment as the
+  version, so describe what older trees need in the commit message.
+- Follow the stable tag policy in the maintainer profiles, the `P:` entries in
+  MAINTAINERS, for the changed files.
+- Ask the caller whether the fix addresses an unpublished vulnerability, as
+  described in Documentation/process/threat-model.rst.
+
+Return the tag lines with the reasons for them, or the reasons for no tag. If
+the decision cannot be made, return no tag and say what is missing.
-- 
2.53.0

[PATCH v4 4/5] agents: add a skill to find other instances of a fixed bug

[Sasha Levin]

A bug fixed in one place often exists elsewhere, in copied code, sibling
drivers, or other users of the same interface, and reviewers routinely
ask whether that was checked. Left alone, agents tend to audit the whole
tree by reading it. Add a skill that states the defect as a rule,
searches for it through shared interfaces, copied code, the introducing
series and earlier fixes, and verifies each candidate before reporting
it.

When Coccinelle is available, the skill searches with a semantic patch:
it looks for an existing one under scripts/coccinelle/, checks that the
rule marks the fixed site in the code before the fix, runs it over the
whole tree with coccicheck, and checks which code spatch could not
parse. These steps live in references/coccinelle.md, which the agent
reads only when it uses Coccinelle. The semantic patch is returned with
the results, so that the commit message of a fix can include it.

Tested on the parent of commit 989fe6771266 ("drm/nouveau/gsp: fix
mismatched alloc/free for kvmalloc()"): both the existing
api/kfree_mismatch.cocci and the example rule mark the two kfree() calls
that commit fixed, and a whole-tree run found the same bug in four other
drivers that were later fixed separately.

The sites found are reported, not fixed. When the same defect turns up
in several places, the skill also reports whether the interface invites
it. The missing of_node_put() calls that iterators/for_each_child.cocci
finds were fixed one driver at a time for years, until
commit 34af4554fb0c ("of: Introduce for_each_*_child_of_node_scoped() to
automate of_node_put() handling") made the put automatic. Whether to fix
the interface or each site is left to the developer.

Point the bug-fix procedure in coding-assistants.rst at the skill.

Link: https://lore.kernel.org/r/DM6DXZJSMPO3.J5PONDJ3HWNP@gmail.com
Assisted-by: LLM
Signed-off-by: Sasha Levin <sashal@kernel.org>
---
 Documentation/process/coding-assistants.rst   |  5 +-
 agents/skills/find-siblings/SKILL.md          | 36 ++++++++++
 .../find-siblings/references/coccinelle.md    | 66 +++++++++++++++++++
 3 files changed, 106 insertions(+), 1 deletion(-)
 create mode 100644 agents/skills/find-siblings/SKILL.md
 create mode 100644 agents/skills/find-siblings/references/coccinelle.md

diff --git a/Documentation/process/coding-assistants.rst b/Documentation/process/coding-assistants.rst
index fc4e98fd96e11..a89a33980c41f 100644
--- a/Documentation/process/coding-assistants.rst
+++ b/Documentation/process/coding-assistants.rst
@@ -39,6 +39,8 @@ The following skills are available:
   checks an existing one.
 * agents/skills/stable-tag/SKILL.md decides whether a fix goes to stable and
   returns its stable tag, or checks an existing one.
+* agents/skills/find-siblings/SKILL.md looks for the same bug elsewhere in the
+  tree.
 
 Licensing and Legal Requirements
 ================================
@@ -101,7 +103,8 @@ these steps:
 5. Build and verify that the fix works either using the reproducer or by
    re-running a complete analysis; drop any fix that doesn't work and try
    another one. The fix must not add build warnings and must pass the
-   checkpatch.pl checks (see submitting-patches.rst).
+   checkpatch.pl checks (see submitting-patches.rst). Then look for the same
+   bug elsewhere with the find-siblings skill.
 6. Commit the working fix with a detailed message describing the problem, the
    solution, a Fixes tag determined with the find-fixes skill, and a stable tag
    if the stable-tag skill calls for one. Do not add a Signed-off-by tag, and
diff --git a/agents/skills/find-siblings/SKILL.md b/agents/skills/find-siblings/SKILL.md
new file mode 100644
index 0000000000000..8d007472675d9
--- /dev/null
+++ b/agents/skills/find-siblings/SKILL.md
@@ -0,0 +1,36 @@
+---
+# SPDX-License-Identifier: GPL-2.0-only
+name: find-siblings
+description: >-
+  Find other places in the Linux kernel tree that have the same defect as a
+  bug being fixed, and verify each candidate. Use after fixing or reviewing
+  a bug fix, or when asked whether the same bug exists elsewhere.
+---
+
+# Find other instances of a bug
+
+Follow the rules for skills in Documentation/process/coding-assistants.rst.
+
+- State the defect as a rule that does not depend on local names, such as
+  "memory from kvmalloc() is released with kfree()".
+- Search the tree as it was before the fix, not the working tree. Look at
+  other users of the same interface, field or lock, code copied from the same
+  origin, the rest of the series that introduced the bug, and earlier fixes
+  for the same defect. Limit history searches to the relevant directories.
+- If Coccinelle is available (`spatch --version` works), search for the
+  defect with a semantic patch as
+  [references/coccinelle.md](references/coccinelle.md) describes. Otherwise
+  use text searches and report that limit.
+- A match is a lead. Read each candidate with its callers, locking and object
+  lifetimes, and classify it as confirmed, safe or undetermined, with the
+  reason. Check whether a confirmed site is already fixed in the current tree
+  or in a pending tree such as linux-next.
+- If several sites have the same defect, check whether the interface they use
+  invites it, for example by making every caller drop a reference by hand when
+  it leaves a loop early. If it does, report that the defect is better fixed
+  in the interface, along with the sites. The developer decides which way to
+  fix it.
+
+Return the searches you ran and their scope, with any semantic patch you
+used, and the classified sites with their maintainers. Do not fix the sites or
+the interface.
diff --git a/agents/skills/find-siblings/references/coccinelle.md b/agents/skills/find-siblings/references/coccinelle.md
new file mode 100644
index 0000000000000..6b09ce9d04c8c
--- /dev/null
+++ b/agents/skills/find-siblings/references/coccinelle.md
@@ -0,0 +1,66 @@
+<!-- SPDX-License-Identifier: GPL-2.0-only -->
+
+# Searching for a bug pattern with Coccinelle
+
+Documentation/dev-tools/coccinelle.rst describes `make coccicheck` and its
+options. The semantic patch language is documented at
+https://coccinelle.gitlabpages.inria.fr/website/docs/.
+
+1. Look under `scripts/coccinelle/` for a semantic patch that already covers
+   the defect. Read its rules rather than its name: `kfree()` of memory from
+   `kvmalloc()` is covered by `api/kfree_mismatch.cocci`, while
+   `api/kvmalloc.cocci` only flags an open-coded `is_vmalloc_addr()` test.
+
+2. Otherwise, write a semantic patch outside the repository. Match only what
+   the defect needs, not names or statements specific to the fixed site. Mark
+   the lines of interest with `*`, and declare `virtual context`: coccicheck
+   passes `-D context`, and spatch rejects a mode the file does not declare.
+   A minimal rule for memory from `kvmalloc()` released with `kfree()`, a
+   case that `api/kfree_mismatch.cocci` covers more completely:
+
+       virtual context
+
+       @@
+       expression E;
+       @@
+       E = \(kvmalloc\|kvzalloc\|kvcalloc\|kvmalloc_array\)(...);
+       ...
+       * kfree(E);
+
+3. Check that it finds the site you fixed. Coccinelle reads the files on
+   disk, where the fix is usually already applied, so copy the file as it was
+   before the fix to a directory outside the repository and run
+   `spatch -D <mode> --very-quiet --sp-file <rule> <copy>`, with a mode the
+   rule declares on a `virtual` line, such as `context` or `report`. Without
+   `-D`, rules that depend on a mode do not run and nothing is reported. The
+   rule must mark the fixed site in that copy, and nothing in the fixed
+   version. If it misses the site, correct the rule before searching further.
+
+4. Search the whole tree:
+
+       make coccicheck MODE=context COCCI=<rule> DEBUG_FILE=<new log file>
+
+   - Use a `MODE` the rule declares on a `virtual` line, as in step 3.
+   - In context mode the output is a diff, and each line starting with `-`
+     is a line the rule marked; report mode prints one warning per site.
+     coccicheck searches the files on disk, so a site you already fixed
+     there is not marked; step 3 covers it.
+   - The kernel's `.cocciconfig` makes spatch skip files that do not contain
+     the rule's identifiers, so a whole-tree search is usually quick when the
+     rule names distinctive functions. Add `M=<dir>/` only if it is not.
+   - Give `COCCI` and `DEBUG_FILE` as absolute paths. With `M=`, coccicheck
+     runs from that directory.
+   - Read the log. Without `DEBUG_FILE`, spatch errors are discarded and a
+     broken rule shows only as "coccicheck failed". coccicheck refuses to
+     reuse an existing log file.
+   - Header files are searched only with `SPFLAGS=--include-headers`, or with
+     a `// Options: --include-headers` line at the top of the rule.
+
+5. Check what was not searched. Coccinelle skips code it cannot parse without
+   saying so. Run `spatch --parse-c` on the searched files or directories: a
+   nonzero `nb bad` count means part of them was skipped. Search those files
+   another way and report the gap.
+
+If the rule marks many sites that turn out to be safe, tighten it, for example
+with `when !=` constraints, and run it again rather than discarding candidates
+by hand.
-- 
2.53.0

[PATCH v4 5/5] agents: add a skill to write commit messages

[Sasha Levin]

Assistants are asked to commit a fix with a detailed message, and the
find-fixes and stable-tag skills leave their tags for that message, but
nothing says how to write it. Messages written by assistants tend to be
long, and Linus recently asked that pull request text written with an
LLM be less verbose and prefer the imperative voice.

Add a skill that sends the agent to the parts of submitting-patches.rst,
5.Posting.rst and the maintainer documentation that cover commit
messages, cover letters and pull requests, and to the P: profiles of the
changed files. It adds what agents get wrong: stating only what the
change and the supplied sources support, keeping the text short and in
the imperative mood, and adding no tags that were not supplied.

When a semantic patch found the bug, the message includes it, or its path
when it is under scripts/coccinelle/, so that reviewers and the
Coccinelle developers can see it and run it again.

Point the bug-fix procedure in coding-assistants.rst at the skill.

Link: https://lore.kernel.org/r/CAHk-=wgXU50=KgZNZc1JDxsSxg9Z+DjG1_2yU-fNXpZtUe4XDw@mail.gmail.com
Link: https://lore.kernel.org/r/50531bd9-f3ea-2d45-7b3a-a96a446a8fcc@inria.fr
Assisted-by: LLM
Signed-off-by: Sasha Levin <sashal@kernel.org>
---
 Documentation/process/coding-assistants.rst | 10 +++--
 agents/skills/commit-message/SKILL.md       | 45 +++++++++++++++++++++
 2 files changed, 51 insertions(+), 4 deletions(-)
 create mode 100644 agents/skills/commit-message/SKILL.md

diff --git a/Documentation/process/coding-assistants.rst b/Documentation/process/coding-assistants.rst
index a89a33980c41f..9cae53cc5d8b9 100644
--- a/Documentation/process/coding-assistants.rst
+++ b/Documentation/process/coding-assistants.rst
@@ -41,6 +41,8 @@ The following skills are available:
   returns its stable tag, or checks an existing one.
 * agents/skills/find-siblings/SKILL.md looks for the same bug elsewhere in the
   tree.
+* agents/skills/commit-message/SKILL.md writes, rewrites or reviews a commit
+  message or cover letter, and writes the text of a pull request.
 
 Licensing and Legal Requirements
 ================================
@@ -105,10 +107,10 @@ these steps:
    another one. The fix must not add build warnings and must pass the
    checkpatch.pl checks (see submitting-patches.rst). Then look for the same
    bug elsewhere with the find-siblings skill.
-6. Commit the working fix with a detailed message describing the problem, the
-   solution, a Fixes tag determined with the find-fixes skill, and a stable tag
-   if the stable-tag skill calls for one. Do not add a Signed-off-by tag, and
-   add an Assisted-by tag, as described above.
+6. Commit the working fix with a message written with the commit-message skill,
+   describing the problem, the solution, a Fixes tag determined with the
+   find-fixes skill, and a stable tag if the stable-tag skill calls for one. Do
+   not add a Signed-off-by tag, and add an Assisted-by tag, as described above.
 7. Identify the maintainers and lists using scripts/get_maintainer.pl.
    Documentation/process/security-bugs.rst shows how to do that.
 8. Indicate what could not be done. If the fix could not be built or tested, or
diff --git a/agents/skills/commit-message/SKILL.md b/agents/skills/commit-message/SKILL.md
new file mode 100644
index 0000000000000..c75f028c56da9
--- /dev/null
+++ b/agents/skills/commit-message/SKILL.md
@@ -0,0 +1,45 @@
+---
+# SPDX-License-Identifier: GPL-2.0-only
+name: commit-message
+description: >-
+  Write, rewrite or review the commit message for a Linux kernel change or
+  the cover letter for a patch series, and write the signed tag and pull
+  request text for a subsystem pull. Use when committing or preparing
+  patches, when asked to improve or check a commit message, or when
+  preparing a pull request for an upstream maintainer.
+---
+
+# Write a commit message
+
+Read "Describe your changes", the sections on tags, "The canonical patch
+format" and "Commentary" in Documentation/process/submitting-patches.rst, and
+Documentation/process/5.Posting.rst for cover letters. Follow the maintainer
+profiles, the `P:` entries in MAINTAINERS, for the changed files; they take
+precedence. Follow the rules for skills and for attribution in
+Documentation/process/coding-assistants.rst, and
+Documentation/process/generated-content.rst when a tool found the problem.
+When editing someone else's message, also follow
+Documentation/maintainer/modifying-patches.rst.
+
+- State only what the diff and the sources you were given support, such as a
+  bug report, a crash log, test results, or the list discussion found with
+  `lei q` on lore.kernel.org. If the reason for the change is not known,
+  return no message and say what is missing.
+- Take the Fixes and stable tags from the find-fixes and stable-tag skills.
+  Add other tags only when they were supplied or given on the list. Never add
+  a Signed-off-by.
+- If a semantic patch found the bug, include it in the message between
+  `// <smpl>` and `// </smpl>` lines. For one under scripts/coccinelle/, give
+  its path instead.
+- Use the imperative mood and keep the message as short as its content
+  allows. Leave out markdown, labels such as "Root cause:", intensifiers, a
+  restatement of the subject, and the story of the investigation.
+- Check the result with `scripts/checkpatch.pl --no-signoff`.
+
+For the signed tag and email of a pull request, follow
+Documentation/maintainer/pull-requests.rst,
+Documentation/maintainer/rebasing-and-merging.rst and
+Documentation/maintainer/messy-diffstat.rst. Summarize what the pull contains
+and why from the commit messages in the range, in the same voice, without
+repeating the shortlog. Ask the caller for conflict resolutions and testing
+that the history does not show.
-- 
2.53.0