Skill folders
wcl wdoc skill <file> --out <dir> renders a document to an agent / Claude skill folder — a SKILL.md plus the conventional references/, scripts/ and assets/ subfolders. It's a Markdown-backed target (see Markdown output): prose, links, tables, code, diagrams and the rest map exactly as they do there, but the *folder layout* and SKILL.md front matter follow the skill convention.
Opting in
A site becomes a skill by setting defaulttemplate = :aiskill and declaring a skill { } block. The skill block supplies the required front-matter name and description (and an optional license) that the backend writes onto SKILL.md.
import <wdoc.wcl>
site my_skill {
default_template = :ai_skill
skill {
name = "demo-skill"
description = "What this skill does and when to use it."
license = "MIT"
}
}
page overview { start = true
h1 "Demo Skill"
p "Instructions… see the [usage guide](usage)."
}
page usage {
h1 "Usage"
p "Details. Back to the [overview](overview)."
}
Folder layout
The site's start page (start = true) becomes SKILL.md at the folder root; every other page is written under references/<name>.md. Internal links between pages resolve into that layout automatically — a link to the start page points at SKILL.md, and a link to any other page at references/<name>.md, with the right ../ prefix from a reference page.
my-skill/
SKILL.md # the start page
references/
usage.md # every other page
scripts/ # files declared with dir = "scripts"
assets/ # files declared with dir = "assets"
_wdoc/ # generated diagram / terminal SVGs
Front matter
SKILL.md's YAML header is built from the skill { } block. To add extra keys (for example allowed-tools), author a @schemaless frontmatter block on the start page — its keys are merged after the canonical name / description / license (which the skill block owns).
---
name: demo-skill
description: What this skill does and when to use it.
license: MIT
---
Shipping files
A file block copies an arbitrary file from beside the document into the output and keeps its basename, so the path is stable and hand-linkable. dir names the target subfolder (scripts, assets, …). Set as to render a link to it; omit as to ship it silently and reference it by its path yourself.
page overview { start = true
h1 "Demo Skill"
// Renders a link: [run setup](scripts/setup.sh)
file "src/setup.sh" { dir = "scripts" as = "run setup" }
// Shipped silently to assets/logo.svg
file "src/logo.svg" { dir = "assets" }
}
Not an HTML template
:ai_skill is a Markdown-only target. Building a skill site with wcl wdoc build (HTML) fails with a message pointing you at wcl wdoc skill. The file block itself works on every target — on the HTML and Markdown targets a dir-less file lands in the _wdoc/ asset folder.
Sharing pages with a website
A :ai_skill site can live in the same document as a :webpage or :book site. wcl wdoc build / pdf / markdown skip the skill site, and wcl wdoc skill builds only it — so one source feeds both a hosted site and a skill. Because a page joins a site through its sites = [ … ] list, the *same* reference page can belong to both: list both site names and it renders into the book and into the skill's references/.
site handbook { default_template = :book }
site assistant { default_template = :ai_skill
skill { name = "handbook" description = "Project handbook for agents." }
}
// Shared: appears in the book *and* the skill's references/.
page deploys { sites = [:handbook, :assistant]
h1 "Deploys"
p "…"
}
This project's own docs do exactly that: the language reference is one set of pages shared by the web reference book and the wcl skill (built by the skill-build recipe into .claude/skills/wcl/).