> AI coding agents: see [/llms.txt](/llms.txt) for the full documentation index. Markdown version: [/docs/manual/en/ai/skills.md](/docs/manual/en/ai/skills.md).

---
title: Agent Skills
description: Publish agent skills from your documentation site so AI tools can discover and install them automatically.
navigation:
  icon: i-lucide-wand-sparkles
---

## About Agent Skills

TockDocs automatically discovers skills in your `skills/` directory and serves them at `/.well-known/skills/`, following the [Cloudflare Agent Skills Discovery RFC](https://github.com/cloudflare/agent-skills-discovery-rfc). This makes your skills installable from any documentation URL with a single command.

[Agent Skills](https://agentskills.io/) 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.

::note
When a TockDocs site ships skills, its catalog is exposed at `/.well-known/skills/index.json`.
::

## Quick Start

::steps

### Create a skill

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

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

### Write your SKILL.md

Follow the [agentskills.io specification](https://agentskills.io/specification). The only required frontmatter field is `description` — `name` defaults to the directory name if omitted:

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

### Deploy

Deploy your documentation. TockDocs automatically serves your skills at `/.well-known/skills/`.

### Share with users

Users can install your skills with a single command:

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

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

## Directory Structure

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

```bash
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}/`.

::tip
Keep your main `SKILL.md` under 500 lines. Move detailed reference material to separate files in `references/` — agents load these on demand, so smaller files mean less context usage.
::

## Configuration

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

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  tockdocs: {
    skills: {
      dir: 'agent-skills',
    },
  },
})
```

## Skill Name Requirements

Skill names must follow the [Agent Skills naming specification](https://agentskills.io/specification#name-field):

- 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

::note
Skills that fail validation are skipped — check your build output for warnings.
::

## Multiple Skills

You can publish multiple skills from a single documentation site:

```bash
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:

```bash
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.

::tip
Use preview URLs to test skills with your AI tools before shipping to production. This ensures your skill instructions work correctly with real agents.
::

## How Discovery Works

This feature implements the [Cloudflare Agent Skills Discovery RFC](https://github.com/cloudflare/agent-skills-discovery-rfc), which extends [RFC 8615](https://datatracker.ietf.org/doc/html/rfc8615) (the same `.well-known` standard behind ACME certificate validation and `security.txt`).

TockDocs 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:

```json
{
  "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:

|              | llms.txt                             | Agent Skills                                       |
| ------------ | ------------------------------------ | -------------------------------------------------- |
| **Purpose**  | Directory of all documentation pages | Capability summary with actionable instructions    |
| **Content**  | Page titles, descriptions, and links | Step-by-step workflows, code examples, constraints |
| **Loaded**   | At discovery time                    | On demand, when the skill is activated             |
| **Format**   | Plain text with links                | Markdown with YAML frontmatter                     |
| **Best for** | Helping agents find information      | Teaching agents how to use your product            |

::tip
Use both together: `llms.txt` tells agents where to find information, while skills tell agents what they can accomplish and how.
::