---
name: llms-txt-design
description: "Concevoir la structure d'un llms.txt pour n'importe quel produit, en suivant les principes de design extraits d'Anthropic — agnostique de stack, de langue et de type de site. Utiliser quand vous devez créer, structurer ou refondre un fichier llms.txt / llms-full.txt pour un site ou un produit, afin d'améliorer sa discoverability par les LLMs et agents IA."
allowed-tools:
  - Bash
  - Read
  - Write
  - Edit
  - WebFetch
  - AskUserQuestion
---

# llms-txt Design — Principes Agnostiques (source : Anthropic)

Tu es un architecte de `llms.txt`. Ta mission : étant donné un produit/site, concevoir la **structure optimale** de ses fichiers `llms.txt` (index) et `llms-full.txt` (contenu complet) en appliquant les principes de design d'Anthropic — le gold standard observé sur `https://platform.claude.com/llms.txt`.

Parse `$ARGUMENTS` :
- Premier argument = **URL ou description du produit** (ex : `https://example.com`, `"SaaS de gestion RH pour PME"`). Dans les templates ci-dessous, `{url}` désigne le domaine **sans schéma** (ex : `example.com`)
- `--output PATH` → écrire le fichier résultant dans ce chemin (sinon afficher uniquement)
- `--full` → produire aussi le template `llms-full.txt`, pas seulement l'index
- Pas d'args → AskUserQuestion : "Quel produit ou URL voulez-vous structurer ?" (accepter une URL de production, un chemin local vers le projet, ou une description libre ; si un projet local est ouvert, tenter l'auto-détection via `package.json`, `.git` ou les fichiers du site)

---

## STEP 0 : Collecter les faits sur le produit

### 0a. Si URL fournie

```bash
curl -s https://{url}/sitemap.xml | grep '<loc>' | sed 's|.*<loc>||;s|</loc>.*||' | sort
curl -s -o /dev/null -w "%{http_code}" https://{url}/llms.txt   # existe déjà ?
```

Si le site n'a pas de sitemap : WebFetch de la page d'accueil et suivre les liens de la navigation principale pour reconstituer l'inventaire des pages.

Extraire :
- Nombre et types de pages (blog, landing, produit, légal, docs, comparatifs, villes…)
- Langue(s) du site
- Profondeur de l'arborescence

### 0b. Si description texte fournie

Inférer mentalement le type de contenu probable. Poser via AskUserQuestion si nécessaire :

1. **Type de produit** : SaaS / docs techniques / site agence / e-commerce / contenu/blog / autre
2. **Pages principales** : lister les sections connues (pricing, about, contact, docs, blog, features…)
3. **Multilingue ?** : si oui, quelles langues, même contenu ou contenu propre par langue

---

## STEP 1 : Choisir l'architecture de sections (H2 → H3)

### Principe Anthropic n°1 — Grouper par workflow utilisateur, pas par type de fichier

❌ Mauvais (alphabétique / technique) :
```
## API
## Blog
## Contact
## Docs
## Legal
## Pricing
```

✅ Bon (fonctionnel / rôle utilisateur) :
```
## Démarrer          ← onboarding / get-started
## Fonctionnalités   ← le cœur du produit
## Intégrations      ← connecteurs, API, webhooks
## Tarifs & Offres   ← décision commerciale
## Administration    ← gestion compte, sécurité
## Blog & Ressources ← contenu long
```

### Règle de mapping par type de produit

| Type de produit | Sections H2 recommandées |
|----------------|--------------------------|
| **SaaS B2B** | Démarrer · Fonctionnalités clés · Intégrations · Tarifs · Administration · Ressources |
| **Docs techniques** | Introduction · Guides · Référence API · Exemples · Changelog |
| **Site agence** | Services · Réalisations · Équipe · Processus · Contact |
| **Contenu/blog** | Thèmes principaux (ex : SEO · Analytics · Product) · À propos · Contact |
| **Landing multi-villes** | Accueil · Offre · Villes couvertes · Tarifs · Blog |
| **Multilingue** | Section H2 par langue, H3 = clusters fonctionnels identiques |

### Règle de profondeur

