> AI coding agents: see [/llms.txt](/llms.txt) for the full documentation index. Markdown version: [/docs/manual/zh/ai/skills.md](/docs/manual/zh/ai/skills.md).

---
title: Agent 技能
description: 从您的文档站点发布 Agent 技能，以便 AI 工具自动发现和安装。
navigation:
  icon: i-lucide-wand-sparkles
---

## 关于 Agent 技能

TockDocs 自动发现 `skills/` 目录中的技能，并在 `/.well-known/skills/` 下提供服务，遵循 [Cloudflare Agent Skills Discovery RFC](https://github.com/cloudflare/agent-skills-discovery-rfc)。这使得您的技能可以通过一条命令从任何文档 URL 安装。

[Agent Skills](https://agentskills.io/) 是一种轻量级、开放格式，用于为 AI Agent 提供专业知识和工作流。一个技能是一个包含 YAML frontmatter 的 `SKILL.md` 文件，描述 Agent 可以使用您的产品做什么，以及可选的支持参考文件。

::note
当 TockDocs 站点提供技能时，其目录会暴露在 `/.well-known/skills/index.json`。
::

## 快速开始

::steps

### 创建技能

在 TockDocs 项目根目录添加一个 `skills/` 目录，并在其中创建包含 `SKILL.md` 文件的技能子目录：

```bash
my-docs/
└── skills/
    └── my-product/
        └── SKILL.md
```

### 编写 SKILL.md

遵循 [agentskills.io 规范](https://agentskills.io/specification)。唯一必填的 frontmatter 字段是 `description`——`name` 默认使用目录名（如果省略）：

```md [skills/my-product/SKILL.md]
---
name: my-product
description: 使用 My Product 构建和部署应用。用于创建项目、配置设置或排查问题。
---

# My Product

## 快速开始

创建一个新项目：

\`\`\`bash
npx create-my-product my-app
\`\`\`
```

### 部署

部署您的文档。TockDocs 会自动在 `/.well-known/skills/` 下提供您的技能。

### 与用户分享

用户可以通过一条命令安装您的技能：

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

CLI 会检测已安装的 Agent（Claude Code、Cursor、Windsurf 等）并将技能安装到所有 Agent 中。
::

## 目录结构

技能目录可以包含 `SKILL.md` 之外的支持文件：

```bash
skills/
└── my-product/
    ├── SKILL.md              # 必填：指令 + 元数据
    ├── references/           # 可选：额外文档
    │   ├── api.md
    │   └── configuration.md
    ├── scripts/              # 可选：可执行代码
    │   └── setup.sh
    └── assets/               # 可选：模板、模式
        └── config.template.yaml
```

所有文件会自动在 `index.json` 目录中列出，并在 `/.well-known/skills/{skill-name}/` 下的相应路径提供。

::tip
将主 `SKILL.md` 保持在 500 行以内。将详细的参考材料移到 `references/` 中的单独文件——Agent 会按需加载，因此较小的文件意味着更少的上下文消耗。
::

## 配置

默认情况下，TockDocs 在项目根目录的 `skills/` 目录中查找技能。您可以在 `nuxt.config.ts` 中使用 `tockdocs.skills.dir` 更改此设置：

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  tockdocs: {
    skills: {
      dir: 'agent-skills',
    },
  },
})
```

## 技能名称要求

技能名称必须遵循 [Agent Skills 命名规范](https://agentskills.io/specification#name-field)：

- 1-64 个字符
- 仅限小写字母、数字和连字符（`a-z`、`0-9`、`-`）
- 不能以连字符开头或结尾
- 不能包含连续连字符（`--`）
- frontmatter 中的 `name` 字段必须与父目录名称匹配

::note
验证失败的技能将被跳过——请检查构建输出中的警告。
::

## 多个技能

您可以从单个文档站点发布多个技能：

```bash
skills/
├── my-product/
│   └── SKILL.md
├── create-project/
│   ├── SKILL.md
│   └── references/
│       └── templates.md
└── migration-guide/
    └── SKILL.md
```

所有技能都会出现在 `index.json` 目录中，并可以独立安装。

## 预览和版本控制

由于技能与您的文档一起存储在仓库中，因此它们可以受益于您现有的 Git 工作流：

- **分支预览**：在合并之前在预览部署上测试技能更改。在 Vercel 上，每个 Pull Request 都会获得一个预览 URL，您可以在其中验证技能是否正常工作：

```bash
npx skills add https://my-docs-git-feat-new-skill.vercel.app
```

- **版本控制**：使用 Git 历史跟踪技能更改，在 Pull Request 中审查差异，需要时回滚。
- **CI/CD**：技能随文档一起自动构建和部署——无需单独的发布步骤。

::tip
使用预览 URL 在发布到生产环境之前使用 AI 工具测试技能。这确保您的技能指令能正确与实际 Agent 配合使用。
::

## 发现机制

此功能实现了 [Cloudflare Agent Skills Discovery RFC](https://github.com/cloudflare/agent-skills-discovery-rfc)，该 RFC 扩展了 [RFC 8615](https://datatracker.ietf.org/doc/html/rfc8615)（与 ACME 证书验证和 `security.txt` 相同的 `.well-known` 标准）。

TockDocs 在构建时扫描您的 `skills/` 目录并生成两种类型的端点：

### 发现索引

```
GET /.well-known/skills/index.json
```

返回一个 JSON 目录，列出所有可用技能及其描述和文件：

```json
{
  "skills": [
    {
      "name": "my-product",
      "description": "使用 My Product 构建和部署应用。",
      "files": ["SKILL.md", "references/api.md"]
    }
  ]
}
```

### 技能文件

```
GET /.well-known/skills/{skill-name}/SKILL.md
GET /.well-known/skills/{skill-name}/references/api.md
```

单个技能文件以适当的内容类型提供（`.md` 文件为 `text/markdown`，`.json` 文件为 `application/json` 等）。

## 与 llms.txt 的对比

`llms.txt` 和 Agent Skills 都有助于 AI 工具使用您的文档，但它们服务于不同的目的：

|              | llms.txt                             | Agent Skills                                      |
| ------------ | ------------------------------------ | ------------------------------------------------- |
| **目的**     | 所有文档页面的目录                   | 功能摘要及可操作指令                               |
| **内容**     | 页面标题、描述和链接                 | 分步工作流、代码示例、约束条件                       |
| **加载时机** | 在发现时                             | 按需加载，技能被激活时                              |
| **格式**     | 带链接的纯文本                       | 带 YAML frontmatter 的 Markdown                   |
| **最适合**   | 帮助 Agent 查找信息                  | 教导 Agent 如何使用您的产品                         |

::tip
二者结合使用：`llms.txt` 告诉 Agent 在哪里查找信息，而技能告诉 Agent 他们可以完成什么以及如何完成。
::