Add llms.txt URL-resolution guidance to cloudflare and cloudflare-one skills - #96
Open
lbellows wants to merge 1 commit into
Open
Add llms.txt URL-resolution guidance to cloudflare and cloudflare-one skills#96lbellows wants to merge 1 commit into
lbellows wants to merge 1 commit into
Conversation
These skills are retrieval-first, but the only retrieval entry points they name are the docs root and the cloudflare-docs MCP tool. When the MCP server is not configured, an agent that needs a page has no way to find its URL and tends to construct one by appending a guessed slug to a known parent path. Docs paths get reorganized and generally 404 rather than redirect, so the guess fails and the agent retries variations of it. developers.cloudflare.com publishes a machine-readable index at /llms.txt, plus per-product /<product>/llms.txt and llms-full.txt. Neither skill mentioned them. - cloudflare: add three rows to the Retrieval Sources table and a "Never guess a docs URL" section with the resolve procedure. - cloudflare-one: add the same fallback, scoped to that product, whose section names are especially hard to predict. Both note that appending index.md (or sending Accept: text/markdown) returns the Markdown source, and that llms-full.txt should be grepped rather than read whole. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
Both skills are explicitly retrieval-first, but the only retrieval entry points they name are the docs root and the
cloudflare-docsMCP tool. When that MCP server isn't configured — which is the common case for someone who installed the skills vianpx skills addand nothing else — an agent that needs a specific docs page has no way to find its URL.What it does instead is construct one: take a parent path it has seen in the skill, append a plausible slug, and fetch. Docs paths get reorganized and generally 404 rather than redirect, so the guess fails, and the agent burns turns retrying variations of the same guess.
A concrete instance from a real session — the agent had
cloudflare-one/access-controls/policies/from the skill, needed session settings, and fetched:The real page is under a different parent entirely:
Nothing in the skill was wrong — that URL appears in no reference file. The skill just gave the agent no way to resolve a path it didn't already have.
Why now
developers.cloudflare.comalready publishes exactly the index needed for this, and neither skill mentions it:https://developers.cloudflare.com/llms.txt— ~16KB index of every producthttps://developers.cloudflare.com/<product>/llms.txt— every page in one product, with descriptionshttps://developers.cloudflare.com/<product>/llms-full.txt— full text of a product's docsGrepping
cloudflare-one/llms.txtfindsaccess-settings/session-managementin one step.Changes
Purely additive, +20 lines, no existing content modified.
skills/cloudflare/SKILL.md— three new rows in the Retrieval Sources table, and a### Never guess a docs URLsection giving the two-step resolve procedure and stating that on a 404 the agent should go to the product'sllms.txtrather than retry variations.skills/cloudflare-one/SKILL.md— the same fallback scoped to that product, whose section names (access-controls/access-settings/,team-and-resources/,traffic-policies/) are particularly hard to predict. Uses the 404 above as the worked example.Both note the
index.md/Accept: text/markdownshortcut for fetching Markdown source, and flag thatllms-full.txtshould be grepped rather than read whole.Related
#95 fixes 8 links in
skills/cloudflare/references/that currently 404 — independent branch, no overlap. That one repairs specific instances; this one is the general fallback for when a link inevitably rots again.🤖 Generated with Claude Code