docs: publish llms.txt and llms-full.txt for AI agents

.github/workflows/docs.yml

@@ -44,8 +44,10 @@ jobs:
           if [[ "$GITHUB_REF" == refs/tags/v* ]]; then
             # v1.4.2 is the version 1.4, the latest release
             version="${GITHUB_REF_NAME#v}"
+            export LLMSTXT_BASE_URL="https://insei.github.io/tinyconf/${version%.*}/"
             mike deploy --push --update-aliases "${version%.*}" latest
           elif mike list | grep -v '^dev' | grep -q .; then
+            export LLMSTXT_BASE_URL="https://insei.github.io/tinyconf/dev/"
             mike deploy --push dev
           else
             # latest is dev until the first release with the versions of the documentation
@@ -58,6 +60,8 @@ jobs:
           # mike builds the version into the site directory, the published site is checked out to another one
           git fetch origin gh-pages --depth=1
           git worktree add pages origin/gh-pages
+          # llms.txt of the latest version is also at the root of the site, where the agents look for it first
+          cp -L pages/latest/llms.txt pages/latest/llms-full.txt pages/ 2>/dev/null || true
       - uses: actions/upload-pages-artifact@v3
         with:
           path: pages

Readme.md

@@ -7,6 +7,8 @@ tinyconf - a simple and universal library for parsing configs.
 
 Documentation: [insei.github.io/tinyconf](https://insei.github.io/tinyconf/) — get started, [why tinyconf](https://insei.github.io/tinyconf/latest/why-tinyconf/), [use cases](https://insei.github.io/tinyconf/latest/use-cases/), features and drivers.
 
+For AI agents: the [skill](skills/tinyconf/SKILL.md) with the current API, and the documentation as one file, [llms-full.txt](https://insei.github.io/tinyconf/latest/llms-full.txt).
+
 # Installation
 Install via go get. Note that Go 1.19 or newer is required.
 ```sh

docs/ai-agents.md

@@ -0,0 +1,28 @@
+# For AI agents
+
+AI agents often write the code that uses a library, and a model trained before tinyconf v2 does not know its API: it writes `Parse(conf)` without the context or imports `github.com/insei/tinyconf` without `/v2`. Give the agent the current documentation.
+
+## The skill
+
+[`skills/tinyconf/SKILL.md`](https://github.com/Insei/tinyconf/blob/main/skills/tinyconf/SKILL.md) is a short guide for agents in the [Agent Skills](https://agentskills.io) format: the rules, complete programs, the drivers with their options and the common mistakes. It is versioned with the code, and CI builds its programs against the code of the repository, so it does not describe the API that does not exist.
+
+Claude Code finds the skill in the `.claude/skills` directory of the project or of the user:
+
+```sh
+mkdir -p .claude/skills/tinyconf
+curl -fsSL https://raw.githubusercontent.com/Insei/tinyconf/main/skills/tinyconf/SKILL.md \
+  -o .claude/skills/tinyconf/SKILL.md
+```
+
+Replace `main` with the release tag, `v2.1.0` for example, to get the skill of the version in your `go.mod`. Other agents read it from any path: mention it in `AGENTS.md` or in the instructions of the agent.
+
+The skill describes the library, not your project. Keep the rules of your project — which drivers you use, where the configs live, how they are registered — in your own instructions next to it.
+
+## llms.txt
+
+The documentation is published in the [llms.txt](https://llmstxt.org) format for every version:
+
+- [`llms.txt`](https://insei.github.io/tinyconf/latest/llms.txt) — the index of the pages with descriptions;
+- [`llms-full.txt`](https://insei.github.io/tinyconf/latest/llms-full.txt) — the whole documentation as one Markdown file, to put into the context of the agent.
+
+Replace `latest` with the version, `2.1` for example, or with `dev` for the documentation of the `main` branch.

docs/requirements.txt

@@ -1,3 +1,4 @@
 mkdocs-material>=9.5,<10
 pymdown-extensions>=10.7,<11
 mike>=2.1,<3
+mkdocs-llmstxt>=0.5,<0.6

mkdocs.yml

@@ -74,6 +74,7 @@ nav:
   - Why tinyconf?: why-tinyconf.md
   - Use cases: use-cases.md
   - Upgrading to v2: upgrading.md
+  - For AI agents: ai-agents.md
   - Features:
       - features/index.md
       - Manager: features/manager.md
@@ -100,3 +101,27 @@ nav:
       - etcd: drivers/etcd.md
       - Custom formats: drivers/format.md
       - Custom drivers: drivers/custom.md
+
+plugins:
+  - search
+  # llms.txt and llms-full.txt for AI agents: https://llmstxt.org
+  - llmstxt:
+      full_output: llms-full.txt
+      # the links point to the pages of the deployed version, it is set by the docs workflow
+      base_url: !ENV [LLMSTXT_BASE_URL, "https://insei.github.io/tinyconf/latest/"]
+      markdown_description: >-
+        tinyconf fills Go config structs from a chain of drivers by struct tags: defaults, YAML, JSON, TOML, INI,
+        properties, environment variables, flags, Consul, Vault and etcd. The next driver overrides the previous one.
+        Packages parse and subscribe to their own parts of the config, reloads create new versions of the config.
+        The module path is github.com/insei/tinyconf/v2.
+      sections:
+        Start:
+          - index.md: installation and the first config
+          - why-tinyconf.md: for whom and for what, comparison with viper, koanf, cleanenv
+          - use-cases.md: recipes
+          - upgrading.md: upgrading from v1
+          - ai-agents.md: the skill for AI agents and llms.txt
+        Features:
+          - features/*.md
+        Drivers:
+          - drivers/*.md