chore(docs): drop removed skills repository field and document skills path#5905
Draft
matlegault wants to merge 2 commits into
Draft
chore(docs): drop removed skills repository field and document skills path#5905matlegault wants to merge 2 commits into
matlegault wants to merge 2 commits into
Conversation
… 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) <noreply@anthropic.com>
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
|
|
||
| <Markdown src="/products/docs/snippets/install-skills-properties.mdx" /> | ||
|
|
||
| ## Legacy: hand-built `.well-known/skills/` |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Headings] 'Legacy: hand-built *******************' should use sentence-style capitalization.
|
|
||
| <Markdown src="/products/docs/snippets/install-skills-properties.mdx" /> | ||
|
|
||
| ## Legacy: hand-built `.well-known/skills/` |
Contributor
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Microsoft.HeadingColons] Capitalize ': h'.
| </ParamField> | ||
|
|
||
| <ParamField path="page-actions.options.skills.path" type="string" required={false} toc={true}> | ||
| 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://<your-docs-domain>` works. Nothing is written back to your repo. |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Acronyms] 'SKILL' has no definition.
Contributor
|
🌿 Preview your docs: https://fern-preview-matlegault-skills-path-config-docs.docs.buildwithfern.com/learn Here are the markdown pages you've updated: |
devalog
approved these changes
Jun 22, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Blocked on fern-api/fern#16510 — keep as draft until it merges + releases.
That PR reworks the docs-site Agent Skills feature: it removes
page-actions.options.skills.repository, makes the skills config schema strict (additionalProperties: false), and addspage-actions.options.skills.path(the CLI discovers a same-repo skills directory, validates the bundle, generates the.well-known/skills/index.jsonmanifest, and publishes it). As of opening this PR, #16510 is open/unreleased — the changelog entry sits inchanges/unreleased/feat-skills-declared-path.ymland the latest published CLI (fern-api@5.50.4) does not include it.This PR is staged and
fern checkpasses today, so it's a fast flip once #16510 ships.Changes
fern/docs.yml— drop therepository:line (it pointed at the external skills repo). Kepttitle,description,learn-more-url, the manualskills:array, andinstall-command: npx skills add fern-api/skills. Not migrating our own config topathhere — that's a separate decision (we still install from the externalfern-api/skillsrepo).host-skills.mdx— reworked to recommend declaringpage-actions.options.skills.path. Documents thatpathresolves relative to the folder containingdocs.ymland../is allowed (e.g. a repo-root.agents/skills/that also serves local coding agents), that the CLI validates/bundles/publishes sonpx skills add https://<domain>works, and the validation rules.install-commandis documented as the override for auth-walled docs / private registries / multi-step installs. The hand-built.well-known/skills/convention is demoted to a legacy fallback note.install-skills-properties.mdx— added thepathParamField, removed therepositoryParamField.site-level-settings.mdx— "Install skills action" example now usespath; removedrepository.Remaining step at release
No manual version bump in this PR — the scheduled
🌿 Upgrade Fern CLIbot bumpsfern/fern.config.jsononmain. Before merging, confirm the CLI onmainis the released version that contains #16510 (its changelog should show thefeat-skills-declared-path/ skills-path entry), then mark ready and merge.Verification
fern check→ 0 errors, 6 pre-existing warnings unrelated to skills (API path conflicts, FDR redirect network check, color contrast).🤖 Generated with Claude Code