自定义技能

组织文件结构

将技能放置在 fern/ 目录下的 .well-known/agent-skills/（当前 v0.2.0 规范）或 .well-known/skills/（旧版 v0.1.0 布局）中。两者都受支持且可以共存。每个技能是一个子目录，至少包含一个 SKILL.md，可选的支持文件放在旁边。

编写每个 SKILL.md

每个 SKILL.md 需要包含 name 和 description 的 YAML 前置数据，遵循 Agent Skills 规范：

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

添加发现清单

技能目录根目录下的 index.json 是必需的。它列出所有技能，以便客户端可以通过单个请求发现它们，通过 url 和 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
}

旧版 v0.1.0 清单为每个技能列出 files 数组，而非 url 和 digest。

发布

Fern 在 fern generate --docs 期间上传文件包并按原样提供文件 — 无需 docs.yml 配置。fern check 在上传时验证文件包，标记以下问题：

• 缺失或无法解析的 index.json
• SKILL.md 的 name 不是 kebab-case、超过 64 个字符，或与其父目录名称不匹配
• SKILL.md 缺少 description 或 description 为空（最多 1,024 个字符）

发布后，技能可通过以下地址访问：

• https://your-docs-domain.com/.well-known/agent-skills/index.json（发现清单）
• https://your-docs-domain.com/.well-known/agent-skills/<skill-name>/SKILL.md（单个技能）
• https://your-docs-domain.com/.well-known/skills/index.json（旧版 v0.1.0 清单）

对于具有基础路径（如 /docs）的站点，端点位于该基础路径下（例如 https://example.com/docs/.well-known/agent-skills/index.json）。

安装技能

文件包发布后，任何人都可以通过以下命令安装您的技能：

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

https:// 协议前缀是必需的：裸域名会被视为 GitHub 仓库简写。

配置安装技能按钮

通过在页面操作栏中添加”安装技能”按钮来在文档 UI 中展示您的技能。在 docs.yml 中设置 page-actions.options.skills，按钮会打开一个弹窗，包含可复制的安装命令、可用技能列表以及可选的源仓库链接。

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.