Oxidoc Skills for AI Agents

AI coding agents like Claude Code, Codex, and Cursor have no built-in knowledge of Oxidoc. These ready-made skills give them everything they need to create, edit, and build Oxidoc sites.

These skills follow the Agent Skills open standard — a SKILL.md file with YAML frontmatter that works across multiple AI tools.

How to Use

Save the skill as a SKILL.md file inside your skills directory:

# Personal (all projects)
mkdir -p ~/.claude/skills/oxidoc
# then save as ~/.claude/skills/oxidoc/SKILL.md

# Project-scoped
mkdir -p .claude/skills/oxidoc
# then save as .claude/skills/oxidoc/SKILL.md

Claude will automatically load the skill when relevant, or you can invoke it directly with /oxidoc.

Save the skill as a SKILL.md file inside the skills directory:

# Project-scoped
mkdir -p .cursor/skills/oxidoc
# then save as .cursor/skills/oxidoc/SKILL.md

# Personal (all projects)
mkdir -p ~/.cursor/skills/oxidoc
# then save as ~/.cursor/skills/oxidoc/SKILL.md

Also discovers skills from .agents/skills/ and .claude/skills/.

Save the skill as a SKILL.md file inside the .agents/skills/ directory:

# Project-scoped
mkdir -p .agents/skills/oxidoc
# then save as .agents/skills/oxidoc/SKILL.md

# Personal (all repos)
mkdir -p ~/.agents/skills/oxidoc
# then save as ~/.agents/skills/oxidoc/SKILL.md

Codex automatically detects skill changes — no restart needed.

Save the skill as a SKILL.md file inside the skills directory:

# Project-scoped
mkdir -p .windsurf/skills/oxidoc
# then save as .windsurf/skills/oxidoc/SKILL.md

# Personal (all workspaces)
mkdir -p ~/.codeium/windsurf/skills/oxidoc
# then save as ~/.codeium/windsurf/skills/oxidoc/SKILL.md

Also discovers skills from .agents/skills/ and .claude/skills/.

Most AI coding agents that support the Agent Skills standard use .agents/skills/ as the common directory:

mkdir -p .agents/skills/oxidoc
# then save as .agents/skills/oxidoc/SKILL.md

For tools without skills support, paste the content into the system prompt or project instructions.

Full Oxidoc Skill

This single skill covers the CLI, RDX syntax, configuration, and components. For most projects, this is all you need.

Full Oxidoc Skill — click to expand

SKILL.mdmarkdown

---
name: oxidoc
description: Complete guide to the Oxidoc documentation engine — CLI, RDX content format, components, configuration, theming, and project structure. Use when creating, editing, configuring, or building Oxidoc documentation sites.
---

# Oxidoc Documentation Engine

## Overview

Oxidoc generates static documentation sites from `.rdx` files (Markdown with embedded components). Single Rust binary, zero Node.js dependency.

**Keywords**: oxidoc, documentation, static site, rdx, components, configuration, theming, CLI, build

## CLI

```
oxidoc init [name]              New project (-f force, -y skip prompts)
oxidoc dev [-p port]            Dev server + hot reload (default: 3000)
oxidoc build [-o dir]           Production build (default: dist/)
oxidoc clean                    Remove .oxidoc-dev/ and dist/
oxidoc archive create|list|delete <ver>   Version snapshots
oxidoc update [--pre]           Update binary
oxidoc set-version <ver>        Pin specific version
```

Global flags: `-C <path>` project dir, `-v` verbose, `-q` quiet.

## RDX Content Format

Files use `.rdx` extension (NOT `.md` or `.mdx`). YAML frontmatter + Markdown + components.

### Frontmatter

Every `.rdx` page requires `title` and `description`:

```yaml
---
title: Page Title
description: Meta description for SEO (150-160 chars)
layout: landing  # Optional: full-width, no sidebar — for landing/marketing pages
---
```

### Components

All components use PascalCase.

