Agent Skills

About Agent Skills

Docus automatically discovers skills in your skills/ directory and serves them at /.well-known/agent-skills/, following the Cloudflare Agent Skills Discovery RFC. This makes your skills installable from any documentation URL with a single command.

Agent Skills are a lightweight, open format for giving AI agents specialized knowledge and workflows. A skill is a SKILL.md file with YAML frontmatter that describes what agents can do with your product, along with optional supporting reference files.

Quick Start

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

Directory Structure

A skill directory can contain supporting files beyond SKILL.md:

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

Single-file skills are served as skill-md artifacts. Skills with supporting files are bundled as .tar.gz archives so agents can download the complete skill directory in one verified artifact.

Configuration

By default, Docus looks for skills in the skills/ directory at the root of your project. You can change this with docus.skills.dir in your nuxt.config.ts:

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

Skill Name Requirements

Skill names must follow the Agent Skills naming specification:

• 1-64 characters
• Lowercase letters, numbers, and hyphens only (a-z, 0-9, -)
• Must not start or end with a hyphen
• Must not contain consecutive hyphens (--)
• The name field in frontmatter must match the parent directory name

Multiple Skills

You can publish multiple skills from a single documentation site:

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

All skills appear in the index.json catalog and are independently installable.

Preview and Versioning

Since skills live in your repository alongside your documentation, they benefit from your existing Git workflow:

• Branch previews: Test skill changes on preview deployments before merging. On Vercel, every pull request gets a preview URL where you can verify your skills work correctly:

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

• Version control: Track skill changes with Git history, review diffs in pull requests, and roll back if needed.
• CI/CD: Skills are built and deployed automatically with your documentation — no separate publishing step.

How Discovery Works

This feature implements the Cloudflare Agent Skills Discovery RFC, which extends RFC 8615 (the same .well-known standard behind ACME certificate validation and security.txt).

Docus scans your skills/ directory at build time and generates two types of endpoints:

Discovery index

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

Returns a JSON catalog listing all available skills with their descriptions, artifact URLs, and SHA-256 digests:

{
  "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
  "skills": [
    {
      "name": "my-product",
      "type": "archive",
      "description": "Build and deploy apps with My Product.",
      "url": "/.well-known/agent-skills/my-product.tar.gz",
      "digest": "sha256:c4d5e6f7..."
    }
  ]
}

Skill artifacts

GET /.well-known/agent-skills/{skill-name}/SKILL.md
GET /.well-known/agent-skills/{skill-name}.tar.gz

Skills that only contain SKILL.md are served directly with type: "skill-md" and text/markdown. Skills with references/, scripts/, assets/, or other support files are served as type: "archive" with application/gzip.

Comparison with llms.txt

Both llms.txt and Agent Skills help AI tools work with your documentation, but they serve different purposes: