Repository navigation
Document the fern-spec, fern-sdks, and fern-workflows skills - #7737
Conversation
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 <noreply@anthropic.com>
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
| |-------|--------| | ||
| | [`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. | |
There was a problem hiding this comment.
📝 [vale] <FernStyles.Adverbs> reported by reviewdog 🐶
Remove 'safely' if it's not important to the meaning of the statement.
| | [`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. | | |
| | [`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 . | |
|
🌿 Preview your docs: https://fern-preview-docs-guest-publish-and-skills.docs.buildwithfern.com/learn Here are the markdown pages you've updated: |
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
| | [`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. | |
There was a problem hiding this comment.
🟡 Skill summaries omit related guides
Readers exploring fern-spec or fern-sdks get no links to Fern's overlays, overrides, or custom-code guides. Those topics already have dedicated pages, but the skill links lead outside the documentation.
Learn more
The repository requires cross-references when newly written content names concepts documented elsewhere. These summaries name overlays, overrides, and SDK custom code, but only link to external skill listings. The guides are already available in the OpenAPI navigation and custom-code guide.
Example: A reader comparing OpenAPI overlays with overrides can reach the fern-spec listing but cannot reach Fern's detailed guides from this summary.
Recommended fix: Add natural inline links for the mentioned concepts to /learn/api-definitions/openapi/overlays, /learn/api-definitions/openapi/overrides, and /learn/sdks/overview/custom-code, as appropriate; keep the skill links intact.
Was this helpful? React with 👍 or 👎 to provide feedback.
Problem
The
fern-api/skillsrepository ships four skills, but the docs only surfacefern-docs:fern-docsfern-specfern-sdksfern-workflowsgrep -rn "fern-spec\|fern-sdks\|fern-workflows" fern/returned nothing onmain. A reader with an OpenAPI spec, agenerators.yml, or a CI workflow had no way to discover that a skill covers their task — including from the Install agent skills toolbar, which offered onlyfern-docs.Changes
agent-skills.mdx— new "Other Fern skills" section listingfern-spec,fern-sdks, andfern-workflows, with the--skillinstall form and the barenpx skills add fern-api/skillsform that installs all four.docs.yml— the three skills added topage-actions.options.skills, so the toolbar offers them too. The action's description broadened from "authoring Fern documentation" to cover specs, SDKs, and CI.agent-skills.mdxreferences table — addedquickstart-openapi.mdandtranslations.md, which exist in the skills repo but were missing from the table.Skill descriptions are condensed from each
SKILL.md, not invented.Verification
fern check→ 0 errors. The 10 warnings are pre-existing onmain(API schema warnings, the unauthenticated redirects check, and the site's own accent contrast); none reference the changed files.skills.sh/fern-api/skills/{fern-docs,fern-sdks,fern-spec,fern-workflows}and the three GitHubtree/main/skills/*links.docs.ymlparses, andpage-actions.options.skills.skillslists all four names.Not verified: Vale isn't installed locally, so the prose lint runs for the first time in CI here. No visual check of the rendered page or the page-action toolbar.
Notes for the reviewer
zhtranslation ofagent-skills.mdxis deliberately untouched —sync-translations.ymlowns it.docs-commands.mdxalready documents--guest,--new-session,fern/.guest-session, andfern claim, and the quickstart is already guest-first after Quickstart: align agent notes with guest-first CLI behavior #7728.🤖 Generated with Claude Code