**Code blocks**: Always prefer native fenced code blocks (` ```lang `) over `<CodeBlock>`. Only use the `<CodeBlock>` component when you need the `filename`, `highlight`, or `line_numbers` props.

| Component | Usage |
|-----------|-------|
| Callout | `<Callout kind="info\|warning\|error\|tip" title="T">text</Callout>` (aliases: `error`=`danger`, `tip`=`success`) |
| Tabs | `<Tabs><Tab title="A">content</Tab><Tab title="B">content</Tab></Tabs>` |
| CodeBlock | `<CodeBlock language="rust" filename="main.rs" highlight="2">code</CodeBlock>` (only when you need filename/highlight/line_numbers) |
| Accordion | `<Accordion title="Label">hidden content</Accordion>` |
| CardGrid | `<CardGrid><Card title="T" icon="icon" href="/url">desc</Card></CardGrid>` |
| Steps | `<Steps><Step title="First">content</Step></Steps>` |
| Badge | `<Badge variant="new\|deprecated\|tip\|warning\|danger">label</Badge>` |
| Tag | `<Tag variant="new\|experimental\|deprecated">label</Tag>` |
| Tooltip | `<Tooltip text="Explanation">hover text</Tooltip>` |
| Banner | `<Banner id="unique" persist="none\|session\|forever">text</Banner>` |
| ThemedImage | `<ThemedImage light="/l.png" dark="/d.png" alt="Alt" />` |
| Head | `<Head><meta property="og:image" content="/img.png"></Head>` |
| Mermaid | Use fenced code block with `mermaid` language |

### Landing Page Components

Set `layout: landing` in frontmatter (full-width, no sidebar), then use:

| Component | Usage |
|-----------|-------|
| Hero | `<Hero title="Name"><HeroAction label="CTA" href="/url" variant="primary\|secondary" />Tagline.</Hero>` |
| Section | `<Section bg="muted">content</Section>` |
| FeatureGrid | `<FeatureGrid><Feature icon="icon" title="T">desc</Feature></FeatureGrid>` |
| CTA | `<CTA title="T" description="D"><HeroAction label="Go" href="/url" variant="primary" /></CTA>` |
| TestimonialGrid | `<TestimonialGrid><Testimonial name="N" role="R">quote</Testimonial></TestimonialGrid>` |

## Configuration (oxidoc.toml)

### Required

```toml
[project]
name = "Project Name"

[routing.root]
homepage = "home.rdx"

[routing]
navigation = [
  { path = "/docs", dir = "docs", groups = [
    { group = "Getting Started", pages = ["quickstart", "guide"] },
  ] },
]
```

### All Sections

| Section | Key fields |
|---------|------------|
| `[project]` | name, description, logo, favicon, base_url, edit_url, edit_label |
| `[theme]` | primary, accent, font, code_font, dark_mode (`"system"\|"light"\|"dark"`), custom_css |
| `[routing.root]` | homepage, pages |
| `[routing]` | header_links `[{label, href}]`, navigation `[{path, dir, groups, openapi}]` |
| `[search]` | provider (`"oxidoc"\|"algolia"\|"typesense"\|"meilisearch"\|"custom"`), semantic |
| `[versioning]` | default, versions |
| `[i18n]` | default_locale, locales, translation_dir |
| `[footer]` | copyright_owner, copyright_owner_url, links `[{label, href}]` |
| `[social]` | github, discord, twitter, mastodon |
| `[analytics]` | google_analytics, script |
| `[redirects]` | redirects `[{from, to}]` |
| `[components.custom]` | `TagName = "path/to/file.js"` |
| `[attribution]` | oxidoc (bool, default true) |

### Navigation Rules

- `path` = URL prefix (e.g., `"/docs"`), `dir` = content directory containing `.rdx` files
- `pages` = list of slugs — the filename without `.rdx` (e.g., `"quickstart"` → `docs/quickstart.rdx`)
- `groups` = sidebar sections with `group` (display title) and `pages` (slug list)
- `openapi` = path to an OpenAPI/Swagger spec file — Oxidoc auto-generates interactive API reference pages from it
- Pages only appear in the sidebar if listed in a navigation group
- Nested slugs: `"guides/styling"` maps to `docs/guides/styling.rdx`

## Theming

### Quick theming via oxidoc.toml

Set colors and fonts in `[theme]`. For deeper customization, create a CSS file and register it:

```toml
[theme]
primary = "#3b82f6"
accent = "#f59e0b"
dark_mode = "system"  # controls toggle: "system", "light", or "dark"
custom_css = ["assets/custom.css"]  # path relative to project root
```

The CSS file goes in `assets/` (e.g., `assets/custom.css`). Everything in `assets/` is copied to `dist/` on build.

### CSS variable overrides

All built-in styles use `@layer oxidoc`, so your custom CSS always wins — no `!important` needed. Override variables in `:root` (or scope to dark mode with `[data-theme="dark"]`):

```css
/* assets/custom.css */
:root {
  --oxidoc-primary: #2563eb;
  --oxidoc-accent: #f59e0b;
}
[data-theme="dark"] {
  --oxidoc-primary: #3b82f6;
}
```

| Category | Variables |
|----------|-----------|
| Core | `--oxidoc-primary`, `--oxidoc-accent`, `--oxidoc-bg`, `--oxidoc-bg-secondary`, `--oxidoc-text`, `--oxidoc-text-secondary`, `--oxidoc-border`, `--oxidoc-code-bg` |
| Semantic | `--oxidoc-success`, `--oxidoc-warning`, `--oxidoc-error`, `--oxidoc-info`, `--oxidoc-new`, `--oxidoc-deprecated` (each has `-text` variant) |
| Typography | `--oxidoc-font-sans`, `--oxidoc-font-mono` |
| Layout | `--oxidoc-content-max` (48rem), `--oxidoc-sidebar-width` (16rem), `--oxidoc-toc-width` (14rem), `--oxidoc-header-height` (3.5rem) |

## Project Structure

```
project/
├── oxidoc.toml        # Site configuration (required)
├── home.rdx           # Landing page (layout: landing)
├── assets/            # Static files — copied as-is to dist/ on build
│   ├── logo.svg       #   referenced in config as "/assets/logo.svg"
│   └── custom.css     #   registered via [theme] custom_css
├── docs/              # Content directory (matches routing dir)
│   ├── intro.rdx      #   slug: "intro"
│   └── advanced/
│       └── plugins.rdx  # slug: "advanced/plugins"
└── i18n/              # Translation files (if i18n enabled)
    └── en.ftl
```

## Build Output

`oxidoc build` produces in `dist/`: static HTML, Wasm islands, search index, sitemap.xml, robots.txt, feed.xml, llms.txt, llms-full.txt.

Skill: RDX Content Writer

Focused on writing .rdx content pages. Use this when you only need the agent to create or edit documentation content, not configure the site.

RDX Content Writer Skill — click to expand

SKILL.mdmarkdown

---
name: rdx-content-writer
description: Write and edit RDX content pages for Oxidoc — covers frontmatter, Markdown, embedded components, and SEO. Use when creating or editing .rdx documentation files.
---

# RDX Content Writing

## Overview

RDX files are Markdown with YAML frontmatter and embedded components. Extension: `.rdx` (NOT `.md` or `.mdx`).

**Keywords**: rdx, content, markdown, components, frontmatter, SEO, documentation pages

## Frontmatter

Every `.rdx` page requires `title` and `description`:

```yaml
---
title: Page Title — Descriptive Hook | Brand
description: 150-160 char meta description with action verb and CTA.
layout: landing  # Optional: full-width, no sidebar — for landing/marketing pages
---
```

## Components

All components use PascalCase.

**Code blocks**: Always prefer native fenced code blocks (` ```lang `) over `<CodeBlock>`. Only use the `<CodeBlock>` component when you need the `filename`, `highlight`, or `line_numbers` props.

