From 12859840f83e448c078154504d280c3f52641b07 Mon Sep 17 00:00:00 2001 From: Naman Anand Date: Tue, 3 Nov 2026 20:18:43 +0530 Subject: [PATCH] Document the fern-spec, fern-sdks, and fern-workflows skills The fern-api/skills repository ships four skills, but the docs only surfaced fern-docs. The other three were unreachable from the docs: a reader with an OpenAPI spec, an SDK config, or a CI workflow had no way to discover that a skill covers their task. - Add an "Other Fern skills" section to the agent skills page listing fern-spec, fern-sdks, and fern-workflows, with the install command and the no---skill form that installs all four. - List the three skills in the "Install agent skills" page action in docs.yml, so the toolbar offers them alongside fern-docs. - Add the two references the fern-docs table was missing, quickstart-openapi.md and translations.md, both of which exist in the skills repo. Descriptions are taken from each SKILL.md. The zh translation is left to sync-translations. Co-Authored-By: Claude Opus 5 --- fern/docs.yml | 20 ++++++++++++++- fern/products/docs/pages/ai/agent-skills.mdx | 26 +++++++++++++++++++- 2 files changed, 44 insertions(+), 2 deletions(-) diff --git a/fern/docs.yml b/fern/docs.yml index 2ee032f0ff..50e21cbac8 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -180,7 +180,7 @@ page-actions: options: skills: title: Install agent skills - description: Skills for authoring Fern documentation, maintained in our open-source skills repo. + description: Skills for building with Fern across docs, OpenAPI specs, SDKs, and CI, maintained in our open-source skills repo. learn-more-url: https://buildwithfern.com/learn/docs/ai-features/agent-skills repository: https://github.com/fern-api/skills install-command: npx skills add fern-api/skills @@ -190,6 +190,24 @@ page-actions: Author and edit Fern documentation: MDX pages, navigation, docs.yml config, custom components, landing pages, and changelog entries. url: https://github.com/fern-api/skills/tree/main/skills/fern-docs + - name: fern-spec + description: >- + Author and tune the OpenAPI spec Fern consumes: operationId and + schema hygiene, x-fern-* extensions, overlays versus overrides, + auth and servers, and spec sync. + url: https://github.com/fern-api/skills/tree/main/skills/fern-spec + - name: fern-sdks + description: >- + Configure and generate Fern SDKs: generators.yml, auth schemes, + environments, .fernignore for custom code, and common generation + failures. + url: https://github.com/fern-api/skills/tree/main/skills/fern-sdks + - name: fern-workflows + description: >- + Set up CI/CD that runs the Fern CLI: fern check on pull requests, + docs previews and publishes, SDK releases, and handling FERN_TOKEN + safely. + url: https://github.com/fern-api/skills/tree/main/skills/fern-workflows settings: http-snippets: diff --git a/fern/products/docs/pages/ai/agent-skills.mdx b/fern/products/docs/pages/ai/agent-skills.mdx index bb14fd4f2f..9f565641bf 100644 --- a/fern/products/docs/pages/ai/agent-skills.mdx +++ b/fern/products/docs/pages/ai/agent-skills.mdx @@ -1,6 +1,6 @@ --- title: Skills for using Fern Docs -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 to teach coding agents how to author and edit Fern Docs sites, plus the Fern skills for OpenAPI specs, SDKs, and CI. availability: beta --- @@ -76,10 +76,34 @@ The skill routes agents to task-specific guides in a `references/` directory. Th | Reference | Loaded when | |-----------|-------------| +| `references/quickstart-openapi.md` | Turning an OpenAPI spec into a published docs site, including which publish command to use with and without a Fern account. | | `references/changelog.md` | Writing or editing a changelog entry. | | `references/products.md` | Setting up a product switcher, adding a product, or refactoring navigation into the products format. | | `references/redirects.md` | Moving, renaming, or deleting a page, or any edit that changes a published URL. | | `references/authentication.md` | Restricting pages or content by role (RBAC), or wiring docs into an auth method (password, SSO, JWT, OAuth). | | `references/snippets.md` | Editing the same content across multiple pages, or adding generic/boilerplate content. | +| `references/translations.md` | Adding or updating a translated version of the site. | An agent writing a changelog entry loads `references/changelog.md` and skips the rest, keeping context small. + +## Other Fern skills + +The [`fern-api/skills`](https://github.com/fern-api/skills) repository ships three more skills covering the rest of a Fern project. Each is structured the same way: a `SKILL.md` index that routes to a task-specific reference. + +| Skill | Covers | +|-------|--------| +| [`fern-spec`](https://www.skills.sh/fern-api/skills/fern-spec) | Authoring and tuning the OpenAPI spec Fern consumes: `operationId` and schema hygiene, `x-fern-*` extensions, overlays versus overrides, auth and servers, and spec sync with `fern api update`. | +| [`fern-sdks`](https://www.skills.sh/fern-api/skills/fern-sdks) | Configuring and generating SDKs: `generators.yml`, auth schemes, environments, `.fernignore` and Replay for custom code, and common generation failures. | +| [`fern-workflows`](https://www.skills.sh/fern-api/skills/fern-workflows) | CI/CD that runs the Fern CLI: `fern check` on pull requests, docs previews and production publishes, SDK releases with pinned CLI and generator versions, and handling `FERN_TOKEN` and registry secrets safely. | + +Install any of them by swapping the `--skill` value: + +```bash +npx skills add fern-api/skills --skill fern-spec -a claude-code +``` + +To install every Fern skill at once, omit `--skill`: + +```bash +npx skills add fern-api/skills +```