Metalsmith Website Skills
Build websites by installing components and writing structured frontmatter. The user
describes what they want. Claude installs components and authors the pages.
Included skills
- component-builder/ The main workflow. Start here.
- css-layout-development/ CSS layout patterns using modern intrinsic design.
- javascript-development/ JavaScript patterns and standards for any custom code.
Which to read
- Building or changing a site: read
component-builder/SKILL.md first, and follow it.
- Writing CSS beyond token changes: also read
css-layout-development/SKILL.md.
- Writing JavaScript, browser or build: also read
javascript-development/SKILL.md.
The contract
There are two published JSON files. They answer what components exist and what each one
accepts. Read them instead of reading prose documentation.
https://nunjucks-components.com/downloads/manifest.json The catalog. What exists, what
version, what each component requires, where its archive is.https://nunjucks-components.com/assets/components-schema.json The composed field tree
for every authorable section. Widgets, labels, defaults, enums, required flags, nesting.
component-builder/references/contract-artifacts.md teaches both. Read it before choosing
components.
Workflow
Six phases, laid out in full in component-builder/SKILL.md:
- Setup Verify Node 22, clone the starter, install, run, initialize the page shell
- Discovery Understand what the site needs
- Component selection Read the catalog, install what is missing
- Page building Write frontmatter from the schema, one page at a time
- Appearance Tokens, then overrides, never canon
- Publish Add the remote, push, deploy on Netlify
Rules that hold across every phase
- Node 22 or higher. The starter sets
engines.node to >=22.0.0 and will not run
below it. Check before cloning.
- The starter is
metalsmith2025-structured-content-starter, cloned from
https://github.com/wernerglinka/metalsmith2025-structured-content-starter.
- Install components with
npm run components, or
node scripts/install-components.mjs <names>. There is no per-component curl plus
install.sh step. Do not invent one.
- Install commits are load-bearing. The installer writes one commit per component
recording its name, version and content hash. Never squash them. Never commit over them
with a single "Initial website". Never rewrite history before pushing.
- Never edit files under
lib/layouts/components/. That is canon and the next install
replaces it wholesale. Customize through lib/assets/styles/_design-tokens.css first,
then lib/overrides/<name>/<name>.css.
- Validation warns, it does not fail the build. A green build is not proof the
frontmatter is right. Read the warnings in the terminal output.
Working with the user
The user may not code. They describe outcomes; Claude runs the commands, writes the files
and explains what changed in plain terms.
They do need Node 22, Git, and a terminal in an empty project directory. They will need a
GitHub account and a Netlify account to publish, and Claude walks them through both at
phase 6.
Preview is live. The dev server runs at http://localhost:3000 throughout. Build one page
at a time, ask the user to refresh, and ask a specific question about what they see rather
than a general one.
1---2name: metalsmith-website-skills3description: Build static websites from structured content and installable Nunjucks components, using the metalsmith2025-structured-content-starter. Triggers on phrases like "build me a website", "create a landing page", "help me make a site", "add a section to my page", "install a component", "change my site's colors", or when working with sectionType frontmatter, nunjucks-components.com, or the structured content starter. Includes JavaScript and CSS development standards.4---56# Metalsmith Website Skills78Build websites by installing components and writing structured frontmatter. The user9describes what they want. Claude installs components and authors the pages.1011## Included skills12131. **component-builder/** The main workflow. Start here.142. **css-layout-development/** CSS layout patterns using modern intrinsic design.153. **javascript-development/** JavaScript patterns and standards for any custom code.1617## Which to read1819- **Building or changing a site**: read `component-builder/SKILL.md` first, and follow it.20- **Writing CSS** beyond token changes: also read `css-layout-development/SKILL.md`.21- **Writing JavaScript**, browser or build: also read `javascript-development/SKILL.md`.2223## The contract2425There are two published JSON files. They answer what components exist and what each one26accepts. Read them instead of reading prose documentation.2728- `https://nunjucks-components.com/downloads/manifest.json` The catalog. What exists, what29 version, what each component requires, where its archive is.30- `https://nunjucks-components.com/assets/components-schema.json` The composed field tree31 for every authorable section. Widgets, labels, defaults, enums, required flags, nesting.3233`component-builder/references/contract-artifacts.md` teaches both. Read it before choosing34components.3536## Workflow3738Six phases, laid out in full in `component-builder/SKILL.md`:39401. **Setup** Verify Node 22, clone the starter, install, run, initialize the page shell412. **Discovery** Understand what the site needs423. **Component selection** Read the catalog, install what is missing434. **Page building** Write frontmatter from the schema, one page at a time445. **Appearance** Tokens, then overrides, never canon456. **Publish** Add the remote, push, deploy on Netlify4647## Rules that hold across every phase48491. **Node 22 or higher.** The starter sets `engines.node` to `>=22.0.0` and will not run50 below it. Check before cloning.512. **The starter is `metalsmith2025-structured-content-starter`**, cloned from52 `https://github.com/wernerglinka/metalsmith2025-structured-content-starter`.533. **Install components with `npm run components`**, or54 `node scripts/install-components.mjs <names>`. There is no per-component `curl` plus55 `install.sh` step. Do not invent one.564. **Install commits are load-bearing.** The installer writes one commit per component57 recording its name, version and content hash. Never squash them. Never commit over them58 with a single "Initial website". Never rewrite history before pushing.595. **Never edit files under `lib/layouts/components/`.** That is canon and the next install60 replaces it wholesale. Customize through `lib/assets/styles/_design-tokens.css` first,61 then `lib/overrides/<name>/<name>.css`.626. **Validation warns, it does not fail the build.** A green build is not proof the63 frontmatter is right. Read the warnings in the terminal output.6465## Working with the user6667The user may not code. They describe outcomes; Claude runs the commands, writes the files68and explains what changed in plain terms.6970They do need Node 22, Git, and a terminal in an empty project directory. They will need a71GitHub account and a Netlify account to publish, and Claude walks them through both at72phase 6.7374Preview is live. The dev server runs at `http://localhost:3000` throughout. Build one page75at a time, ask the user to refresh, and ask a specific question about what they see rather76than a general one.
wernerglinka