| Component | Usage |
|-----------|-------|
| Callout | `<Callout kind="info\|warning\|error\|tip" title="T">text</Callout>` (aliases: `error`=`danger`, `tip`=`success`) |
| Tabs | `<Tabs><Tab title="A">content</Tab></Tabs>` |
| CodeBlock | `<CodeBlock language="rust" filename="main.rs" highlight="2">code</CodeBlock>` (only when you need filename/highlight/line_numbers) |
| Accordion | `<Accordion title="Label">hidden content</Accordion>` |
| CardGrid | `<CardGrid><Card title="T" icon="icon" href="/url">desc</Card></CardGrid>` |
| Steps | `<Steps><Step title="First">content</Step></Steps>` |
| Badge | `<Badge variant="new\|deprecated\|tip\|warning\|danger">label</Badge>` |
| Tag | `<Tag variant="new\|experimental\|deprecated">label</Tag>` |
| Tooltip | `<Tooltip text="Explanation">hover text</Tooltip>` |
| Banner | `<Banner id="unique" persist="none\|session\|forever">text</Banner>` |
| ThemedImage | `<ThemedImage light="/l.png" dark="/d.png" alt="Alt" />` |
| Head | `<Head><meta property="og:image" content="/img.png"></Head>` |
| Mermaid | Use fenced code block with `mermaid` language |

## SEO Rules

