The wskill schema

A complete reference of the wcl.wskill namespace, reflected from the live schema (namespace_decls / decl_info / type_fields) so it never drifts from base.wcl / extensions.wcl. Top-level blocks — the ones the root document gathers — come first in declaration order; any blocks nested inside a block are listed directly under it. The document roots and shared types follow.

Blocks

Topic

The overarching subject — wraps everything inside the wskill — together with the wskill's own document-level metadata (creation/maintenance dates). Exactly one per wskill.

Property	Type	Required
id	identifier	yes
name	utf8	yes
summary	utf8	yes
description	utf8	no
version	utf8	no
tags	list<utf8>	no
created	utf8	yes
updated	utf8	no
maintainer	utf8	no
maintainer_entity	identifier	no
note	utf8	no

Skill

Controls written into the generated SKILL.md frontmatter, plus the bundled artifacts (script / asset children). A skill block kind is only possible because the schema is namespaced (wcl.wskill::skill) — bare it would collide with wdoc's own skill block. Defaults are absent-equivalent (empty list = no pre-approval / no restriction; false = model may invoke), so they are safe to always emit. Exactly one per wskill; the templates bind let skill = head(skills).

Property	Type	Required
allowed_tools	list<utf8>	no
disallowed_tools	list<utf8>	no
disable_model_invocation	bool	no

Child blocks

Slot	Accepts	Multiple
skill_scripts	script	yes
skill_assets	asset	yes
summary	summary	yes
parameters	skill_param	yes
boundary	skill_boundary	yes

Script

A runnable script shipped into the skill's scripts/ folder.

Property	Type	Required
id	identifier	yes
source	utf8	yes
name	utf8	yes
description	utf8	yes
usage	utf8	yes
tags	list<utf8>	no

Asset

A static data file (fixture, dataset, sample config) shipped into assets/.

Property	Type	Required
id	identifier	yes
source	utf8	yes
name	utf8	yes
description	utf8	yes
tags	list<utf8>	no

Summary

Optional custom SKILL.md summary content — a sub-block of skill whose plain fields are pulled onto the skill's start page (no wdoc body projection, which the skill/wdoc block-kind collision prevents). Author one inside skill.

Property	Type	Required	Description
overview	list<utf8>	no

SkillParam

An invocation parameter the skill accepts — rendered into the SKILL.md "Parameters" section. name is the Claude Code placeholder or label (e.g. "1", "$2"); value says how to determine what to pass. The kind is skill_param (not parameter, which the language module already declares).

Property	Type	Required
name	utf8	yes
description	utf8	no
value	utf8	no

SkillBoundary

Behavioural guardrails for the skill — rendered into SKILL.md inside <Boundary> … </Boundary> tags so an agent treats them as hard rules. The kind is skill_boundary (bare boundary collides with a wdoc diagram block).

Property	Type	Required
always	list<utf8>	no
ask	list<utf8>	no
never	list<utf8>	no

Source

Where current/authoritative information about the topic lives. Drives the update workflow only; it carries no content. See references/workflow-update.md.

Property	Type	Required
id	identifier	yes
kind	utf8	yes
locator	utf8	yes
covers	utf8	yes
last_checked	utf8	no
reflects_version	utf8	no

WskillRef

A relationship to another wskill. Resolved by name against repo peers / the collection manifest first, by url otherwise. status = "planned" is the stub form: it renders but the validator reports it as a warning so the planned-skill backlog stays visible without blocking renders.

Property	Type	Required
id	identifier	yes
name	utf8	yes
url	utf8	no
relation	utf8	no
status	utf8	no

Concept

An idea the reader must understand.

Property	Type	Required
id	identifier	yes
name	utf8	yes
summary	utf8	yes
related	list<identifier>	no
audience	Audience	no
tags	list<utf8>	no

Child blocks

Slot	Accepts	Multiple	Description
body	body	no

Entity

A concrete thing in the topic's world (type, command, screen, card, …).

