llms.txt support

[toolmantim]

I've been trying to get Claude (via Amp) to help automate and iterate on Buildkite pipelines… and it's painful. It has some understanding of Buildkite, but it's incomplete.

It'd be useful if the Buildkite docs were more LLM friendly — at the moment agents such as Amp have to scrape the HTML of the page in order to try to understand Buildkite’s APIs, Pipeline YAML syntax, etc.

Adding better llms.txt support would help people trying to use agents, e.g. asking an AI agent to fetch a particular docs page and not burn through $$ of poor quality tokens, vs high quality markdown equivalent. It would also help the foundation models train themselves with a better understanding of Buildkite, and how to help users with Buildkite related workflows.

Bits UI seems to be a great example to follow https://bits-ui.com/docs/llms

[karensawrey]

Hey, @toolmantim! Thanks a million for pointing this out. We'll look into how we can implement this in the docs. The example you've provided is great, really appreciate it.

For the time being, I personally am getting better results with (reasonably pre-prompted) ChatGPT 4.5 vs Claude 3.7 for creating/automating pipelines for particular Buildkite use cases so I might suggest that for personal use.

Thanks for creating the issue!

[toolmantim]

Thanks! 👋🏼 I don't have the option of using ChatGPT 4.5 with Amp, but good to know!

[gilesgas]

Hi @toolmantim , we've recently implemented a feature (as part of the following commits):

• 3f0ebf3 (feature)
• 4b9ab39 (test)

that now allows the Buildkite Docs to be surfaced in Markdown format.

Hence, you can visit a page like:

• https://buildkite.com/docs/pipelines/getting-started

to view its HTML output, but also obtain its Markdown equivalent by appending .md to the end of the page name:

• https://buildkite.com/docs/pipelines/getting-started.md

I'm hoping that this type of feature is something that might help with what you're looking for?

[toolmantim]

Thank you!

I think you're going to want an LLMs page like bits-ui and some visible UI, to make this discoverable to both users and base models tho.

Otherwise it's just a hidden feature that won't really move the needle.

The models have a fantastic understand of GitHub Actions, but sadly in my testing the Buildkite knowledge is too limited atm to the useful.

[sj26]

Yeah I think this is still an issue. We need an /llms.txt tying it all together. Ideally an /llms-full.txt, too.

[sj26]

This needs to work:

https://context7.com/context7/buildkite

[toolmantim]

Related: https://docs.freestyle.sh/blog/docs-revamp

[tomcwatts]

Hey @toolmantim we've added a Copy page menu to better surface AI-friendly stuff, which is now live on all docs pages:

How does that feel to you? Anything else you'd like to see in here? Definitely agree we still need an /llms.txt

[catkins]

@toolmantim 👀 https://buildkite.com/docs/llms.txt

I landed the initial llms.txt just now. It still needs a bit of finessing, and its not really linked from anywhere just yet but that will follow.

[toolmantim]

Amazing @tomcwatts & @catkins! I think that general LLMs landing page for crawlers (linking it from somewhere like @catkins mentioned) is probably all that's left.