Skill folders
The `:aiskill target: the skill { } block, folder layout, front matter, and file` blocks._
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 (the Markdown output mapping applies), but the *folder layout* and SKILL.md front matter follow the skill convention.
wcl wdoc skill docs/my-skill.wcl --out ./my-skill
Opting in
A site becomes a skill by setting default_template = :ai_skill 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, a link to any other page at references/<name>.md.
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 frontmatter block on the start page — its keys are merged after the canonical name / description / license (which the skill block owns).
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 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.
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 "…"
}
Examples
Opting a site into a skill
A site becomes a Claude skill by setting defaulttemplate = :aiskill and declaring a skill { } block that supplies the SKILL.md front matter.
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)."
}
Expected: The start page becomes SKILL.md with name/description/license front matter; every other page lands under references/.
Related