On Thu, Oct 15, 2026 at 07:57:35AM -0600, Jonathan Corbet wrote:
Miguel Ojeda <[email protected]> writes:
On Thu, Oct 15, 2026 at 3:42 PM Sasha Levin <[email protected]> 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
