From 000e3a61e778f3d8f1092b183692f7ca597a881c Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Wed, 10 Jun 2026 17:29:33 +0000 Subject: [PATCH 1/7] docs: add Agent Skills documentation page Co-Authored-By: mathieu --- fern/products/docs/pages/ai/agent-skills.mdx | 89 ++++++++++++++++++++ 1 file changed, 89 insertions(+) diff --git a/fern/products/docs/pages/ai/agent-skills.mdx b/fern/products/docs/pages/ai/agent-skills.mdx index b9b1030e3..c0c4f2c85 100644 --- a/fern/products/docs/pages/ai/agent-skills.mdx +++ b/fern/products/docs/pages/ai/agent-skills.mdx @@ -33,3 +33,92 @@ The skill routes agents to task-specific references in a `references/` directory | `references/products.md` | Setting up a product switcher, adding a product, or refactoring navigation into the products format. | This routing keeps context small. An agent writing a changelog entry loads `references/changelog.md` and skips the products guide entirely. + +## Host custom skills from your docs site + +Fern docs sites can also serve author-supplied [Agent Skills](https://github.com/cloudflare/agent-skills-discovery-rfc) at the standard `/.well-known/skills/` and `/.well-known/agent-skills/` endpoints. This lets users discover and install your skills with: + +```bash +npx skills add https://your-docs-domain.com +``` + +No `docs.yml` configuration is required. Place your skill bundle inside the `fern/` folder and Fern uploads it during `fern generate --docs`. The docs site serves the files as-is. + +### Directory layout + +Place skills under `.well-known/skills/` (v0.1.0 layout) or `.well-known/agent-skills/` (current v0.2.0 spec) inside your Fern docs folder. Both paths are supported and can coexist. + +```bash title="Project structure" +fern/ + docs.yml + .well-known/ + agent-skills/ + index.json # discovery manifest (required) + code-review/ + SKILL.md # skill instructions + deploy/ + SKILL.md + references/ + api.md # supporting files (optional) +``` + +Each skill lives in its own subdirectory containing at minimum a `SKILL.md` file. Supporting files (references, archives) can be nested alongside it. + +### Discovery manifest + +The `index.json` file at the root of the skills directory is required. It enumerates all available skills so clients can discover them in a single request. For the current v0.2.0 spec: + +```json title="fern/.well-known/agent-skills/index.json" +{ + "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json", + "skills": [ + { + "name": "code-review", + "type": "skill-md", + "description": "Review code for bugs, security issues, and best practices.", + "url": "/.well-known/agent-skills/code-review/SKILL.md", + "digest": "sha256:c4d5e6f7..." + } + ] +} +``` + +For the legacy v0.1.0 layout under `.well-known/skills/`, the manifest follows the same structure without the `$schema` field. + +### SKILL.md format + +Each `SKILL.md` requires YAML frontmatter with `name` and `description`: + +```markdown title="fern/.well-known/agent-skills/code-review/SKILL.md" +--- +name: code-review +description: Review code for bugs, security issues, and best practices. +--- + +# Code Review + +When reviewing code, check for... +``` + +### Validation + +`fern check` validates skill bundles at upload time. It reports errors for: + +- A missing or unparseable `index.json` +- A `SKILL.md` with missing or invalid frontmatter + +Frontmatter requirements for each `SKILL.md`: + +| Field | Rules | +|-------|-------| +| `name` | Kebab-case (lowercase letters, numbers, hyphens). Max 64 characters. Must match the parent directory name. | +| `description` | Non-empty. Max 1,024 characters. | + +### Accessing skills + +After publishing, skills are available at: + +- `https://your-docs-domain.com/.well-known/agent-skills/index.json` (discovery manifest) +- `https://your-docs-domain.com/.well-known/agent-skills//SKILL.md` (individual skill) + +For sites with a basepath like `/docs`, the endpoints live under that basepath (e.g., `https://example.com/docs/.well-known/agent-skills/index.json`). From 54c59758e06ff8cefa1a6a65ab54076b304ff4d5 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Thu, 11 Jun 2026 15:30:25 +0000 Subject: [PATCH 2/7] docs: fix manifest format descriptions and use plant-themed examples Co-Authored-By: mathieu --- fern/products/docs/pages/ai/agent-skills.mdx | 43 ++++++++++++++------ 1 file changed, 30 insertions(+), 13 deletions(-) diff --git a/fern/products/docs/pages/ai/agent-skills.mdx b/fern/products/docs/pages/ai/agent-skills.mdx index c0c4f2c85..3a7dc6a90 100644 --- a/fern/products/docs/pages/ai/agent-skills.mdx +++ b/fern/products/docs/pages/ai/agent-skills.mdx @@ -36,12 +36,14 @@ This routing keeps context small. An agent writing a changelog entry loads `refe ## Host custom skills from your docs site -Fern docs sites can also serve author-supplied [Agent Skills](https://github.com/cloudflare/agent-skills-discovery-rfc) at the standard `/.well-known/skills/` and `/.well-known/agent-skills/` endpoints. This lets users discover and install your skills with: +Fern docs sites can also serve author-supplied [Agent Skills](https://www.skills.sh) at the standard `/.well-known/skills/` and `/.well-known/agent-skills/` endpoints. This lets users discover and install your skills with: ```bash npx skills add https://your-docs-domain.com ``` +The `https://` scheme is required — a bare domain is treated as a GitHub repository shorthand. + No `docs.yml` configuration is required. Place your skill bundle inside the `fern/` folder and Fern uploads it during `fern generate --docs`. The docs site serves the files as-is. ### Directory layout @@ -54,9 +56,9 @@ fern/ .well-known/ agent-skills/ index.json # discovery manifest (required) - code-review/ + plant-care/ SKILL.md # skill instructions - deploy/ + garden-planner/ SKILL.md references/ api.md # supporting files (optional) @@ -66,38 +68,52 @@ Each skill lives in its own subdirectory containing at minimum a `SKILL.md` file ### Discovery manifest -The `index.json` file at the root of the skills directory is required. It enumerates all available skills so clients can discover them in a single request. For the current v0.2.0 spec: +The `index.json` file at the root of the skills directory is required. It enumerates all available skills so clients can discover them in a single request. + +The v0.2.0 spec (`/.well-known/agent-skills/`) uses `url` and `digest` per skill: ```json title="fern/.well-known/agent-skills/index.json" { "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json", "skills": [ { - "name": "code-review", + "name": "plant-care", "type": "skill-md", - "description": "Review code for bugs, security issues, and best practices.", - "url": "/.well-known/agent-skills/code-review/SKILL.md", + "description": "Guide for diagnosing and treating common plant diseases.", + "url": "/.well-known/agent-skills/plant-care/SKILL.md", "digest": "sha256:c4d5e6f7..." } ] } ``` -For the legacy v0.1.0 layout under `.well-known/skills/`, the manifest follows the same structure without the `$schema` field. +The legacy v0.1.0 layout (`/.well-known/skills/`) uses a `files` array instead: + +```json title="fern/.well-known/skills/index.json" +{ + "skills": [ + { + "name": "plant-care", + "description": "Guide for diagnosing and treating common plant diseases.", + "files": ["SKILL.md"] + } + ] +} +``` ### SKILL.md format Each `SKILL.md` requires YAML frontmatter with `name` and `description`: -```markdown title="fern/.well-known/agent-skills/code-review/SKILL.md" +```markdown title="fern/.well-known/agent-skills/plant-care/SKILL.md" --- -name: code-review -description: Review code for bugs, security issues, and best practices. +name: plant-care +description: Guide for diagnosing and treating common plant diseases. --- -# Code Review +# Plant Care -When reviewing code, check for... +When diagnosing a plant issue, check for... ``` ### Validation @@ -120,5 +136,6 @@ After publishing, skills are available at: - `https://your-docs-domain.com/.well-known/agent-skills/index.json` (discovery manifest) - `https://your-docs-domain.com/.well-known/agent-skills//SKILL.md` (individual skill) +- `https://your-docs-domain.com/.well-known/skills/index.json` (legacy v0.1.0 manifest) For sites with a basepath like `/docs`, the endpoints live under that basepath (e.g., `https://example.com/docs/.well-known/agent-skills/index.json`). From e91b77b612a550ebacf57e833a4b199baa379e58 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Thu, 11 Jun 2026 18:19:41 +0000 Subject: [PATCH 3/7] docs: add page-actions.options.skills config and cross-reference Co-Authored-By: mathieu --- fern/products/docs/pages/ai/agent-skills.mdx | 2 +- .../pages/navigation/site-level-settings.mdx | 49 ++++++++++++++++++- 2 files changed, 49 insertions(+), 2 deletions(-) diff --git a/fern/products/docs/pages/ai/agent-skills.mdx b/fern/products/docs/pages/ai/agent-skills.mdx index 3a7dc6a90..1d3519252 100644 --- a/fern/products/docs/pages/ai/agent-skills.mdx +++ b/fern/products/docs/pages/ai/agent-skills.mdx @@ -44,7 +44,7 @@ npx skills add https://your-docs-domain.com The `https://` scheme is required — a bare domain is treated as a GitHub repository shorthand. -No `docs.yml` configuration is required. Place your skill bundle inside the `fern/` folder and Fern uploads it during `fern generate --docs`. The docs site serves the files as-is. +No `docs.yml` configuration is required for serving. Place your skill bundle inside the `fern/` folder and Fern uploads it during `fern generate --docs`. The docs site serves the files as-is. To surface an "Install skills" button in the [page action bar](/learn/docs/configuration/site-level-settings#install-skills-action), add a [`page-actions.options.skills`](/learn/docs/configuration/site-level-settings#install-skills-action) config to your `docs.yml`. ### Directory layout diff --git a/fern/products/docs/pages/navigation/site-level-settings.mdx b/fern/products/docs/pages/navigation/site-level-settings.mdx index dd127ef57..34db53829 100644 --- a/fern/products/docs/pages/navigation/site-level-settings.mdx +++ b/fern/products/docs/pages/navigation/site-level-settings.mdx @@ -830,7 +830,7 @@ page-actions: ``` - The default page action to display. Options: `copy-page`, `view-as-markdown`, `ask-ai`, `chatgpt`, `claude`, `claude-code`, `cursor`, `vscode`. + The default page action to display. Options: `copy-page`, `view-as-markdown`, `ask-ai`, `chatgpt`, `claude`, `claude-code`, `cursor`, `vscode`, `install-skills`. @@ -865,6 +865,53 @@ page-actions: When enabled, displays an "Open in VS Code" button that allows users to open the page content in Visual Studio Code for editing and development. Requires [Ask Fern](/learn/docs/ai-features/ask-fern/overview) to be enabled. +### Install skills action + +Add an "Install skills" button to the page action bar that opens a modal showing how to install your site's [agent skills](/learn/docs/ai-features/agent-skills). The modal displays a copyable install command, the list of available skills, and links to the skill source. + +```yaml docs.yml +page-actions: + options: + skills: + title: Plant API Skills + description: Skills for working with the Plant Store API. + repository: https://github.com/your-org/plant-api-skills + skills: + - name: plant-care + description: Guide for diagnosing and treating common plant diseases. + url: https://github.com/your-org/plant-api-skills/tree/main/plant-care +``` + +When no `install-command` is provided, the modal defaults to `npx skills add https://`. On first open, the modal fetches the site's served `/.well-known/agent-skills/index.json` manifest and replaces the config-driven skill list with whatever the manifest contains. + + + Enables the "Install skills" page action and configures its modal. Omit to hide the action. + + + + Overrides the modal title. + + + + Overrides the modal description. + + + + URL for a "Learn more" link shown alongside the description. + + + + Source repository URL displayed as a "View source" button in the modal. + + + + Command(s) shown as a copyable block in the modal. A single string is shown as-is; an array is joined with newlines for multi-step installs. Defaults to `npx skills add https://` when omitted. + + + + List of skills displayed in the modal. Each entry has a `name` (required), `description` (optional), and `url` (optional link to the skill source). When the site serves a `/.well-known/agent-skills/index.json` or `/.well-known/skills/index.json` manifest, the manifest replaces this list. + + ### Custom page actions Define custom page action buttons with your own titles, icons, and URLs. Custom actions appear alongside the built-in page actions and can link to external tools, editors, or any URL. From 3f30a16eac8a7ec9bdaca8ca11a66c1e52974735 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Thu, 11 Jun 2026 18:20:28 +0000 Subject: [PATCH 4/7] docs: add changelog entries for agent skills hosting and install-skills action Co-Authored-By: mathieu --- fern/products/docs/pages/changelog/2026-06-10.mdx | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/fern/products/docs/pages/changelog/2026-06-10.mdx b/fern/products/docs/pages/changelog/2026-06-10.mdx index 8501536b4..5af3d8e31 100644 --- a/fern/products/docs/pages/changelog/2026-06-10.mdx +++ b/fern/products/docs/pages/changelog/2026-06-10.mdx @@ -11,3 +11,17 @@ npx skills add fern-api/skills --skill fern-docs ``` + +## Host agent skills from your docs site + +Fern docs sites can now serve author-supplied [Agent Skills](https://www.skills.sh) at the standard `/.well-known/skills/` and `/.well-known/agent-skills/` endpoints. Place your skill bundle under `fern/.well-known/agent-skills/` and the CLI uploads it during `fern generate --docs`. Users install with `npx skills add https://`. + +`fern check` validates skill bundles: `index.json` must exist and parse, and each `SKILL.md` frontmatter needs a kebab-case `name` (max 64 characters) matching its parent directory and a non-empty `description` (max 1,024 characters). + + + +## "Install skills" page action + +You can now add an "Install skills" button to the page action bar via `page-actions.options.skills` in `docs.yml`. The button opens a modal showing a copyable install command, the list of available skills, and a link to the skill source. The modal fetches the site's served well-known manifest on first open, so the skill list stays in sync with what `npx skills add` installs. + + From f88cfa9267193751c743a9d5ac7f5537d3d420f6 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Thu, 11 Jun 2026 18:42:52 +0000 Subject: [PATCH 5/7] docs: add install skills modal config section to agent-skills page Co-Authored-By: mathieu --- fern/products/docs/pages/ai/agent-skills.mdx | 35 +++++++++++++++++++- 1 file changed, 34 insertions(+), 1 deletion(-) diff --git a/fern/products/docs/pages/ai/agent-skills.mdx b/fern/products/docs/pages/ai/agent-skills.mdx index 1d3519252..e63532910 100644 --- a/fern/products/docs/pages/ai/agent-skills.mdx +++ b/fern/products/docs/pages/ai/agent-skills.mdx @@ -1,6 +1,6 @@ --- title: Agent skills -description: Install the fern-docs agent skill to teach coding agents how to author and edit Fern Docs sites. +description: Install the fern-docs agent skill, host custom skills from your docs site, and configure the install skills modal. availability: beta --- @@ -139,3 +139,36 @@ After publishing, skills are available at: - `https://your-docs-domain.com/.well-known/skills/index.json` (legacy v0.1.0 manifest) For sites with a basepath like `/docs`, the endpoints live under that basepath (e.g., `https://example.com/docs/.well-known/agent-skills/index.json`). + +## Configure the install skills modal + +Add an "Install skills" button to the page action bar by configuring `page-actions.options.skills` in `docs.yml`. The button opens a modal with a copyable install command and a list of available skills. + +```yaml docs.yml +page-actions: + options: + skills: + title: Plant API Skills + description: Skills for working with the Plant Store API. + repository: https://github.com/your-org/plant-api-skills + install-command: npx skills add https://your-docs-domain.com + skills: + - name: plant-care + description: Guide for diagnosing and treating common plant diseases. + url: https://github.com/your-org/plant-api-skills/tree/main/plant-care + - name: garden-planner + description: Plan garden layouts and planting schedules. +``` + +| Field | Description | +|-------|-------------| +| `title` | Overrides the modal title. | +| `description` | Overrides the modal description. | +| `learn-more-url` | URL for a "Learn more" link in the modal. | +| `repository` | Source repository shown as a "View source" button. | +| `install-command` | Command(s) shown as a copyable block. Defaults to `npx skills add https://` when omitted. Accepts a string or a list of strings for multi-step installs. | +| `skills` | List of skills displayed in the modal. Each entry has `name` (required), `description` (optional), and `url` (optional link to skill source). | + +When the site also serves a well-known manifest (from a [skill bundle](#directory-layout)), the modal fetches it on first open and replaces the config-driven list with the manifest contents. This keeps the modal in sync with what `npx skills add` installs. + +For the full parameter reference, see [Install skills action](/learn/docs/configuration/site-level-settings#install-skills-action). From fef0c1c8b815c7c805dfc4dc9e354bfc21da2d30 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Thu, 11 Jun 2026 18:47:33 +0000 Subject: [PATCH 6/7] =?UTF-8?q?docs:=20restructure=20agent-skills=20page?= =?UTF-8?q?=20=E2=80=94=20lead=20with=20docs.yml=20config,=20well-known=20?= =?UTF-8?q?as=20secondary?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: mathieu --- fern/products/docs/pages/ai/agent-skills.mdx | 84 ++++++++++---------- 1 file changed, 41 insertions(+), 43 deletions(-) diff --git a/fern/products/docs/pages/ai/agent-skills.mdx b/fern/products/docs/pages/ai/agent-skills.mdx index e63532910..37820d201 100644 --- a/fern/products/docs/pages/ai/agent-skills.mdx +++ b/fern/products/docs/pages/ai/agent-skills.mdx @@ -36,17 +36,48 @@ This routing keeps context small. An agent writing a changelog entry loads `refe ## Host custom skills from your docs site -Fern docs sites can also serve author-supplied [Agent Skills](https://www.skills.sh) at the standard `/.well-known/skills/` and `/.well-known/agent-skills/` endpoints. This lets users discover and install your skills with: +Fern docs sites can serve your own [Agent Skills](https://www.skills.sh) so users can discover and install them with `npx skills add https://your-docs-domain.com`. There are two parts: configuring the "Install skills" modal and serving the skill files at well-known endpoints. -```bash -npx skills add https://your-docs-domain.com +### Configure the modal + +Add an "Install skills" button to the [page action bar](/learn/docs/configuration/site-level-settings#page-actions-configuration) by setting `page-actions.options.skills` in `docs.yml`. The button opens a modal with a copyable install command, a list of available skills, and an optional link to the source repository. + +```yaml docs.yml +page-actions: + options: + skills: + title: Plant API Skills + description: Skills for working with the Plant Store API. + repository: https://github.com/your-org/plant-api-skills + install-command: npx skills add https://your-docs-domain.com + skills: + - name: plant-care + description: Guide for diagnosing and treating common plant diseases. + url: https://github.com/your-org/plant-api-skills/tree/main/plant-care + - name: garden-planner + description: Plan garden layouts and planting schedules. ``` -The `https://` scheme is required — a bare domain is treated as a GitHub repository shorthand. +| Field | Description | +|-------|-------------| +| `title` | Overrides the modal title. | +| `description` | Overrides the modal description. | +| `learn-more-url` | URL for a "Learn more" link in the modal. | +| `repository` | Source repository shown as a "View source" button. | +| `install-command` | Command(s) shown as a copyable block. Defaults to `npx skills add https://` when omitted. Accepts a string or a list of strings for multi-step installs. | +| `skills` | List of skills displayed in the modal. Each entry has `name` (required), `description` (optional), and `url` (optional link to skill source). | + +For the full parameter reference, see [Install skills action](/learn/docs/configuration/site-level-settings#install-skills-action). + +### Serve skill files at well-known endpoints + +For `npx skills add https://your-docs-domain.com` to work, the docs site needs to serve a skill bundle at the standard `/.well-known/skills/` or `/.well-known/agent-skills/` endpoints. Place the bundle inside your `fern/` folder and the CLI uploads it during `fern generate --docs`. No `docs.yml` configuration is required for serving. + +The `https://` scheme is required in the install command: a bare domain is treated as a GitHub repository shorthand. -No `docs.yml` configuration is required for serving. Place your skill bundle inside the `fern/` folder and Fern uploads it during `fern generate --docs`. The docs site serves the files as-is. To surface an "Install skills" button in the [page action bar](/learn/docs/configuration/site-level-settings#install-skills-action), add a [`page-actions.options.skills`](/learn/docs/configuration/site-level-settings#install-skills-action) config to your `docs.yml`. +When the site serves a well-known manifest, the modal fetches it on first open and replaces the config-driven skill list with the manifest contents. This keeps the modal in sync with what `npx skills add` installs. -### Directory layout +#### Directory layout Place skills under `.well-known/skills/` (v0.1.0 layout) or `.well-known/agent-skills/` (current v0.2.0 spec) inside your Fern docs folder. Both paths are supported and can coexist. @@ -66,7 +97,7 @@ fern/ Each skill lives in its own subdirectory containing at minimum a `SKILL.md` file. Supporting files (references, archives) can be nested alongside it. -### Discovery manifest +#### Discovery manifest The `index.json` file at the root of the skills directory is required. It enumerates all available skills so clients can discover them in a single request. @@ -101,7 +132,7 @@ The legacy v0.1.0 layout (`/.well-known/skills/`) uses a `files` array instead: } ``` -### SKILL.md format +#### SKILL.md format Each `SKILL.md` requires YAML frontmatter with `name` and `description`: @@ -116,7 +147,7 @@ description: Guide for diagnosing and treating common plant diseases. When diagnosing a plant issue, check for... ``` -### Validation +#### Validation `fern check` validates skill bundles at upload time. It reports errors for: @@ -130,7 +161,7 @@ Frontmatter requirements for each `SKILL.md`: | `name` | Kebab-case (lowercase letters, numbers, hyphens). Max 64 characters. Must match the parent directory name. | | `description` | Non-empty. Max 1,024 characters. | -### Accessing skills +#### Accessing skills After publishing, skills are available at: @@ -139,36 +170,3 @@ After publishing, skills are available at: - `https://your-docs-domain.com/.well-known/skills/index.json` (legacy v0.1.0 manifest) For sites with a basepath like `/docs`, the endpoints live under that basepath (e.g., `https://example.com/docs/.well-known/agent-skills/index.json`). - -## Configure the install skills modal - -Add an "Install skills" button to the page action bar by configuring `page-actions.options.skills` in `docs.yml`. The button opens a modal with a copyable install command and a list of available skills. - -```yaml docs.yml -page-actions: - options: - skills: - title: Plant API Skills - description: Skills for working with the Plant Store API. - repository: https://github.com/your-org/plant-api-skills - install-command: npx skills add https://your-docs-domain.com - skills: - - name: plant-care - description: Guide for diagnosing and treating common plant diseases. - url: https://github.com/your-org/plant-api-skills/tree/main/plant-care - - name: garden-planner - description: Plan garden layouts and planting schedules. -``` - -| Field | Description | -|-------|-------------| -| `title` | Overrides the modal title. | -| `description` | Overrides the modal description. | -| `learn-more-url` | URL for a "Learn more" link in the modal. | -| `repository` | Source repository shown as a "View source" button. | -| `install-command` | Command(s) shown as a copyable block. Defaults to `npx skills add https://` when omitted. Accepts a string or a list of strings for multi-step installs. | -| `skills` | List of skills displayed in the modal. Each entry has `name` (required), `description` (optional), and `url` (optional link to skill source). | - -When the site also serves a well-known manifest (from a [skill bundle](#directory-layout)), the modal fetches it on first open and replaces the config-driven list with the manifest contents. This keeps the modal in sync with what `npx skills add` installs. - -For the full parameter reference, see [Install skills action](/learn/docs/configuration/site-level-settings#install-skills-action). From 9c0ec2083795a5a191b00ac02fa330a3a88e4911 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 11 Jun 2026 16:21:10 -0400 Subject: [PATCH 7/7] structural edits for clarity --- fern/products/docs/docs.yml | 13 +- fern/products/docs/pages/ai/agent-skills.mdx | 147 +----------------- fern/products/docs/pages/ai/host-skills.mdx | 127 +++++++++++++++ .../docs/pages/changelog/2026-06-10.mdx | 4 +- .../pages/navigation/site-level-settings.mdx | 38 +---- .../snippets/install-skills-properties.mdx | 27 ++++ 6 files changed, 179 insertions(+), 177 deletions(-) create mode 100644 fern/products/docs/pages/ai/host-skills.mdx create mode 100644 fern/products/docs/snippets/install-skills-properties.mdx diff --git a/fern/products/docs/docs.yml b/fern/products/docs/docs.yml index 990095443..5d2788c0c 100644 --- a/fern/products/docs/docs.yml +++ b/fern/products/docs/docs.yml @@ -204,9 +204,16 @@ navigation: - page: API catalog discovery path: ./pages/ai/api-catalog.mdx slug: api-catalog - - page: Agent skills - path: ./pages/ai/agent-skills.mdx - slug: agent-skills + - section: Agent skills + collapsed: open-by-default + skip-slug: true + contents: + - page: fern-docs skill + path: ./pages/ai/agent-skills.mdx + slug: agent-skills + - page: Custom skills + path: ./pages/ai/host-skills.mdx + slug: host-skills - section: Ask Fern slug: ask-fern contents: diff --git a/fern/products/docs/pages/ai/agent-skills.mdx b/fern/products/docs/pages/ai/agent-skills.mdx index 37820d201..c15455cd8 100644 --- a/fern/products/docs/pages/ai/agent-skills.mdx +++ b/fern/products/docs/pages/ai/agent-skills.mdx @@ -1,10 +1,14 @@ --- -title: Agent skills -description: Install the fern-docs agent skill, host custom skills from your docs site, and configure the install skills modal. +title: fern-docs skill +description: Install the fern-docs agent skill to teach coding agents how to author and edit Fern Docs sites. availability: beta --- -The `fern-docs` [agent skill](https://www.skills.sh) teaches coding agents (Claude Code, Cursor, Codex, Copilot, and others) how to work with Fern Docs. It ships in the [`fern-api/skills`](https://github.com/fern-api/skills) repository and loads automatically when an agent's task involves docs authoring. +The `fern-docs` [agent skill](https://www.skills.sh) teaches coding agents (Claude Code, Cursor, Codex, Copilot, and others) how to work with Fern Docs. It ships in the [`fern-api/skills`](https://github.com/fern-api/skills) repository and loads automatically when an agent's task involves docs authoring. + + + Your docs site can also [host your own skills](/learn/docs/ai-features/host-skills) for your users to discover and install. + ## Install @@ -33,140 +37,3 @@ The skill routes agents to task-specific references in a `references/` directory | `references/products.md` | Setting up a product switcher, adding a product, or refactoring navigation into the products format. | This routing keeps context small. An agent writing a changelog entry loads `references/changelog.md` and skips the products guide entirely. - -## Host custom skills from your docs site - -Fern docs sites can serve your own [Agent Skills](https://www.skills.sh) so users can discover and install them with `npx skills add https://your-docs-domain.com`. There are two parts: configuring the "Install skills" modal and serving the skill files at well-known endpoints. - -### Configure the modal - -Add an "Install skills" button to the [page action bar](/learn/docs/configuration/site-level-settings#page-actions-configuration) by setting `page-actions.options.skills` in `docs.yml`. The button opens a modal with a copyable install command, a list of available skills, and an optional link to the source repository. - -```yaml docs.yml -page-actions: - options: - skills: - title: Plant API Skills - description: Skills for working with the Plant Store API. - repository: https://github.com/your-org/plant-api-skills - install-command: npx skills add https://your-docs-domain.com - skills: - - name: plant-care - description: Guide for diagnosing and treating common plant diseases. - url: https://github.com/your-org/plant-api-skills/tree/main/plant-care - - name: garden-planner - description: Plan garden layouts and planting schedules. -``` - -| Field | Description | -|-------|-------------| -| `title` | Overrides the modal title. | -| `description` | Overrides the modal description. | -| `learn-more-url` | URL for a "Learn more" link in the modal. | -| `repository` | Source repository shown as a "View source" button. | -| `install-command` | Command(s) shown as a copyable block. Defaults to `npx skills add https://` when omitted. Accepts a string or a list of strings for multi-step installs. | -| `skills` | List of skills displayed in the modal. Each entry has `name` (required), `description` (optional), and `url` (optional link to skill source). | - -For the full parameter reference, see [Install skills action](/learn/docs/configuration/site-level-settings#install-skills-action). - -### Serve skill files at well-known endpoints - -For `npx skills add https://your-docs-domain.com` to work, the docs site needs to serve a skill bundle at the standard `/.well-known/skills/` or `/.well-known/agent-skills/` endpoints. Place the bundle inside your `fern/` folder and the CLI uploads it during `fern generate --docs`. No `docs.yml` configuration is required for serving. - -The `https://` scheme is required in the install command: a bare domain is treated as a GitHub repository shorthand. - -When the site serves a well-known manifest, the modal fetches it on first open and replaces the config-driven skill list with the manifest contents. This keeps the modal in sync with what `npx skills add` installs. - -#### Directory layout - -Place skills under `.well-known/skills/` (v0.1.0 layout) or `.well-known/agent-skills/` (current v0.2.0 spec) inside your Fern docs folder. Both paths are supported and can coexist. - -```bash title="Project structure" -fern/ - docs.yml - .well-known/ - agent-skills/ - index.json # discovery manifest (required) - plant-care/ - SKILL.md # skill instructions - garden-planner/ - SKILL.md - references/ - api.md # supporting files (optional) -``` - -Each skill lives in its own subdirectory containing at minimum a `SKILL.md` file. Supporting files (references, archives) can be nested alongside it. - -#### Discovery manifest - -The `index.json` file at the root of the skills directory is required. It enumerates all available skills so clients can discover them in a single request. - -The v0.2.0 spec (`/.well-known/agent-skills/`) uses `url` and `digest` per skill: - -```json title="fern/.well-known/agent-skills/index.json" -{ - "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json", - "skills": [ - { - "name": "plant-care", - "type": "skill-md", - "description": "Guide for diagnosing and treating common plant diseases.", - "url": "/.well-known/agent-skills/plant-care/SKILL.md", - "digest": "sha256:c4d5e6f7..." - } - ] -} -``` - -The legacy v0.1.0 layout (`/.well-known/skills/`) uses a `files` array instead: - -```json title="fern/.well-known/skills/index.json" -{ - "skills": [ - { - "name": "plant-care", - "description": "Guide for diagnosing and treating common plant diseases.", - "files": ["SKILL.md"] - } - ] -} -``` - -#### SKILL.md format - -Each `SKILL.md` requires YAML frontmatter with `name` and `description`: - -```markdown title="fern/.well-known/agent-skills/plant-care/SKILL.md" ---- -name: plant-care -description: Guide for diagnosing and treating common plant diseases. ---- - -# Plant Care - -When diagnosing a plant issue, check for... -``` - -#### Validation - -`fern check` validates skill bundles at upload time. It reports errors for: - -- A missing or unparseable `index.json` -- A `SKILL.md` with missing or invalid frontmatter - -Frontmatter requirements for each `SKILL.md`: - -| Field | Rules | -|-------|-------| -| `name` | Kebab-case (lowercase letters, numbers, hyphens). Max 64 characters. Must match the parent directory name. | -| `description` | Non-empty. Max 1,024 characters. | - -#### Accessing skills - -After publishing, skills are available at: - -- `https://your-docs-domain.com/.well-known/agent-skills/index.json` (discovery manifest) -- `https://your-docs-domain.com/.well-known/agent-skills//SKILL.md` (individual skill) -- `https://your-docs-domain.com/.well-known/skills/index.json` (legacy v0.1.0 manifest) - -For sites with a basepath like `/docs`, the endpoints live under that basepath (e.g., `https://example.com/docs/.well-known/agent-skills/index.json`). diff --git a/fern/products/docs/pages/ai/host-skills.mdx b/fern/products/docs/pages/ai/host-skills.mdx new file mode 100644 index 000000000..4833fed31 --- /dev/null +++ b/fern/products/docs/pages/ai/host-skills.mdx @@ -0,0 +1,127 @@ +--- +title: Custom skills +description: Serve author-supplied agent skills from your Fern docs site and configure the Install skills button. +availability: beta +--- + +Fern Docs sites can serve your own [Agent Skills](https://www.skills.sh) so your users can discover and install them with the [skills CLI](https://www.skills.sh). You can also add an "Install skills" button to your docs UI that opens a modal with the install command and your skill list. + + + This is separate from installing Fern's own [`fern-docs` skill](/learn/docs/ai-features/agent-skills) into your agent. + + + + + +Place your skills in your `fern/` folder under `.well-known/agent-skills/` (the current v0.2.0 spec) or `.well-known/skills/` (the legacy v0.1.0 layout). Both are supported and can coexist. Each skill is a subdirectory holding at least a `SKILL.md`, with optional supporting files alongside it. + + + + + + + + + + + + + + + + + + + + + + + + +Each `SKILL.md` needs YAML frontmatter with `name` and `description`, following the [Agent Skills spec](https://agentskills.io): + +```markdown title="fern/.well-known/agent-skills/plant-care/SKILL.md" +--- +name: plant-care +description: Guide for diagnosing and treating common plant diseases. +--- + +# Plant Care + +When diagnosing a plant issue, check for... +``` + + + + +The `index.json` at the root of the skills directory is required. It enumerates every skill so clients can discover them in a single request, referencing each by `url` and `digest`: + +```json title="fern/.well-known/agent-skills/index.json" +{ + "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json", + "skills": [ + { + "name": "plant-care", + "type": "skill-md", + "description": "Guide for diagnosing and treating common plant diseases.", + "url": "/.well-known/agent-skills/plant-care/SKILL.md", + "digest": "sha256:c4d5e6f7..." + } + ] +} +``` + +The legacy v0.1.0 manifest lists a `files` array per skill instead of `url` and `digest`. + + + + +Fern uploads the bundle during `fern generate --docs` and serves the files as-is — no `docs.yml` configuration is required. `fern check` validates the bundle at upload time, flagging a missing or unparseable `index.json` and any `SKILL.md` whose frontmatter doesn't conform to the spec. + +Once published, skills are served at: + +- `https://your-docs-domain.com/.well-known/agent-skills/index.json` (discovery manifest) +- `https://your-docs-domain.com/.well-known/agent-skills//SKILL.md` (individual skill) +- `https://your-docs-domain.com/.well-known/skills/index.json` (legacy v0.1.0 manifest) + +For sites with a basepath like `/docs`, the endpoints live under that basepath (e.g., `https://example.com/docs/.well-known/agent-skills/index.json`). + + + + +With the bundle published, anyone can install your skills with: + +```bash +npx skills add https://your-docs-domain.com +``` + +The `https://` scheme is required: a bare domain is treated as a GitHub repository shorthand. + + + + +Surface your skills in the docs UI by adding an "Install skills" button to the [page action bar](/learn/docs/configuration/site-level-settings#page-actions-configuration). Set `page-actions.options.skills` in `docs.yml` and the button opens a modal with a copyable install command, the list of available skills, and an optional link to the source repository. + +```yaml docs.yml +page-actions: + options: + skills: + title: Plant API Skills + description: Skills for working with the Plant Store API. + repository: https://github.com/your-org/plant-api-skills + install-command: npx skills add https://your-docs-domain.com + skills: + - name: plant-care + description: Guide for diagnosing and treating common plant diseases. + url: https://github.com/your-org/plant-api-skills/tree/main/plant-care + - name: garden-planner + description: Plan garden layouts and planting schedules. +``` + + + +## Install skills properties + +Configure the Install skills button under `page-actions.options.skills` in `docs.yml`. + + diff --git a/fern/products/docs/pages/changelog/2026-06-10.mdx b/fern/products/docs/pages/changelog/2026-06-10.mdx index 5af3d8e31..597e53391 100644 --- a/fern/products/docs/pages/changelog/2026-06-10.mdx +++ b/fern/products/docs/pages/changelog/2026-06-10.mdx @@ -16,9 +16,7 @@ npx skills add fern-api/skills --skill fern-docs Fern docs sites can now serve author-supplied [Agent Skills](https://www.skills.sh) at the standard `/.well-known/skills/` and `/.well-known/agent-skills/` endpoints. Place your skill bundle under `fern/.well-known/agent-skills/` and the CLI uploads it during `fern generate --docs`. Users install with `npx skills add https://`. -`fern check` validates skill bundles: `index.json` must exist and parse, and each `SKILL.md` frontmatter needs a kebab-case `name` (max 64 characters) matching its parent directory and a non-empty `description` (max 1,024 characters). - - + ## "Install skills" page action diff --git a/fern/products/docs/pages/navigation/site-level-settings.mdx b/fern/products/docs/pages/navigation/site-level-settings.mdx index 34db53829..ddf824056 100644 --- a/fern/products/docs/pages/navigation/site-level-settings.mdx +++ b/fern/products/docs/pages/navigation/site-level-settings.mdx @@ -816,7 +816,7 @@ settings: ## Page actions configuration -Configure the page action buttons that appear throughout your documentation. By default, **Copy Page** (`copy-page`), **View as Markdown** (`view-as-markdown`), **Ask AI** (`ask-ai`), **ChatGPT** (`chatgpt`), **Claude** (`claude`), **Claude Code** (`claude-code`), and **Cursor** (`cursor`) are enabled. +Configure the page action buttons that appear throughout your documentation. `page-actions.options` holds two kinds of actions: built-in actions you toggle on or off with a boolean, and configurable actions — the [Install skills action](#install-skills-action) and [custom page actions](#custom-page-actions) — that you define with their own settings. Set `page-actions.default` to choose which action shows first. To hide page actions on an individual page, use the [`hide-page-actions` frontmatter property](/learn/docs/configuration/page-level-settings#page-actions). @@ -833,6 +833,10 @@ page-actions: The default page action to display. Options: `copy-page`, `view-as-markdown`, `ask-ai`, `chatgpt`, `claude`, `claude-code`, `cursor`, `vscode`, `install-skills`. +### Built-in actions + +Toggle the built-in actions on or off with a boolean. **Copy Page** (`copy-page`), **View as Markdown** (`view-as-markdown`), **Ask AI** (`ask-ai`), **ChatGPT** (`chatgpt`), **Claude** (`claude`), **Claude Code** (`claude-code`), and **Cursor** (`cursor`) are enabled by default. + When enabled, displays a button that allows users to copy the entire page content to their clipboard for easy sharing or reference. To control what content appears in the copied output, use [``](/learn/docs/ai-features/customize-llm-output#content-for-humans-only) tags. @@ -867,7 +871,7 @@ page-actions: ### Install skills action -Add an "Install skills" button to the page action bar that opens a modal showing how to install your site's [agent skills](/learn/docs/ai-features/agent-skills). The modal displays a copyable install command, the list of available skills, and links to the skill source. +Add an "Install skills" button to the page action bar that opens a modal showing how to install your site's [custom skills](/learn/docs/ai-features/host-skills). The modal displays a copyable install command, the list of available skills, and links to the skill source. ```yaml docs.yml page-actions: @@ -882,35 +886,7 @@ page-actions: url: https://github.com/your-org/plant-api-skills/tree/main/plant-care ``` -When no `install-command` is provided, the modal defaults to `npx skills add https://`. On first open, the modal fetches the site's served `/.well-known/agent-skills/index.json` manifest and replaces the config-driven skill list with whatever the manifest contains. - - - Enables the "Install skills" page action and configures its modal. Omit to hide the action. - - - - Overrides the modal title. - - - - Overrides the modal description. - - - - URL for a "Learn more" link shown alongside the description. - - - - Source repository URL displayed as a "View source" button in the modal. - - - - Command(s) shown as a copyable block in the modal. A single string is shown as-is; an array is joined with newlines for multi-step installs. Defaults to `npx skills add https://` when omitted. - - - - List of skills displayed in the modal. Each entry has a `name` (required), `description` (optional), and `url` (optional link to the skill source). When the site serves a `/.well-known/agent-skills/index.json` or `/.well-known/skills/index.json` manifest, the manifest replaces this list. - + ### Custom page actions diff --git a/fern/products/docs/snippets/install-skills-properties.mdx b/fern/products/docs/snippets/install-skills-properties.mdx new file mode 100644 index 000000000..0d71c5682 --- /dev/null +++ b/fern/products/docs/snippets/install-skills-properties.mdx @@ -0,0 +1,27 @@ + + Enables the "Install skills" page action and configures the modal it opens. Omit to hide it. + + + + Overrides the modal title. + + + + Overrides the modal description. + + + + URL for a "Learn more" link shown alongside the description. + + + + Source repository URL displayed as a "View source" button in the modal. + + + + Command(s) shown as a copyable block in the modal. A single string is shown as-is; an array is joined with newlines for multi-step installs. Defaults to `npx skills add https://` when omitted. + + + + List of skills displayed in the modal. Each entry has a `name` (required), `description` (optional), and `url` (optional link to the skill source). When the site serves a `/.well-known/agent-skills/index.json` or `/.well-known/skills/index.json` manifest, the manifest replaces this list. +