Agent Skills

About Agent Skills

Docus automatically discovers skills in your skills/ directory and serves them at /.well-known/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

All files are automatically listed in the index.json catalog and served at their respective paths under /.well-known/skills/{skill-name}/.

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/skills/index.json

Returns a JSON catalog listing all available skills with their descriptions and files:

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

Skill files

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

Individual skill files are served with appropriate content types (text/markdown for .md files, application/json for .json, etc.).

Comparison with llms.txt

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