Custom skills

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.

Write each SKILL.md

Each SKILL.md needs YAML frontmatter with name and description, following the Agent Skills spec:

1
---
2
name: plant-care
3
description: Guide for diagnosing and treating common plant diseases.
4
---
5
6
# Plant Care
7
8
When diagnosing a plant issue, check for...

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:

1
{
2
  "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
3
  "skills": [
4
    {
5
      "name": "plant-care",
6
      "type": "skill-md",
7
      "description": "Guide for diagnosing and treating common plant diseases.",
8
      "url": "/.well-known/agent-skills/plant-care/SKILL.md",
9
      "digest": "sha256:c4d5e6f7..."
10
    }
11
  ]
12
}

The legacy v0.1.0 manifest lists a files array per skill instead of url and digest.

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).

Install the skills

With the bundle published, anyone can install your skills with:

$
npx skills add https://your-docs-domain.com

The https:// scheme is required: a bare domain is treated as a GitHub repository shorthand.

Configure the Install skills button

Surface your skills in the docs UI by adding an “Install skills” button to the page action bar. 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.

1
page-actions:
2
  options:
3
    skills:
4
      title: Plant API Skills
5
      description: Skills for working with the Plant Store API.
6
      repository: https://github.com/your-org/plant-api-skills
7
      install-command: npx skills add https://your-docs-domain.com
8
      skills:
9
        - name: plant-care
10
          description: Guide for diagnosing and treating common plant diseases.
11
          url: https://github.com/your-org/plant-api-skills/tree/main/plant-care
12
        - name: garden-planner
13
          description: Plan garden layouts and planting schedules.