- **< 20 pages** → H2 seulement, pas de H3
- **20–100 pages** → H2 sections + H3 clusters
- **> 100 pages** → H2 sections + H3 clusters + troncature explicite pour les sections massives

---

## STEP 2 : Construire le bloc métadonnées (toujours en tête)

### Principe Anthropic n°2 — Déclarer la couverture avant le contenu

Chaque `llms.txt` doit ouvrir avec un bloc de métadonnées qui répond à :
- Qu'est-ce que ce fichier ?
- Quelle est l'URL racine ?
- Qu'est-ce qui est inclus dans ce fichier vs ce qui nécessite de visiter le site ?

Template :

```markdown
# {Nom du Produit} — Documentation

Ce fichier fournit une vue d'ensemble du contenu de {nom_produit} pour les LLMs, agents IA et outils de développement.

## URL racine

{https://example.com}

## Contenu couvert

{Description en 1-2 phrases de ce que ce fichier indexe. Ex : "Les pages publiques du site en français. Le blog complet est inclus ci-dessous."}

---
```

### Si multilingue (modèle Anthropic) :

```markdown
## Langues disponibles

- Français (fr) — {N} pages — contenu inclus ci-dessous
- English (en) — {N} pages — visiter {url}/en pour le contenu
- Deutsch (de) — {N} pages — visiter {url}/de pour le contenu
```

**Règle** : inclure le contenu d'une seule langue dans `llms.txt`. Les autres langues : pointer vers le site.

---

## STEP 3 : Formater chaque lien (H3 bullets)

### Principe Anthropic n°3 — Liens vers .md, pas HTML

Format préféré quand une version `.md` existe (docs, contenu structuré) :
```markdown
- [Titre de la page](https://example.com/docs/page.md) - Descripteur court
```

Format standard (site HTML) :
```markdown
- [Titre de la page](https://example.com/page) - Descripteur court
```

### Règle du descripteur

- **Titre non ambigu** → pas de descripteur : `- [Pricing](url)`
- **Titre ambigu** ("Overview", "Guide", "Quickstart") → descripteur obligatoire : `- [Overview](url) - MCP tunnels`
- **Descripteur = 1 ligne max** — jamais de phrase longue

### Format complet d'une section

```markdown
### {Cluster fonctionnel}

- [Titre page A](url) - Descripteur si nécessaire
- [Titre page B](url)
- [Titre page C](url) - Descripteur
```

---

## STEP 4 : Gérer les sections massives (troncature explicite)

### Principe Anthropic n°4 — Jamais d'omission silencieuse

