feat(layer): add agent skills discovery via .well-known

docs/content/en/1.getting-started/3.installation.md

@@ -52,17 +52,21 @@ Head over the [Edition](/en/concepts/edition) section to learn how to write your
 Get started quickly with Docus by adding specialized knowledge to your AI assistant (Cursor, Claude, etc.):
 
 ```bash [Terminal]
-npx skills add nuxt-content/docus
+npx skills add https://docus.dev
 ```
 
 This skill helps you create documentation faster by providing your AI assistant with:
-- 📝 Best practices for writing documentation with Docus
-- 🎨 MDC component usage and ready-to-use templates
-- 📚 Writing guidelines and content structure patterns
-- 🔧 Configuration and customization tips
+- Best practices for writing documentation with Docus
+- MDC component usage and ready-to-use templates
+- Writing guidelines and content structure patterns
+- Configuration and customization tips
 
 Once installed, your AI assistant can help you scaffold new documentation projects, generate pages with proper structure, and write content following Docus best practices.
 
+::tip{to="/en/ai/skills"}
+You can also publish your own skills from your Docus site. Learn more about Agent Skills.
+::
+
 ## Layer Integration
 
 Docus v4 uses a **Nuxt layer-based approach**, you can extend the Docus layer directly in your `nuxt.config.ts` with `extends: ['docus']`:

docs/content/en/4.ai/3.skills.md

