From 9669d3bf88c1a25228db3f54afb92613896a9003 Mon Sep 17 00:00:00 2001 From: Mathieu Legault Date: Mon, 22 Jun 2026 10:12:34 -0400 Subject: [PATCH 1/2] chore(docs): drop removed skills repository field and document skills path The skills config rework in fern-api/fern#16510 removes the `repository` display field from page-actions.options.skills (the schema becomes strict) and adds a `path` field that points the CLI at a directory of skills in the docs repo, which it validates, bundles, and publishes. - fern/docs.yml: drop the repository line; keep title/description/learn-more-url, the manual skills array, and install-command (npx skills add fern-api/skills) - host-skills.mdx: rework to recommend declaring page-actions.options.skills.path; demote the hand-built .well-known/skills/ convention to a legacy fallback - install-skills-properties.mdx: add the path ParamField, remove repository - site-level-settings.mdx: path-based Install skills example, drop repository Co-Authored-By: Claude Opus 4.8 (1M context) --- fern/docs.yml | 1 - fern/products/docs/pages/ai/host-skills.mdx | 101 ++++++++++-------- .../pages/navigation/site-level-settings.mdx | 8 +- .../snippets/install-skills-properties.mdx | 12 +-- 4 files changed, 62 insertions(+), 60 deletions(-) diff --git a/fern/docs.yml b/fern/docs.yml index 0d78ac0aa2..122270b61b 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -172,7 +172,6 @@ page-actions: title: Install agent skills description: Skills for authoring Fern documentation, maintained in our open-source skills repo. learn-more-url: https://buildwithfern.com/learn/docs/ai/agent-skills - repository: https://github.com/fern-api/skills install-command: npx skills add fern-api/skills skills: - name: fern-docs diff --git a/fern/products/docs/pages/ai/host-skills.mdx b/fern/products/docs/pages/ai/host-skills.mdx index 2d2e07774f..29b3f2197a 100644 --- a/fern/products/docs/pages/ai/host-skills.mdx +++ b/fern/products/docs/pages/ai/host-skills.mdx @@ -4,19 +4,19 @@ description: Serve author-supplied agent skills from your Fern docs site and con 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. +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). Point `page-actions.options.skills.path` at a directory of skills in your docs repo, and Fern validates the bundle, generates the discovery manifest, and publishes it — so anyone can run `npx skills add https://`. You can also add an "Install skills" button to your docs UI that opens a modal with the install command and your skill list. - + -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. +Put your skills in a single directory, with each skill in its own subdirectory holding at least a `SKILL.md`. Supporting files (references, scripts) live alongside it. + +The directory can live anywhere in your repo. A common choice is a repo-root `.agents/skills/` folder, which doubles as the location local coding agents (Claude Code, Cursor, and others) read from: - - - - - + + + @@ -28,15 +28,18 @@ Place your skills in your `fern/` folder under `.well-known/agent-skills/` (the + + + -Each `SKILL.md` needs YAML frontmatter with `name` and `description`, following the [Agent Skills spec](https://agentskills.io): +Each `SKILL.md` needs YAML frontmatter with `name` and `description`, following the [Agent Skills spec](https://agentskills.io). The `name` must be kebab-case, at most 64 characters, and match its parent directory name: -```markdown title="fern/.well-known/agent-skills/plant-care/SKILL.md" +```markdown title=".agents/skills/plant-care/SKILL.md" --- name: plant-care description: Guide for diagnosing and treating common plant diseases. @@ -48,43 +51,36 @@ 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`. +Point `page-actions.options.skills.path` at your skills directory. The path resolves relative to the folder containing `docs.yml`, and `../` is allowed — so a `docs.yml` in `fern/` can reach a repo-root `.agents/skills/` directory: + +```yaml title="fern/docs.yml" +page-actions: + options: + skills: + path: ../.agents/skills +``` -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: +Fern discovers and publishes your skills during `fern generate --docs`. For every subdirectory containing a `SKILL.md`, it generates the `/.well-known/skills/index.json` discovery manifest and uploads the skill's files — nothing is written back to your repo. + +`fern check` validates the bundle at build time and blocks publishing on: -- A missing or unparseable `index.json` +- A declared path that doesn't exist or contains no skills - A `SKILL.md` whose `name` isn't kebab-case, exceeds 64 characters, or doesn't match its parent directory name - A `SKILL.md` with a missing or empty `description` (max 1,024 characters) +- Duplicate skill names across the directory +- A markdown reference that escapes the skill's directory (`../`), which would dangle once the skill is installed -Once published, skills are served at: +Once published, your 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) +- `https://your-docs-domain.com/.well-known/skills/index.json` (discovery manifest) +- `https://your-docs-domain.com/.well-known/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`). +For sites with a basepath like `/docs`, the endpoints live under that basepath (e.g., `https://example.com/docs/.well-known/skills/index.json`). @@ -98,25 +94,32 @@ 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. +Setting `page-actions.options.skills` already adds an "Install skills" button to the [page action bar](/learn/docs/configuration/site-level-settings#page-actions-configuration). The button opens a modal with a copyable install command and your skill list (read from the generated manifest). Customize the modal with `title`, `description`, and `learn-more-url`: -```yaml docs.yml +```yaml title="fern/docs.yml" page-actions: options: skills: + path: ../.agents/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. + learn-more-url: https://your-docs-domain.com/skills ``` + +By default the modal shows `npx skills add https://`. Override it with `install-command` when that command won't work as-is — for example auth-walled docs, a private registry, or a multi-step install: + +```yaml title="fern/docs.yml" +page-actions: + options: + skills: + path: ../.agents/skills + install-command: + - npm login --registry https://npm.your-org.com + - npx skills add https://your-docs-domain.com +``` + @@ -125,3 +128,7 @@ page-actions: Configure the Install skills button under `page-actions.options.skills` in `docs.yml`. + +## Legacy: hand-built `.well-known/skills/` + +Before `path` existed, you could serve skills by hand-populating a `.well-known/skills/` (or `.well-known/agent-skills/`) directory inside your `fern/` folder, complete with your own `index.json` manifest. Fern still uploads such a directory as-is when no `path` is declared, so existing setups keep working. Prefer `path`: it generates the manifest for you and validates the bundle. If you declare a `path` and also have a hand-built `fern/.well-known/skills/` folder, the declared path takes precedence and Fern warns about the conflict. diff --git a/fern/products/docs/pages/navigation/site-level-settings.mdx b/fern/products/docs/pages/navigation/site-level-settings.mdx index a317d9d765..6267615ab7 100644 --- a/fern/products/docs/pages/navigation/site-level-settings.mdx +++ b/fern/products/docs/pages/navigation/site-level-settings.mdx @@ -871,19 +871,15 @@ Toggle the built-in actions on or off with a boolean. **Copy Page** (`copy-page` ### 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. +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 and the list of available skills. Point `path` at a directory of skills in your repo and Fern publishes them and reads the modal's skill list from the generated manifest: ```yaml docs.yml page-actions: options: skills: + path: ../.agents/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 ``` diff --git a/fern/products/docs/snippets/install-skills-properties.mdx b/fern/products/docs/snippets/install-skills-properties.mdx index 0d71c56826..8377fd167d 100644 --- a/fern/products/docs/snippets/install-skills-properties.mdx +++ b/fern/products/docs/snippets/install-skills-properties.mdx @@ -2,6 +2,10 @@ Enables the "Install skills" page action and configures the modal it opens. Omit to hide it. + + Path to a directory of agent skills in this repo. Resolved relative to the folder containing `docs.yml`; `../` is allowed (e.g. a repo-root `.agents/skills/` directory that also serves local coding agents). Every subdirectory containing a `SKILL.md` is published as one skill: the CLI validates the bundle, generates the `/.well-known/skills/index.json` discovery manifest, and uploads every file so that `npx skills add https://` works. Nothing is written back to your repo. + + Overrides the modal title. @@ -14,14 +18,10 @@ 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. + 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. Set this when the generated command won't work as-is — for example auth-walled docs, a private registry, or a multi-step install. - 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. + List of skills displayed in the modal. Each entry has a `name` (required), `description` (optional), and `url` (optional link to the skill source). When `path` is set, or the site serves a `/.well-known/skills/index.json` (or `/.well-known/agent-skills/index.json`) manifest, the generated manifest replaces this hand-listed array. From f7c5ed043447a8c31315f297e13ef3764d2aa6ac Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Mon, 22 Jun 2026 11:50:54 -0400 Subject: [PATCH 2/2] remove legacy info --- fern/products/docs/pages/ai/host-skills.mdx | 4 ---- fern/products/docs/pages/changelog/2026-06-22.mdx | 9 +++++++++ 2 files changed, 9 insertions(+), 4 deletions(-) create mode 100644 fern/products/docs/pages/changelog/2026-06-22.mdx diff --git a/fern/products/docs/pages/ai/host-skills.mdx b/fern/products/docs/pages/ai/host-skills.mdx index 29b3f2197a..ae1bf7b44e 100644 --- a/fern/products/docs/pages/ai/host-skills.mdx +++ b/fern/products/docs/pages/ai/host-skills.mdx @@ -128,7 +128,3 @@ page-actions: Configure the Install skills button under `page-actions.options.skills` in `docs.yml`. - -## Legacy: hand-built `.well-known/skills/` - -Before `path` existed, you could serve skills by hand-populating a `.well-known/skills/` (or `.well-known/agent-skills/`) directory inside your `fern/` folder, complete with your own `index.json` manifest. Fern still uploads such a directory as-is when no `path` is declared, so existing setups keep working. Prefer `path`: it generates the manifest for you and validates the bundle. If you declare a `path` and also have a hand-built `fern/.well-known/skills/` folder, the declared path takes precedence and Fern warns about the conflict. diff --git a/fern/products/docs/pages/changelog/2026-06-22.mdx b/fern/products/docs/pages/changelog/2026-06-22.mdx new file mode 100644 index 0000000000..0a24694ecf --- /dev/null +++ b/fern/products/docs/pages/changelog/2026-06-22.mdx @@ -0,0 +1,9 @@ +--- +tags: ["ai"] +--- + +## Host agent skills from a directory in your repo + +The "Install skills" page action now accepts `page-actions.options.skills.path`, pointing at a skills directory in the same repo as your `docs.yml`. The CLI validates the bundle, generates the `/.well-known/skills/index.json` manifest, and publishes it so users can install with `npx skills add https://`. + +