Si une section contient > 30 pages (ex : référence API avec des dizaines d'endpoints, blog avec 100+ articles) :

✅ Troncature explicite :
```markdown
### Référence API

[Cette section contient {N} endpoints couvrant : opérations CRUD sur les ressources X, Y, Z ; authentification ; webhooks ; pagination. Voir {url}/api-reference pour la liste complète.]
```

ou, pour un blog massif :
```markdown
### Blog

{N} articles sur les thèmes : {thème 1}, {thème 2}, {thème 3}.
Les 10 articles les plus récents sont listés ci-dessous ; [voir tous les articles](https://{url}/blog).

- [Titre article récent 1](url)
- [Titre article récent 2](url)
- ...
```

❌ Ne jamais omettre une section entière sans signal :
```markdown
# [Section manquante = le LLM ne sait pas qu'elle existe]
```

---

## STEP 5 : Produire le squelette `llms.txt`

Assembler les steps 1–4 dans ce template :

```markdown
# {Nom Produit} — {Courte accroche}

{Description 1-2 phrases : à quoi sert ce fichier, à qui}

## URL racine

{URL prod principale}

## Contenu couvert

{Scope en 1-2 phrases}

---

## {Section H2 #1 — ex : Démarrer}

### {Cluster H3 — ex : Premiers pas}

- [Titre](url) - Descripteur
- [Titre](url)

### {Cluster H3 — ex : Installation}

- [Titre](url) - Descripteur

---

## {Section H2 #2 — ex : Fonctionnalités}

### {Cluster H3}

- [Titre](url)

[Si section massive : [Description en prose de ce qui est couvert mais non listé]]

---

## {Section H2 #3 — ex : Tarifs}

- [Tarifs](url) - Plans et prix
- [FAQ](url) - Questions fréquentes

---

## {Section H2 #4 — ex : Ressources}

### Blog

- [{Titre article 1}](url) - Description
- [{Titre article 2}](url) - Description

### Légal & Support

- [Mentions légales](url)
- [Contact](url)
- [CGU](url)
```

---

## STEP 6 : Template `llms-full.txt` (si `--full`)

### Principe Anthropic n°5 — llms-full.txt = dump complet, format machine

Structure par page, délimitée par `---` :

```markdown
# {Nom Produit} — Contenu complet

> {Tagline}

Ce fichier contient le contenu intégral des pages publiques de {url} en Markdown.
Destiné aux LLMs et agents IA souhaitant accéder au contenu du site sous forme compacte.

## URL racine

https://{url}

## Sommaire

- [{Titre page A}](#anchor-a)
- [{Titre page B}](#anchor-b)
...

---

# {Titre Page A}

URL: https://{url}/{path-a}

*{Meta description de la page}*

## {Section de la page}

{Contenu intégral en Markdown}

---

# {Titre Page B}

URL: https://{url}/{path-b}

*{Meta description}*

{Contenu...}

---
```

**Règles strictes pour llms-full.txt** :
- Contenu **verbatim** — ne jamais paraphraser, surtout pricing et engagements commerciaux
- Pas de HTML, pas de JSX — Markdown pur
- Meta description en italique sur sa propre ligne après URL
- Une section `---` entre chaque page
- Sommaire cliquable en tête avec ancres

---

## STEP 7 : Checklist de validation

Avant de produire le fichier final, vérifier :

| Critère | ✅ / ❌ |
|---------|--------|
| H1 = nom produit (pas générique) | |
| URL racine déclarée en tête | |
| Coverage scope décrit | |
| Sections H2 = workflows, pas types de fichiers | |
| Titres ambigus ont un descripteur | |
| Sections massives tronquées **avec signal explicite** | |
| Zéro prose marketing dans la structure | |
| Liens fonctionnels (pas de 404 anticipés) | |
| `llms.txt` < 10 KB | |
| Tous les accents corrects (si contenu FR) | |

---

## STEP 8 : Livrable

### Mode `--output PATH`

Écrire le fichier à l'emplacement indiqué. Afficher ensuite :
- Nombre de sections H2
- Nombre de liens
- Taille estimée en KB
- Les sections qui ont une troncature explicite (signal d'alerte)

### Mode affichage (défaut)

Afficher le fichier généré dans la conversation + un commentaire par section sur les choix de design effectués.

Proposer ensuite :
1. Ajuster les sections H2 (renommer, regrouper, réordonner)
2. Ajouter des sections manquantes
3. Écrire dans un fichier (`--output`)
4. Passer à la génération du contenu complet : remplir le squelette avec le contenu réel des pages (fetch page par page, conversion en Markdown)

---

## RÉFÉRENCE : Principes Anthropic en résumé

| # | Principe | Application |
|---|----------|-------------|
| 1 | **Grouper par workflow utilisateur, pas par type de fichier** | Grouper par rôle/cas d'usage, pas par type de fichier |
| 2 | **Déclarer la couverture avant le contenu** | Root URL + scope + langues avant tout contenu |
| 3 | **Liens vers .md, pas HTML** | Pointer vers versions machine-readable quand elles existent |
| 4 | **Jamais d'omission silencieuse** | `[Cette section contient N pages...]` — troncature explicite |
| 5 | **llms-full.txt = dump complet, format machine** | `llms.txt` = index ≤ 10 KB ; `llms-full.txt` = dump complet |
| 6 | **Titre ambigu → descripteur** | `[Overview](url) - MCP tunnels` pas juste `[Overview](url)` |
| 7 | **Zéro prose marketing** | Navigation pure, pas de copy "notre produit est fantastique" |
| 8 | **Signal "inclus / visit website"** | "Content included below" vs "Visit website for content" |

Les principes 6-8 sont complémentaires (non détaillés ci-dessus).

**Source observée** : `https://platform.claude.com/llms.txt` (2026-06-08)