@@ -0,0 +1,189 @@
+---
+title: Agent Skills
+description: Publish agent skills from your documentation site so AI tools can discover and install them automatically.
+navigation:
+  icon: i-lucide-wand-sparkles
+---
+
+## About Agent Skills
+
+Docus automatically discovers skills in your `skills/` directory and serves them at `/.well-known/skills/`, following the [Cloudflare Agent Skills Discovery RFC](https://github.com/cloudflare/agent-skills-discovery-rfc). This makes your skills installable from any documentation URL with a single command.
+
+[Agent Skills](https://agentskills.io/) are a lightweight, open format for giving AI agents specialized knowledge and workflows. A skill is a `SKILL.md` file with YAML frontmatter that describes what agents can do with your product, along with optional supporting reference files.
+
+::note{to="https://docus.dev/.well-known/skills/index.json"}
+See the skills published on this documentation site.
+::
+
+## Quick Start
+
+::steps
+### Create a skill
+
+Add a `skills/` directory at the root of your Docus project with a skill subdirectory containing a `SKILL.md` file:
+
+```bash
+my-docs/
+└── skills/
+    └── my-product/
+        └── SKILL.md
+```
+
+### Write your SKILL.md
+
+Follow the [agentskills.io specification](https://agentskills.io/specification). The only required frontmatter field is `description` — `name` defaults to the directory name if omitted:
+
+```md [skills/my-product/SKILL.md]
+---
+name: my-product
+description: Build and deploy apps with My Product. Use when creating projects, configuring settings, or troubleshooting issues.
+---
+
+# My Product
+
+## Getting Started
+
+Create a new project:
+
+\`\`\`bash
+npx create-my-product my-app
+\`\`\`
+```
+
+### Deploy
+
+Deploy your documentation. Docus automatically serves your skills at `/.well-known/skills/`.
+
+### Share with users
+
+Users can install your skills with a single command:
+
+```bash
+npx skills add https://your-docs-domain.com
+```
+
+The CLI detects installed agents (Claude Code, Cursor, Windsurf, and others) and installs the skill to all of them.
+::
+
+## Directory Structure
+
+A skill directory can contain supporting files beyond `SKILL.md`:
+
+```bash
+skills/
+└── my-product/
+    ├── SKILL.md              # Required: instructions + metadata
+    ├── references/           # Optional: additional documentation
+    │   ├── api.md
+    │   └── configuration.md
+    ├── scripts/              # Optional: executable code
+    │   └── setup.sh
+    └── assets/               # Optional: templates, schemas
+        └── config.template.yaml
+```
+
+All files are automatically listed in the `index.json` catalog and served at their respective paths under `/.well-known/skills/{skill-name}/`.
+
+::tip
+Keep your main `SKILL.md` under 500 lines. Move detailed reference material to separate files in `references/` — agents load these on demand, so smaller files mean less context usage.
+::
+
+## Skill Name Requirements
+
+Skill names must follow the [Agent Skills naming specification](https://agentskills.io/specification#name-field):
+
+- 1-64 characters
+- Lowercase letters, numbers, and hyphens only (`a-z`, `0-9`, `-`)
+- Must not start or end with a hyphen
+- Must not contain consecutive hyphens (`--`)
+- The `name` field in frontmatter must match the parent directory name
+
+::note
+Skills that fail validation are skipped — check your build output for warnings.
+::
+
+## Multiple Skills
+
+You can publish multiple skills from a single documentation site:
+
+```bash
+skills/
+├── my-product/
+│   └── SKILL.md
+├── create-project/
+│   ├── SKILL.md
+│   └── references/
+│       └── templates.md
+└── migration-guide/
+    └── SKILL.md
+```
+
+All skills appear in the `index.json` catalog and are independently installable.
+
+## Preview and Versioning
+
+Since skills live in your repository alongside your documentation, they benefit from your existing Git workflow:
+
+- **Branch previews**: Test skill changes on preview deployments before merging. On Vercel, every pull request gets a preview URL where you can verify your skills work correctly:
+
+```bash
+npx skills add https://my-docs-git-feat-new-skill.vercel.app
+```
+
+- **Version control**: Track skill changes with Git history, review diffs in pull requests, and roll back if needed.
+- **CI/CD**: Skills are built and deployed automatically with your documentation — no separate publishing step.
+
+::tip
+Use preview URLs to test skills with your AI tools before shipping to production. This ensures your skill instructions work correctly with real agents.
+::
+
+## How Discovery Works
+
+This feature implements the [Cloudflare Agent Skills Discovery RFC](https://github.com/cloudflare/agent-skills-discovery-rfc), which extends [RFC 8615](https://datatracker.ietf.org/doc/html/rfc8615) (the same `.well-known` standard behind ACME certificate validation and `security.txt`).
+
+Docus scans your `skills/` directory at build time and generates two types of endpoints:
+
+### Discovery index
+
+```
+GET /.well-known/skills/index.json
+```
+
+Returns a JSON catalog listing all available skills with their descriptions and files:
+
+```json
+{
+  "skills": [
+    {
+      "name": "my-product",
+      "description": "Build and deploy apps with My Product.",
+      "files": ["SKILL.md", "references/api.md"]
+    }
+  ]
+}
+```
+
+### Skill files
+
+```
+GET /.well-known/skills/{skill-name}/SKILL.md
+GET /.well-known/skills/{skill-name}/references/api.md
+```
+
+Individual skill files are served with appropriate content types (`text/markdown` for `.md` files, `application/json` for `.json`, etc.).
+
+## Comparison with llms.txt
+
+Both `llms.txt` and Agent Skills help AI tools work with your documentation, but they serve different purposes:
+
+| | llms.txt | Agent Skills |
+|---|---|---|
+| **Purpose** | Directory of all documentation pages | Capability summary with actionable instructions |
+| **Content** | Page titles, descriptions, and links | Step-by-step workflows, code examples, constraints |
+| **Loaded** | At discovery time | On demand, when the skill is activated |
+| **Format** | Plain text with links | Markdown with YAML frontmatter |
+| **Best for** | Helping agents find information | Teaching agents how to use your product |
+
+::tip
+Use both together: `llms.txt` tells agents where to find information, while skills tell agents what they can accomplish and how.
+::

docs/content/fr/1.getting-started/3.installation.md

@@ -52,17 +52,21 @@ Rendez-vous dans la section [Édition](/fr/concepts/edition) pour apprendre à r
 Démarrez rapidement avec Docus en ajoutant des connaissances spécialisées à votre assistant IA (Cursor, Claude, etc.) :
 
 ```bash [Terminal]
-npx skills add nuxt-content/docus
+npx skills add https://docus.dev
 ```
 
 Ce skill vous aide à créer de la documentation plus rapidement en fournissant à votre assistant IA :
-- 📝 Les meilleures pratiques pour rédiger de la documentation avec Docus
-- 🎨 L'utilisation des composants MDC et des templates prêts à l'emploi
-- 📚 Les guides de rédaction et les modèles de structure de contenu
-- 🔧 Les conseils de configuration et de personnalisation
+- Les meilleures pratiques pour rédiger de la documentation avec Docus
+- L'utilisation des composants MDC et des templates prêts à l'emploi
+- Les guides de rédaction et les modèles de structure de contenu
+- Les conseils de configuration et de personnalisation
 
 Une fois installé, votre assistant IA peut vous aider à créer rapidement de nouveaux projets de documentation, générer des pages avec la bonne structure, et rédiger du contenu en suivant les meilleures pratiques Docus.
 
+::tip{to="/fr/ai/skills"}
+Vous pouvez aussi publier vos propres skills depuis votre site Docus. En savoir plus sur les Agent Skills.
+::
+
 ## Intégration du layer Docus
 
 Docus v4 utilise une **approche basée sur les layers Nuxt**, vous pouvez étendre le layer Docus directement dans votre `nuxt.config.ts` avec `extends: ['docus']` :