Agent 技能

关于 Agent 技能

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

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

快速开始

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

---
name: my-product
description: 使用 My Product 构建和部署应用。用于创建项目、配置设置或排查问题。
---

# My Product

## 快速开始

创建一个新项目：

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

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

目录结构

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

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

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

配置

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

export default defineNuxtConfig({
  tockdocs: {
    skills: {
      dir: 'agent-skills',
    },
  },
})

技能名称要求

技能名称必须遵循 Agent Skills 命名规范：

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

多个技能

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

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

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

预览和版本控制

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

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

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

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

发现机制

此功能实现了 Cloudflare Agent Skills Discovery RFC，该 RFC 扩展了 RFC 8615（与 ACME 证书验证和 security.txt 相同的 .well-known 标准）。

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

发现索引

GET /.well-known/skills/index.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 工具使用您的文档，但它们服务于不同的目的：