Property	Type	Required
id	identifier	yes
name	utf8	yes
kind	utf8	yes
summary	utf8	no
related	list<identifier>	no
audience	Audience	no
tags	list<utf8>	no

Child blocks

Slot	Accepts	Multiple	Description
body	body	no

Fact

A factual unit — a container for values, constants, value tables. The title names it; the body holds the data (a table, code, prose).

Property	Type	Required
id	identifier	yes
title	utf8	yes
related	list<identifier>	no
audience	Audience	no
tags	list<utf8>	no

Child blocks

Slot	Accepts	Multiple	Description
body	body	no

Term

A glossary entry.

Property	Type	Required
id	identifier	yes
term	utf8	yes
definition	utf8	yes
aliases	list<utf8>	no
audience	Audience	no
tags	list<utf8>	no

Example

A worked example or code sample. It is NOT a section of its own — it projects onto a unit: unit names the id of the concept/entity/fact it illustrates, and the templates render it on that unit's page (after the body).

Property	Type	Required
id	identifier	yes
title	utf8	yes
unit	identifier	no
narrative	utf8	no
code_lang	utf8	no
code	utf8	no
expected	utf8	no
audience	Audience	no
tags	list<utf8>	no

Index

An index — a curated landing page that gathers links to other parts of the wskill in a topic-meaningful arrangement. Unlike concept/entity/fact/procedure it is NOT filed under Reference: each index gets its own top-level entry in the book menu (between Overview and Reference). The body (an addressable body { … }) holds the curated links/prose; related auto-resolves to a link list. An index may nest child indexes one level deep (@children("index")): write a child index { … } block inside the parent and both projections render it nested — under the parent chapter in the book TOC, indented under the parent bullet in the skill. Document-level @children("index") gathers only direct children, so a nested index is not also listed at the top level.

Property	Type	Required
id	identifier	yes
name	utf8	yes
summary	utf8	no
related	list<identifier>	no
audience	Audience	no
tags	list<utf8>	no

Child blocks

Slot	Accepts	Multiple	Description
body	body	no
children	index	yes

Index

Property	Type	Required
id	identifier	yes
name	utf8	yes
summary	utf8	no
related	list<identifier>	no
audience	Audience	no
tags	list<utf8>	no

Child blocks

Slot	Accepts	Multiple	Description
body	body	no
children	index	yes

Procedure

A runbook for *doing* a specific task. Written for someone who already knows the topic and needs the reliable sequence. A procedure is a fourth interlinking unit (alongside concept/entity/fact) — it keeps its structured, step-based shape, but carries related and renders to its own page, so units can link to and from it. (process is the user-facing name; the block is procedure.)

Property	Type	Required
id	identifier	yes
title	utf8	yes
purpose	utf8	yes
preconditions	list<utf8>	no
verification	utf8	no
related	list<identifier>	no
audience	Audience	no
tags	list<utf8>	no

Child blocks

Slot	Accepts	Multiple	Description
steps	step	yes

Step

One ordered step in a process (procedure). The label is its number.

Property	Type	Required	Description
n	u32	yes
title	utf8	no

Child blocks

Slot	Accepts	Multiple	Description
bodies	body	yes

Document roots & shared types

Attr

Property	Type	Required	Description
key	utf8	yes
value	utf8	yes

WSkillDoc

Merges with wdoc's library @document (so site / page template blocks are legal alongside content) and with any @document declared in extensions.wcl.

Property	Type	Required	Description
schema_version	utf8	yes

Child blocks

Slot	Accepts	Multiple
topics	topic	yes
skills	skill	yes
sources	source	yes
refs	wskill_ref	yes
concepts	concept	yes
entities	entity	yes
facts	fact	yes
terms	term	yes
examples	example	yes
indexes	index	yes
procedures	procedure	yes

Audience

A symbol_set — one of: book, ai, both.

- Separation of Data and Presentation

- Content is self-contained