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.

bash

wcl wdoc skill docs/my-skill.wcl --out ./my-skill

§ 1Opting 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.

wcl

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)."
}

§ 2Folder 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.

text

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

§ 3Front 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).

text

---
name: demo-skill
description: What this skill does and when to use it.
license: MIT
---

§ 4Shipping 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.

wcl

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.

§ 5Shipping agents

A document-level agent block (a peer of site) ships a Claude Code subagent definition: the backend writes each one to agents/<name>.md at the output root, beside the skill folder(s) — YAML front matter from its fields (tools joined onto one comma-separated line, the agent-file convention; empty list and absent model omit their lines) and the body child rendered as the agent's system prompt. Agents belong to the document, not to one skill, so a document with several skill sites ships one shared set. Installers copy them into a repo's .claude/agents/. The agent file is the standing role constitution; the dispatching orchestrator's prompt carries the per-task payload, so write the body self-contained. Every other target ignores agent blocks. Duplicate agent names fail the build.

wcl

site assistant { default_template = :ai_skill
  skill { name = "demo-skill"  description = "A demo skill." }
}

agent "demo-helper" {
  description = "Runs one demo task. Use when dispatching demo work."
  tools = ["Read", "Bash"]
  model = "sonnet"
  body {
    h1 "Role"
    p  "You are the demo helper. Your prompt carries one task; do it and stop."
  }
}

§ 6Several skills from one document

A document may declare more than one :ai_skill site. With a single skill site the folder renders flat at the output root; with several (and none marked root = true), each renders into its own named subfolder — <out>/<site>/SKILL.md — with the shared agents/ beside them. Pages join a skill through the usual sites = [ … ] membership, so each skill curates its own page set (and pages may be shared).

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/.

wcl

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/).