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

[Krzysztof Kozlowski <krzk@kernel.org>]

On 12/11/2026 15:12, Sasha Levin wrote:
> 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.

I am not objecting to have the instructions for agents. They should be
however placed in Documentation.
> 
>>> 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.

Documentation already has YAML files for Devicetree and other ABI, thus
difference of format does not matter. It's just minor technical aspect -
tweak the Makefile.

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

Oh, it can go to tools/, I don't mind.

> own home. Why does it matter if it's a top-level dir or not?

Because we do not need one more top-level directory for something which
is already categorized. We do not create another top-level for
"drivers-embedded" or "drivers-acpi". We do not have "tools" and
"tools-ai". Neither "Documentation" and
"Documentation-for-ai-but-we-will-call-it-agents".


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

So place it deeper please.

Best regards,
Krzysztof