Agent Skills

关于 Agent Skills

Docus 会自动发现 skills/ 目录中的 skills，并根据 Cloudflare Agent Skills Discovery RFC 将它们提供到 /.well-known/skills/。这样用户就可以用一条命令从任意文档 URL 安装你的 skills。

Agent Skills 是一种轻量、开放的格式，用于为 AI agents 提供专门知识和工作流。一个 skill 是带有 YAML frontmatter 的 SKILL.md 文件，用来描述 agents 可以用你的产品完成什么，也可以附带可选的参考文件。

快速开始

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

---
name: my-product
description: Build and deploy apps with My Product. Use when creating projects, configuring settings, or troubleshooting issues.
---

# My Product

## Getting Started

Create a new project:

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

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

目录结构

除了 SKILL.md，skill 目录还可以包含支持文件：

skills/
└── my-product/
    ├── SKILL.md              # Required: instructions + metadata
    ├── references/           # Optional: additional documentation
    │   ├── api.md
    │   └── configuration.md
    ├── scripts/              # Optional: executable code
    │   └── setup.sh
    └── assets/               # Optional: templates, schemas
        └── config.template.yaml

所有文件都会自动列入 index.json 目录，并在 /.well-known/skills/{skill-name}/ 下通过各自路径提供。

配置

默认情况下，Docus 会在项目根目录的 skills/ 目录中查找 skills。你可以在 nuxt.config.ts 中通过 docus.skills.dir 修改：

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

Skill 名称要求

Skill 名称必须遵循 Agent Skills naming specification：

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

多个 Skills

你可以从同一个文档站点发布多个 skills：

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

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

预览和版本管理

由于 skills 与文档一起保存在仓库中，它们可以直接受益于现有 Git 工作流：

• 分支预览：合并前在预览部署中测试 skill 改动。在 Vercel 上，每个 pull request 都会获得一个预览 URL，你可以用它验证 skills 是否正常工作：

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

• 版本控制：通过 Git 历史跟踪 skill 改动，在 pull requests 中审阅 diff，并在需要时回滚。
• CI/CD：Skills 会随文档自动构建和部署，无需单独发布步骤。

发现机制如何工作

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

Docus 会在构建时扫描 skills/ 目录，并生成两类 endpoints：

发现索引

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

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

{
  "skills": [
    {
      "name": "my-product",
      "description": "Build and deploy apps with My Product.",
      "files": ["SKILL.md", "references/api.md"]
    }
  ]
}

Skill 文件

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

独立 skill 文件会以合适的 content type 提供（.md 文件使用 text/markdown，.json 使用 application/json 等）。

与 llms.txt 对比

llms.txt 和 Agent Skills 都能帮助 AI 工具使用你的文档，但目的不同：