# RFC: Publishing Agent Skills through `llms.txt` - **Status:** Draft (v0.2) - **Date:** 2026-04-21 - **Author:** automators.work - **Depends on:** [llmstxt.org](https://llmstxt.org/) spec, [Agent Skills](https://agentskills.io) (`SKILL.md`) - **Reference implementation:** [img.automators.work](https://img.automators.work) --- ## 1. Problem ### 1.1 The gap between two ecosystems `llms.txt` lets a domain tell LLMs what it *is* and where its content lives. Agent Skills (`SKILL.md`) let a user install reusable *capabilities* into their local agent. Both exist. Neither talks to the other. The result: a site can describe itself in `llms.txt`, and it can publish a `SKILL.md` somewhere, but there is no standardized way for the site to say *"here is the skill you need to work with me"* — and no standardized way for an agent to discover it. ### 1.2 The infrastructure barrier of existing alternatives The current agent-surface primitives (MCP, A2A) require running server infrastructure: a persistent process, a transport layer, an endpoint. This is appropriate for complex, stateful integrations. It is overkill for the large majority of sites on the web, which are: - **Static sites** (Cloudflare Pages, GitHub Pages, Netlify, Vercel) — no server process exists - **Existing APIs** that want to teach agents how to call them, not reimplement their surface - **Documentation sites** that want to describe their interaction patterns once, not maintain a daemon The reference implementation for this RFC (`img.automators.work`) is a Cloudflare Pages static site. It cannot run an MCP server. It *can* serve a text file. ### 1.3 The convention-based discovery problem An emerging convention (`/.well-known/skills/default/skill.md`, proposed by Cloudflare and adopted by Mintlify) lets agents find a skill by trying a known path. This works when: - The agent knows the domain in advance - The agent is configured to probe `.well-known` paths It does not work when: - The site wants to declare *multiple* skills for different use cases - The agent encounters the site for the first time via `llms.txt` - The site wants to co-locate skill discovery with the rest of its agent-facing context **Co-location matters.** An agent that reads `llms.txt` to understand a site already has the right document open. If skill discovery requires a separate probe, that is extra latency and a second source of truth. --- ## 2. Proposal Add an optional `## Skills` section to `llms.txt`. Each entry is a link to a remote `SKILL.md` (or a skill bundle archive) that conforms to the Agent Skills spec. ### 2.1 Syntax ```markdown ## Skills - [skill-name](https://example.com/skills/skill-name/SKILL.md): description of when to use this skill. - [bundle-name](https://example.com/skills/bundle-name.zip): description. ``` Rules: 1. The section heading MUST be exactly `## Skills` (case-insensitive). 2. Each list item MUST follow the standard `llms.txt` link convention: `- [title](URL): description`. 3. The URL MUST resolve to either: - A raw `SKILL.md` document (`Content-Type: text/markdown`), OR - An archive ending in `.zip` or `.tar.gz` containing `SKILL.md` at the archive root 4. The remote `SKILL.md` MUST be a valid Agent Skill (YAML frontmatter + body per the Agent Skills spec) 5. The URL SHOULD be same-origin as the `llms.txt`. Cross-origin URLs are permitted but carry additional security implications (see §4) 6. The description SHOULD match or summarize the `description` field in the skill's frontmatter ### 2.2 Optional inline metadata A skill entry MAY carry a trailing HTML comment with a JSON object for richer discovery: ```markdown - [pay-with-x402](/skills/x402/SKILL.md): make x402 payments. ``` Recognized keys: `version`, `sha256`, `requires`, `license`, `homepage`. Agents that do not understand the comment MUST ignore it. ### 2.3 Discovery flow ``` 1. Agent encounters a domain (via user instruction, URL in context, or search result) 2. Agent fetches https://example.com/llms.txt 3. Agent parses the ## Skills section 4. Agent surfaces available skills to the user 5. User opts in to one or more skills 6. Agent fetches the SKILL.md, verifies sha256 if declared, loads it 7. Agent caches the skill per HTTP cache semantics of the SKILL.md response ``` Step 5 is mandatory. Agents MUST NOT auto-install or auto-activate skills without explicit user approval (see §4). ### 2.4 Two primary use cases This mechanism is intentionally broad enough to cover two distinct patterns: **Pattern A — API wrapping.** The site has a public HTTP API. The skill teaches the agent how to authenticate and which endpoints to call. The agent executes calls directly against the API. Example: a placeholder image service, a payment API, a search API. **Pattern B — Interaction instructions.** The site has no dedicated API but wants to describe how agents should interact with it: what paths to fetch, what patterns to parse, what to avoid. The agent uses its own capabilities (HTTP fetch, browser) guided by the skill. Example: a documentation site, a blog, a product catalog. Both patterns require only static file hosting. Neither requires a running server process. --- ## 3. Relationship to existing standards | Standard | What it solves | What it doesn't solve | |---|---|---| | `llms.txt` | Content discovery for LLMs | Capability/skill discovery | | `/.well-known/skills/default/skill.md` | Single-skill convention-based discovery | Multi-skill, declarative discovery | | MCP / A2A | Rich, stateful agent-service integration | Static sites; low-friction publishing | | Skills marketplaces (skills.sh, SkillsMP) | Curated skill distribution | Site-native, self-hosted publishing | | **This RFC** | Declarative, multi-skill, web-native discovery from `llms.txt` | Skill *execution* (left to agent runtime) | This proposal is **complementary** to all of the above. A site can serve `/.well-known/skills/default/skill.md` *and* list it in `## Skills` — the two discovery mechanisms are not mutually exclusive. --- ## 4. Security considerations Remote skill loading is a prompt-injection surface. A compromised `llms.txt` or skill URL can instruct an agent to exfiltrate data, call attacker-controlled services, or deceive the user. ### Required mitigations for conforming implementations 1. **Explicit user opt-in per origin.** Agents MUST NOT auto-install or auto-activate skills. The user must approve each origin at least once. Presenting available skills is permitted; loading them is not. 2. **No implicit execution.** Listing a skill in `llms.txt` MUST NOT cause it to be invoked. Approval and invocation are separate steps. 3. **Content-Type enforcement.** Agents MUST reject skill URLs that return `text/html`, `application/javascript`, or any non-markdown, non-archive MIME type. 4. **Integrity verification.** If `sha256` is declared in the inline metadata, agents MUST verify the hash of the fetched file and refuse to load on mismatch. 5. **Cross-origin skills require elevated confirmation.** If a skill URL is on a different origin from the `llms.txt` that references it, agents SHOULD require additional user confirmation beyond the base opt-in. This prevents a compromised `llms.txt` from silently delegating trust to a third-party host. 6. **Least privilege.** Skills loaded from a domain operate within the permission scope of that domain. They cannot request filesystem access, network calls to unrelated origins, or other capabilities not stated in the skill's frontmatter without explicit user re-confirmation. --- ## 5. On agent-side discovery triggers This RFC defines the *publishing* side of the protocol. It does not mandate when or how agents decide to read `llms.txt`. Today, most agents read `llms.txt` only when the user explicitly directs them to a URL or instructs them to research a site. Proactive, background skill discovery does not yet occur in mainstream runtimes. This is not a defect of the proposal — it is the current state of the ecosystem. MCP, A2A, and `/.well-known/skills/` face the same trigger problem: all require the user or agent to know the site exists before discovery begins. **What this RFC adds, even today:** when an agent does encounter a site — via user instruction, a URL in context, or a tool result — a `## Skills` section gives it an unambiguous, machine-readable signal that purpose-built skills are available. That is more than any site can currently express through `llms.txt` alone. As agent runtimes evolve toward more proactive web discovery, the `## Skills` section provides the declaration primitive those systems will need. --- ## 6. Why this is worth doing - **Deployable on any static host.** A Cloudflare Pages site, a GitHub Pages repo, a Netlify deploy — any host that can serve a text file can publish skills through this mechanism. No server process required. - **Self-describing at the source.** A site ships its API *and* the skill for consuming it in the same deploy. No third-party marketplace required. - **Version-locked to the API.** When the API changes, the skill changes in the same commit. No drift between capability and documentation. - **Co-located discovery.** An agent reading `llms.txt` finds skills in the same document, in one fetch, with no additional probing. - **Multi-skill support.** A single domain can publish skills for different use cases (e.g., read-only queries, authenticated writes, admin operations) as separate entries. - **No gatekeeper.** Publishing a skill is a `git push`. No approval process, no marketplace submission. --- ## 7. Non-goals - Replacing local skill filesystems or marketplaces — both remain valid distribution modes - Defining a new skill format — this RFC reuses the Agent Skills `SKILL.md` spec as-is - Mandating skill *execution* behavior — that is the agent runtime's responsibility - Replacing MCP or A2A for complex, stateful integrations — this RFC targets the simpler, static-hosting case --- ## 8. Open questions 1. **Should `llms.txt` grow parallel `## MCP` and `## Agents` sections**, making it the single discovery document for a domain's full agent surface? Or should each standard manage its own discovery separately? 2. **Cross-origin skill trust model.** Should cross-origin skills be disallowed entirely, allowed with elevated confirmation, or allowed freely? Current proposal: allowed with elevated confirmation (§4.5). 3. **Archive format.** Should `.zip` be the only mandated archive format, or should `.tar.gz` remain in scope? `.zip` is more universally supported; `.tar.gz` is more natural for git-hosted skill bundles. 4. **Signature scheme beyond `sha256`.** Is content hashing sufficient, or is a signing scheme (sigstore, Web Bot Auth) necessary for high-trust deployments? 5. **Relationship to `/.well-known/skills/`.** Should this RFC explicitly recommend that sites serve both — a `## Skills` section in `llms.txt` *and* the `.well-known` convention — for maximum compatibility? --- ## 9. Reference implementation [`img.automators.work`](https://img.automators.work) is a live Cloudflare Pages static site — no server process, no MCP server, no A2A endpoint. - [`/llms.txt`](https://img.automators.work/llms.txt) — contains a `## Skills` section - [`/skills/placeholder/SKILL.md`](https://img.automators.work/skills/placeholder/SKILL.md) — the skill itself - [`/docs/rfc-skills-in-llms-txt.md`](https://img.automators.work/docs/rfc-skills-in-llms-txt.md) — this document --- ## 10. Changelog - **v0.2 (2026-04-21):** Added §3 ecosystem comparison; expanded §4 with cross-origin security rule; added §5 on discovery triggers; added §1.2 infrastructure barrier argument; refined two use-case patterns in §2.4; updated open questions. - **v0.1 (2026-04-20):** Initial draft.