- **Title**: under 60 chars, front-load keyword, format `Primary — Hook | Brand`
- **Description**: 150-160 chars, action verb, unique per page
- First paragraph is auto-extracted as meta description (max 160 chars)
- Every page must have unique title and description

## Markdown

Standard Markdown: headings (#-######), bold, italic, links, images, lists, tables, code blocks, blockquotes, horizontal rules. Headings auto-generate anchor links.

Skill: Oxidoc CLI Operator

For CI/CD automation or when the agent needs to run Oxidoc commands.

CLI Operator Skill — click to expand

SKILL.mdmarkdown

---
name: oxidoc-cli
description: Run Oxidoc CLI commands — init, dev, build, clean, archive, update. Use for CI/CD automation, local development, or any task requiring Oxidoc command execution.
---

# Oxidoc CLI

## Overview

Single Rust binary, no runtime dependencies. Install with `curl -fsSL https://oxidoc.dev/install.sh | sh`.

**Keywords**: oxidoc, CLI, build, dev server, init, deploy, CI/CD, install

## Commands

```
oxidoc init [name]              New project (-f force, -y skip prompts)
oxidoc dev [-p port]            Dev server + hot reload (default: 3000)
oxidoc build [-o dir]           Production build (default: dist/)
oxidoc clean                    Remove .oxidoc-dev/ and dist/
oxidoc archive create|list|delete <ver>   Version snapshots
oxidoc update [--pre]           Update binary
oxidoc set-version <ver>        Pin specific version
```

Global flags: `-C <path>` project dir, `-v` verbose, `-q` quiet.

## CI/CD (GitHub Actions)

```yaml
- run: curl -fsSL https://oxidoc.dev/install.sh | sh
- run: oxidoc build
```

## Build Output

`oxidoc build` produces a fully static site in `dist/`: HTML, CSS, JS, Wasm islands, search index, sitemap.xml, robots.txt, feed.xml, llms.txt. Serve with any static host.

Skill: Oxidoc Site Configurator

For when the agent needs to set up or modify oxidoc.toml.

Site Configurator Skill — click to expand

SKILL.mdmarkdown

---
name: oxidoc-configurator
description: Set up and modify oxidoc.toml — covers all configuration sections including project, theme, routing, search, versioning, i18n, and analytics. Use when configuring an Oxidoc documentation site.
---

# Oxidoc Configuration (oxidoc.toml)

## Overview

All site configuration lives in `oxidoc.toml` at the project root.

**Keywords**: oxidoc.toml, configuration, routing, navigation, search, versioning, i18n, theme, footer, social, analytics

## Minimal Config

```toml
[project]
name = "My Docs"

[routing.root]
homepage = "home.rdx"

[routing]
navigation = [
  { path = "/docs", dir = "docs", groups = [
    { group = "Guide", pages = ["intro", "quickstart"] },
  ] },
]
```

## All Sections

| Section | Key fields |
|---------|------------|
| `[project]` | name (required), description, logo, favicon, base_url, edit_url, edit_label |
| `[theme]` | primary, accent, font, code_font, dark_mode (`"system"\|"light"\|"dark"`), custom_css |
| `[routing.root]` | homepage, pages |
| `[routing]` | header_links `[{label, href}]`, navigation `[{path, dir, groups, openapi}]` |
| `[search]` | provider (`"oxidoc"\|"algolia"\|"typesense"\|"meilisearch"\|"custom"`), semantic |
| `[versioning]` | default, versions |
| `[i18n]` | default_locale, locales, translation_dir |
| `[footer]` | copyright_owner, copyright_owner_url, links `[{label, href}]` |
| `[social]` | github, discord, twitter, mastodon |
| `[analytics]` | google_analytics, script |
| `[redirects]` | redirects `[{from, to}]` |
| `[components.custom]` | `TagName = "path/to/file.js"` |
| `[attribution]` | oxidoc (bool, default true) |

### Search Providers

- **Oxidoc** (default): zero-config BM25, optional `semantic = true`
- **Algolia**: app_id, api_key, index_name
- **Typesense**: host, port, protocol, api_key, collection_name
- **Meilisearch**: host, api_key, index_name
- **Custom**: stylesheet, script, init_script

## Navigation Rules

- `path` = URL prefix (e.g., `"/docs"`), `dir` = content directory containing `.rdx` files
- `pages` = list of slugs — the filename without `.rdx` (e.g., `"quickstart"` → `docs/quickstart.rdx`)
- `groups` = sidebar sections with `group` (display title) and `pages` (slug list)
- `openapi` = path to OpenAPI/Swagger spec — auto-generates interactive API reference pages
- Pages only appear in sidebar if listed in a navigation group
- Nested slugs: `"guides/styling"` maps to `docs/guides/styling.rdx`

Skill: Oxidoc Theme Customizer

For when the agent needs to customize the visual design.

Theme Customizer Skill — click to expand

SKILL.mdmarkdown

---
name: oxidoc-theme
description: Customize Oxidoc's visual design — theme config in oxidoc.toml, CSS custom properties, dark mode overrides, and layout tokens. Use when styling or theming an Oxidoc documentation site.
---

# Oxidoc Theming

## Overview

Oxidoc uses CSS custom properties (`--oxidoc-*`) for all visual styling. All built-in styles use `@layer oxidoc`, so your custom CSS always wins without `!important`.

**Keywords**: theme, CSS variables, dark mode, colors, typography, layout, custom CSS, styling, branding

## Quick Theming (oxidoc.toml)

Set colors, fonts, and dark mode toggle behavior in `[theme]`:

```toml
[theme]
primary = "#3b82f6"        # Primary brand color
accent = "#f59e0b"         # Accent color for highlights
font = "Inter, sans-serif"
code_font = "JetBrains Mono, monospace"
dark_mode = "system"       # "system" (follows OS), "light", or "dark"
custom_css = ["assets/custom.css"]  # paths relative to project root
```

## Custom CSS Setup

1. Create a CSS file in `assets/` (e.g., `assets/custom.css`) — this directory is copied to `dist/` on build
2. Register it in `oxidoc.toml` via `custom_css = ["assets/custom.css"]`
3. Override any `--oxidoc-*` variable in `:root` or scope to dark mode with `[data-theme="dark"]`

All built-in styles use `@layer oxidoc`, so your CSS always wins — no `!important` needed.

```css
/* assets/custom.css */
:root {
  --oxidoc-primary: #2563eb;
  --oxidoc-font-sans: "My Font", sans-serif;
}
[data-theme="dark"] {
  --oxidoc-primary: #3b82f6;
}
```

## CSS Variables Reference

| Category | Variables |
|----------|-----------|
| Core | `--oxidoc-primary`, `--oxidoc-accent`, `--oxidoc-bg`, `--oxidoc-bg-secondary`, `--oxidoc-text`, `--oxidoc-text-secondary`, `--oxidoc-border`, `--oxidoc-code-bg` |
| Semantic | `--oxidoc-success`, `--oxidoc-warning`, `--oxidoc-error`, `--oxidoc-info`, `--oxidoc-new`, `--oxidoc-deprecated` (each has `-text` variant) |
| Utility | `--oxidoc-text-muted`, `--oxidoc-bg-subtle`, `--oxidoc-on-primary`, `--oxidoc-shadow`, `--oxidoc-overlay` |
| Typography | `--oxidoc-font-sans`, `--oxidoc-font-mono` |
| Layout | `--oxidoc-content-max` (48rem), `--oxidoc-sidebar-width` (16rem), `--oxidoc-toc-width` (14rem), `--oxidoc-header-height` (3.5rem) |
| Radius | `--oxidoc-radius-sm`, `--oxidoc-radius-md`, `--oxidoc-radius-lg` |
| Shadows | `--oxidoc-shadow-sm`, `--oxidoc-shadow-md`, `--oxidoc-shadow-lg` |
| Z-index | `--oxidoc-z-tooltip` (10), `z-back-to-top` (50), `z-sidebar` (90), `z-header` (100), `z-skip-nav` (200), `z-overlay` (1000) |
| Transitions | `--oxidoc-transition-fast`, `--oxidoc-transition-normal`, `--oxidoc-transition-slow`, `--oxidoc-transition-spring` |

## Dark Mode

The `dark_mode` setting in `oxidoc.toml` controls the toggle behavior (system/light/dark). To customize dark mode colors, override CSS variables under `[data-theme="dark"]` in your custom CSS file. Primary shades auto-generate via `color-mix()` — you only need to set the base color.

Combining Skills

You can install multiple skills side by side. In Claude Code, each goes in its own directory under .claude/skills/. For other tools, combine the skill contents in a single config file. For most projects, the Full Oxidoc Skill is all you need. Use the focused skills when you want to keep the agent's context lean.

Keep it updated

When you upgrade Oxidoc, check this page for updated skill files. New components and config options get added to the skills as they ship.