Re: [PATCH v5 0/6] agents: add skills for Fixes tags, stable tags, similar bugs, and commit messages

[Sasha Levin <sashal@kernel.org>]

On Thu, Nov 12, 2026 at 02:49:09PM +0100, Krzysztof Kozlowski wrote:
>On 12/11/2026 14:46, Theodore Tso wrote:
>> On Thu, Nov 12, 2026 at 09:26:09AM -0500, Krzysztof Kozlowski wrote:
>>>
>>> All these are docs (even if you call them as a skill, it's the same),
>>> therefore they should be placed in Documentation, not in top-level. We
>>> should not create one documentation for humans and another for agents.
>>> It's just one documentation.

Right. The idea here is that agent skills will mostly refer to our existing
Documentation/ and will only act as a glue layer to make agents behave better.

Consider, for example, one of the most common feedback points we have to AI
users: "make your commit message way less verbose". This is the type of things
that would make sense as an agent-only instruction.

>> Skills aren't necessarily *just* documentation.  The skills
>> specification[1] also defines a structured location in the skill's
>> directory hierarchy for Python scripts or other executables.
>
>Specification is also documentation, just like for example specification
>for our ABI. It's also located in Documentation directory.

One of the reasons to keep it out of Documentation/ was that it doesn't mesh
with the infrastructure Documentation/ uses. For example, Documentation/ is all
.rst, while the agents.md spec specifically calls out for markdown, and a very
particular construction of that file.

>Agents supposedly "are just tools", thus just as sparse, smatch and
>compilers such tools do not get another top-level directory.

I'm a bit confused by this... the original reasoning was the it doesn't really
fit into either Documentation/ , scripts/, or tools/, so we just gave it it's
own home. Why does it matter if it's a top-level dir or not?

It's something we can always move around later - agents don't care where it
lives as long as it's refered to by the main AGENTS.md, so if we later come to
the conclusion that it makes sense to move it, for example, under scripts/,
then we can easily do that.

-- 
Thanks,
Sasha