Proposal: `## Skills` section — extend llms.txt from content discovery to capability discovery

## Summary

`llms.txt` today describes what a site **is** and where its content lives. This proposal adds an optional `## Skills` section that lets a site declare what an agent can **do** with it — specifically, links to `SKILL.md` files (per the [[Agent Skills spec](https://agentskills.io/)](https://agentskills.io)) that an agent can load to interact with the site's API or content.

Live reference implementation: **[[img.automators.work](https://img.automators.work/)](https://img.automators.work)** — a Cloudflare Pages static site.
Full RFC: **[[img.automators.work/docs/rfc-skills-in-llms-txt.md](https://img.automators.work/docs/rfc-skills-in-llms-txt.md)](https://img.automators.work/docs/rfc-skills-in-llms-txt.md)**

---

## The gap

`llms.txt` solves the *reading* problem: it helps an LLM find and understand a site's content. But it says nothing about *acting* — how an agent should call a site's API, what endpoints to use, how to authenticate, or how to navigate the site programmatically.

Today a site that wants to publish this kind of capability knowledge has two options:

1. Hope the agent reads `llms.txt` and re-derives the interaction pattern each session (fragile, no caching, no canonical source)
2. Submit to a skills marketplace like skills.sh (requires a third party, no self-hosting)

There is no web-native, self-hosted way for a site to say: *"here is the pre-built playbook for working with me."*

---

## Proposal

Add an optional `## Skills` section to `llms.txt`, following the same link-list convention already used for file sections:

```markdown
# My Project

> Brief description of the project.

## Docs

- [API Reference](https://example.com/docs/api.md): Full API documentation.

## Skills

- [api-client](https://example.com/skills/api-client/SKILL.md): Use when calling this API from an agent.
- [site-search](https://example.com/skills/site-search/SKILL.md): Use when searching or navigating this site.
```

**Format rules** (consistent with existing llms.txt conventions):

1. Section heading MUST be `## Skills` (case-insensitive)
2. Each entry follows the standard llms.txt link convention: `- [title](URL): description`
3. URL MUST resolve to a valid `SKILL.md` (`Content-Type: text/markdown`) or a `.zip`/`.tar.gz` archive containing `SKILL.md` at the archive root
4. The `SKILL.md` format is defined by [[agentskills.io](https://agentskills.io/)](https://agentskills.io) — this proposal does not introduce a new format
5. URL SHOULD be same-origin; cross-origin is permitted with elevated agent-side confirmation
6. An optional trailing HTML comment MAY carry metadata: ``

**Discovery flow:**

```
1. Agent encounters domain (via user instruction or URL in context)
2. Agent fetches /llms.txt
3. Agent parses ## Skills section, surfaces available skills to user
4. User explicitly opts in — no auto-install
5. Agent fetches SKILL.md, verifies sha256 if declared, loads it
6. Agent caches per HTTP cache semantics
```

---

## Why this fits naturally in llms.txt

The existing spec already uses `## Section` headings to organize different types of resources (Docs, Examples, Optional). `## Skills` is the same pattern applied to a new resource type: executable agent capabilities rather than readable documents.

Concretely: when an agent fetches `llms.txt` to understand a site, it already has the right document open. Finding skills in the same document costs zero extra fetches. A separate convention (like `/.well-known/skills/`) requires an additional probe and produces a second source of truth.

---

## Why this matters for static sites

The reference implementation (`img.automators.work`) runs on **Cloudflare Pages** — no server, no process, no MCP endpoint possible. The only way to make it agent-capable is through static files. `llms.txt` + `## Skills` is exactly that: two text files, zero infrastructure.

This is the case for the vast majority of sites on the web: GitHub Pages, Netlify, Vercel static deploys, documentation sites. They cannot run MCP servers but they can serve a text file.

---

## Relationship to existing work

This proposal is **additive** — it does not change the existing spec, only adds an optional section. Sites that don't have skills simply omit the section. Parsers that don't understand `## Skills` treat it like any other H2 section and ignore it gracefully.

It is also **complementary** to the `/.well-known/skills/default/skill.md` convention (Cloudflare/Mintlify): a site can serve both. The `## Skills` section adds declarative, multi-skill, co-located discovery on top of convention-based single-skill discovery.

---

## Open questions for this community

1. Does `## Skills` fit the spirit of llms.txt, or should capability discovery live in a separate file entirely?
2. Should the spec recommend that `## Skills` entries follow the same "optional" semantics as the existing `## Optional` section — i.e., agents can skip them for shorter context?
3. Is there appetite to cross-reference this with the `agentskills/agentskills` repo, where a parallel discussion is open? ([[agentskills/agentskills#329](https://github.com/agentskills/agentskills/discussions/329)](https://github.com/agentskills/agentskills/discussions/329))

Start by reading the existing llms.txt section conventions and the linked RFC at img.automators.work/docs/rfc-skills-in-llms-txt.md, then compare the proposal with the Agent Skills specification. Done means the community has decided whether ## Skills belongs in the spec and, if so, agreed on its format and semantics.

Written by the indexing model from the issue text.