Agent Skills

llms.txt tells an agent where your pages are. An Agent Skill tells it what someone can do with your product: the capabilities, the hard facts, the footguns. Readsmith serves skills at the standard discovery paths and, unlike hosted platforms that generate them opaquely on their servers, writes the generated skill into your repository where you review it like code.

What gets served

Try it on this site:

curl https://readsmith.dev/docs/skill.md

The reply begins, as of Readsmith 0.13.0:

---
name: readsmith
description: Readsmith is a Fair Source documentation platform that builds a
  docs site (navigation, search, generated OpenAPI reference, agent outputs like
  llms.txt/MCP/skill.md) from a Markdown/MDX repo, self-hosted via Docker
  Compose with Postgres/pgvector. Use when configuring docs.yaml, authoring...

Every site serves something here from the first build: with nothing configured, a generated fallback lists the pages so the path is never empty.

Author a skill by hand

Put skills in the reserved .readsmith/skills/ directory at your content root, one directory per skill:

docs/
└── .readsmith/
    └── skills/
        └── my-product/
            └── SKILL.md

SKILL.md needs name (matching its directory) and description frontmatter; the body is yours. Authored skills always win over anything generated.

Generate one from your docs

pnpm skill:generate --dry-run
pnpm skill:generate --model anthropic/claude-sonnet-5

The generator reads your built site, extracts facts, procedures, and gotchas in a bounded map-reduce loop on your own model key, verifies every claimed link against pages that actually exist, and writes the result into .readsmith/skills/ in your repository. You read the diff, edit what you disagree with, and commit; the next build serves it.

Three behaviors keep this safe:

• It never overwrites your hand-written skill. A file without the generated marker is refused unless you pass --force.
• It never runs during a build. Builds stay deterministic; generation is an explicit command, and its cost is printed when it finishes.
• It skips when content has not changed, so re-running is free.

This site's own skill was produced exactly this way; the file in the repository carries the marker and the review history.