docs: add custom agent skills hosting to Agent skills page

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:

fern/products/docs/pages/ai/agent-skills.mdx

@@ -1,11 +1,15 @@
 ---
-title: Agent skills
+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 author and edit Fern Docs sites. It ships in the [`fern-api/skills`](https://github.com/fern-api/skills) repository.
 
+<Tip>
+    Your docs site can also [host your own skills](/learn/docs/ai-features/host-skills) for your users to discover and install.
+</Tip>
+
 ## Install
 
 From your project, run the command for your agent:

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. 
+
+<Note>
+  This is separate from installing Fern's own [`fern-docs` skill](/learn/docs/ai-features/agent-skills) into your agent.
+</Note>
+
+<Steps toc={true} tocDepth={2}>
+  <Step title="Lay out the bundle">
+
+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.
+
+<Files>
+  <Folder name="fern" defaultOpen>
+    <File name="docs.yml" />
+    <Folder name=".well-known" defaultOpen>
+      <Folder name="agent-skills" defaultOpen>
+        <File name="index.json" comment="discovery manifest (required)" />
+        <Folder name="plant-care" defaultOpen>
+          <File name="SKILL.md" comment="skill instructions" />
+        </Folder>
+        <Folder name="garden-planner" defaultOpen>
+          <File name="SKILL.md" />
+          <Folder name="references" defaultOpen>
+            <File name="api.md" comment="supporting files (optional)" />
+          </Folder>
+        </Folder>
+      </Folder>
+    </Folder>
+  </Folder>
+</Files>
+
+  </Step>
+  <Step title="Write each SKILL.md">
+
+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...
+```
+
+  </Step>
+  <Step title="Add the discovery manifest">
+
+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`.
+
+  </Step>
+  <Step title="Publish">
+
+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-name>/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`).
+
+  </Step>
+  <Step title="Install the skills">
+
+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.
+
+  </Step>
+  <Step title="Configure the Install skills button">
+
+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.
+```
+</Step>
+</Steps>
+
+## Install skills properties
+
+Configure the Install skills button under `page-actions.options.skills` in `docs.yml`.
+
+<Markdown src="/products/docs/snippets/install-skills-properties.mdx" />

fern/products/docs/pages/changelog/2026-06-10.mdx

@@ -11,3 +11,15 @@ npx skills add fern-api/skills --skill fern-docs
 ```
 
 <Button intent="none" outlined rightIcon="arrow-right" href="/learn/docs/ai-features/agent-skills">Read the docs</Button>
+
+## 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://<your-domain>`.
+
+<Button intent="none" outlined rightIcon="arrow-right" href="/learn/docs/ai-features/host-skills">Read the docs</Button>
+
+## "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.
+
+<Button intent="none" outlined rightIcon="arrow-right" href="/learn/docs/configuration/site-level-settings#install-skills-action">Read the docs</Button>

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).
 
@@ -830,9 +830,13 @@ page-actions:
 ```
 
 <ParamField path="page-actions.default" type="string" required={false} toc={true}>
-  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`.
 </ParamField>
 
+### 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.
+
 <ParamField path="page-actions.options.copy-page" type="boolean" required={false} default="true" toc={true}>
   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 [`<llms-ignore>`](/learn/docs/ai-features/customize-llm-output#content-for-humans-only) tags.
 </ParamField>
@@ -865,6 +869,25 @@ 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.
 </ParamField>
 
+### Install skills action
+
+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:
+  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
+```
+
+<Markdown src="/products/docs/snippets/install-skills-properties.mdx" />
+
 ### 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.

fern/products/docs/snippets/install-skills-properties.mdx

@@ -0,0 +1,27 @@
+<ParamField path="page-actions.options.skills" type="object" required={false} toc={true}>
+  Enables the "Install skills" page action and configures the modal it opens. Omit to hide it.
+</ParamField>
+
+<ParamField path="page-actions.options.skills.title" type="string" required={false} toc={true}>
+  Overrides the modal title.
+</ParamField>
+
+<ParamField path="page-actions.options.skills.description" type="string" required={false} toc={true}>
+  Overrides the modal description.
+</ParamField>
+
+<ParamField path="page-actions.options.skills.learn-more-url" type="string" required={false} toc={true}>
+  URL for a "Learn more" link shown alongside the description.
+</ParamField>
+
+<ParamField path="page-actions.options.skills.repository" type="string" required={false} toc={true}>
+  Source repository URL displayed as a "View source" button in the modal.
+</ParamField>
+
+<ParamField path="page-actions.options.skills.install-command" type="string or list of strings" required={false} toc={true}>
+  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://<your-docs-domain>` when omitted.
+</ParamField>
+
+<ParamField path="page-actions.options.skills.skills" type="list of objects" required={false} toc={true}>
+  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.
+</ParamField>