Agent Skills

About Agent Skills

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 files like references and scripts.

Docus automatically discovers skills in your project 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.

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
\`\`\`

## Configuration

Configure your project in `config.ts`:

\`\`\`ts
export default {
  option: 'value'
}
\`\`\`

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

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.).

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

Preview and Versioning

Since skills live in your project 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.

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.

Comparison with llms.txt

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