Re: [PATCH 0/2] agents: add portable agent skills and Fixes attribution

[Sasha Levin <sashal@kernel.org>]

On Thu, Oct 15, 2026 at 07:57:35AM -0600, Jonathan Corbet wrote:
>Miguel Ojeda <miguel.ojeda.sandonis@gmail.com> writes:
>
>> On Thu, Oct 15, 2026 at 3:42 PM Sasha Levin <sashal@kernel.org> wrote:
>>>
>>> Sorry, what I meant to say is that the spec seems to require markdown as it's
>>> preferred format. We can experiment with other options, but then the risk is
>>> that we'll break some tools.
>>
>> Ah, got it, thanks! Yeah, at the very least the `SKILL.md` main file
>> should most likely be all Markdown inside (and of course the
>> filename).
>>
>> Now, if we go with `agents/` instead of `Documentation/`, then I would
>> personally prefer Markdown for the other files in the same folder like
>> the `guide.rst`, but that is just my bias, and it has a small
>> disadvantage: if we happen to move things between `Doc/` and
>> `agents/`, then it is a bit painful to reformat.
>
>For all that we hear about how smart these tools are, are they really
>incapable of dealing with two only slightly different markup formats?  I
>would really hate to bring in a separate format for this stuff...

Tools like codex or claude handle different markup formats well and do the
right thing here.

My concern is more around folks who use "simpler" tools, smaller open source
models, and are on a token budget. I'm not sure how they'll handle cases where
we don't follow the spec.

I'll send the v3 later today, which does a better job at having very little
information in the SKILL.md files themselves, and just points to our existing
documentation. Would it make sense to keep it in the agents/ dir rather than
mixing it with Documentation?

-- 
Thanks,
Sasha