Agent Skills

Docd automatically discovers skills in your skills/ directory and serves them at /.well-known/skills/, following the Cloudflare Agent Skills Discovery RFC. Any documentation URL becomes an installable skill endpoint.

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

Quick Start

Create a skill

Add a skills/ directory at the root of your project with a subdirectory for each skill containing a SKILL.md file:

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

Write your SKILL.md

The only required frontmatter field is description. The name field defaults to the directory name if omitted:

Skills My Product SKILL

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

Deploy

Deploy your documentation. Docd automatically serves your skills at /.well-known/skills/ — no extra configuration needed.

Share with users

Users install your skill with a single command pointing at your docs URL:

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

The CLI detects installed agents (Claude Code, Cursor, Windsurf, and others) and installs to all of them.

Directory structure

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

skills/
└── my-product/
    ├── SKILL.md              # Required: frontmatter + instructions
    ├── references/           # Optional: detailed reference docs
    │   ├── api.md
    │   └── configuration.md
    ├── scripts/              # Optional: executable helpers
    │   └── setup.sh
    └── assets/               # Optional: templates, schemas
        └── config.template.yaml

All files are catalogued in index.json and served at /.well-known/skills/{skill-name}/{file}.

Configuration

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

Nuxt Config

export default defineNuxtConfig({
  docd: {
    skills: {
      dir: "agent-skills",
    },
  },
})

If the configured directory does not exist, the skills module is silently skipped — nothing breaks if you have not created skills yet.

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.

Supported file types

Docd serves skill files with appropriate content types:

Hidden files (names starting with .) are automatically excluded from the catalog.

How discovery works

Docd scans your skills/ directory at build time and registers two server routes.

Discovery index

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

Returns a JSON catalog of all available skills:

{
  "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 files are served with a one-hour cache header and path traversal protection built in.

All routes are prerendered at build time, so skills are available on static hosts with no server required.

Comparison with llms.txt and MCP