# Metalsmith Website Skills

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

- Skill: `wernerglinka/metalsmith-website-skills` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds add wernerglinka/metalsmith-website-skills`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wernerglinka/metalsmith-website-skills/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: wernerglinka (https://skillmd.com/u/wernerglinka)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/wernerglinka/metalsmith-website-skills

---


# 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

1. **component-builder/** The main workflow. Start here.
2. **css-layout-development/** CSS layout patterns using modern intrinsic design.
3. **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`:

1. **Setup** Verify Node 22, clone the starter, install, run, initialize the page shell
2. **Discovery** Understand what the site needs
3. **Component selection** Read the catalog, install what is missing
4. **Page building** Write frontmatter from the schema, one page at a time
5. **Appearance** Tokens, then overrides, never canon
6. **Publish** Add the remote, push, deploy on Netlify

## Rules that hold across every phase

1. **Node 22 or higher.** The starter sets `engines.node` to `>=22.0.0` and will not run
   below it. Check before cloning.
2. **The starter is `metalsmith2025-structured-content-starter`**, cloned from
   `https://github.com/wernerglinka/metalsmith2025-structured-content-starter`.
3. **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.
4. **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.
5. **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`.
6. **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.