@nera-static/nera 1.9.0 → 1.10.0

package/README.md

@@ -27,11 +27,11 @@ package is named after the folder (`My Bakery` → `my-bakery`).
 
 | Command | What it does |
 |---|---|
-| `nera new <name>` | Scaffold a new thin Nera site (one dependency: `@nera-static/nera`). Add `--theme <name>` to start from a theme. `nera new .` scaffolds into the current, empty folder (dotfiles, `AGENTS.md` and `CLAUDE.md` allowed). |
+| `nera new <name>` | Scaffold a new thin Nera site (one dependency: `@nera-static/nera`). Add `--theme <name>` to start from a theme, `--no-install` to skip `npm install`. `nera new .` scaffolds into the current, empty folder (dotfiles, `AGENTS.md` and `CLAUDE.md` allowed). Every new site also gets the `nera` skill for AI assistants. |
 | `nera build` | Render `pages/` → `public/`. With `--check`, then run `nera check` on the result — one command for CI. `--json` prints the result as one JSON object (see [Machine-readable output](#machine-readable-output)). |
 | `nera dev` | Build, serve `public/`, and rebuild on change with live reload. Watches `pages/`, `config/`, `theme/` and a local theme (`theme: ./themes/<name>`). |
 | `nera serve` | Serve the already-built `public/` folder. |
-| `nera update` | Update the site's Nera packages, then create a missing `AGENTS.md`/`CLAUDE.md` and refresh the Nera part of `AGENTS.md` (see [Instructions for AI assistants](#instructions-for-ai-assistants)). On a legacy cloned site, `nera update --migrate` converts it to the thin model. |
+| `nera update` | Update the site's Nera packages, then create a missing `AGENTS.md`/`CLAUDE.md` and refresh the Nera part of `AGENTS.md` and the `nera` skill (see [Instructions for AI assistants](#instructions-for-ai-assistants)). On a legacy cloned site, `nera update --migrate` converts it to the thin model. |
 | `nera validate` | Check the site's sources (layouts, includes, YAML) before publishing; exits non-zero on any error. `--json` for machine-readable output. |
 | `nera check` | Check the built `public/` for accessibility, privacy and legal-notice problems (see below). Build first. `--json` for machine-readable output. |
 
@@ -75,6 +75,23 @@ packages are updated (and after `nera update --migrate`) it:
 A file is written only when its content changes, so running `nera update`
 again changes nothing.
 
+### The `nera` skill
+
+Every site also gets the `nera` [Agent Skill](https://agentskills.io): a
+`SKILL.md` with the workflow (scaffold, content, plugins, `nera validate`,
+`nera build --check`, deploy `public/`) and short recipes — business site,
+blog, portfolio, contact form, search, images, multilingual site, custom
+domain — that assistants load when a task matches. It lives in two folders,
+`.agents/skills/nera/` (Codex, Cursor, Copilot, Gemini CLI) and
+`.claude/skills/nera/` (Claude Code); commit them with the site.
+
+Both folders are Nera's: `nera new` writes them, and `nera update` (also after
+`--migrate`) replaces them with the skill of the installed `@nera-static/nera`,
+removing files the new version no longer has. Put your own instructions in
+`AGENTS.md`'s notes section or in a skill folder of your own; other folders
+under `.agents/skills/` and `.claude/skills/` are never touched. The source is
+[`skills/nera/`](skills/nera/) in this repository.
+
 ## Starting from a theme
 
 ```bash

package/bin/nera.js

@@ -13,7 +13,7 @@ const json = rest.includes('--json')
 const usage = `Nera — the static site generator CLI
 
 Usage:
-  nera new <name>    scaffold a new Nera site (--theme <name> to start from a theme)
+  nera new <name>    scaffold a new Nera site (--theme <name> to start from a theme, --no-install to skip npm install)
   nera new .         scaffold into the current, empty folder
   nera build         render pages/ → public/ (--check to check the output after, --json for machine-readable output)
   nera dev           build, serve and live-reload

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@nera-static/nera",
-    "version": "1.9.0",
+    "version": "1.10.0",
     "description": "The Nera CLI — scaffold, build, preview and update a Nera static site with one command over the @nera-static/core engine",
     "type": "module",
     "bin": {
@@ -8,6 +8,7 @@
     },
     "files": [
         "bin",
+        "skills",
         "src",
         "template"
     ],

package/skills/nera/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: nera
+description: Create, change, check and deploy websites built with Nera, the Markdown + Pug static site generator (npm package @nera-static/nera). Use when package.json lists @nera-static/nera, or when the user asks to build a website, page, blog, portfolio or business site with Nera, or to add a contact form, search, images, a second language or a custom domain to a Nera site. Holds the workflow, the checks to run after every change, and short recipes for common sites and features.
+---
+
+# Nera
+
+Nera turns Markdown pages and Pug templates into plain HTML. It is not
+Eleventy, Hugo, Astro or Jekyll; do not apply their conventions.
+
+## Read this first
+
+- **In an existing site, read `AGENTS.md` at the site root before anything
+  else.** It holds the folder map, the commands and the traps (pages need
+  `layout`, URLs end in `.html`, `public/` is wiped on every build, plugin
+  templates are copied and included by hand). This skill does not repeat it.
+- No site yet? Scaffold one (step 1 below), then read its `AGENTS.md`.
+- The "Notes for this site" section at the end of `AGENTS.md` belongs to the
+  site owner: follow it, and add to it what the next agent should know.
+
+## Workflow
+
+1. **Scaffold.** `npx @nera-static/nera new my-site` creates a folder and
+   installs; `npx @nera-static/nera new .` fills the current, empty folder.
+   `--theme <name>` starts from a theme; `--no-install` skips `npm install`.
+2. **Content.** One Markdown file per page in `pages/`, each with YAML
+   frontmatter that names its `layout`. Site name, language and texts for
+   templates go in `config/app.yaml`. Shared markup goes in `theme/views/`.
+3. **Plugins.** Look for a plugin before writing a feature (see below).
+   Install it, configure it in `config/<name>.yaml`, copy its templates with
+   its own binary and include them in a layout.
+4. **Validate.** `npx nera validate` and fix every error it reports. It
+   finds broken layouts and includes and pages the build would skip.
+5. **Build and check.** `npx nera build --check` and fix what it reports
+   (accessibility, privacy and legal hints on the built site).
+   `npm run dev` previews on http://localhost:3000 with live reload; stop it
+   when you are done.
+6. **Deploy.** `npm run build` writes the finished site into `public/`.
+   Upload the contents of `public/` to any static host. See
+   [custom-domain](recipes/custom-domain.md) for a domain of your own.
+
+Repeat steps 2–5 for every change. For machine-readable results, add `--json`:
+`npx nera validate --json`, `npx nera check --json`,
+`npx nera build --check --json`.
+
+Existing site on an older Nera? `npx nera update` updates the Nera packages
+and refreshes `AGENTS.md` and this skill.
+
+## Look for a plugin before writing a feature
+
+Features come from npm packages named `@nera-static/plugin-<name>`. An
+installed plugin loads on the next build, with nothing to register. Do not
+hand-write navigation, a contact form, tags, search, pagination, image
+handling or a sitemap: a plugin exists for each. The catalog:
+https://github.com/seebaermichi/nera/blob/main/PLUGINS.md
+
+The published plugins: canonical-links, code-blocks, contact-form, images,
+link-attributes, navigation, one-page, page-navigation, page-pagination,
+popular-content, search, simple-page-list, sitemap, social-media-links,
+stacks, statistics, tags. Each plugin's README (on npm, or
+`github.com/seebaermichi/nera-plugin-<name>`) lists its config keys and its
+template binary. Read it before you configure the plugin.
+
+A feature no plugin covers can be a local plugin in
+`src/plugins/<name>/index.js`; see the tutorial
+[Write a local plugin](https://nera.js.org/tutorials/write-a-local-plugin.md).
+
+## Recipes
+
+Short task guides. Each names the steps, the files it touches and the docs
+page to open next.
+
+- [Business site](recipes/business-site.md): home, about, services, contact,
+  imprint and privacy, with a menu
+- [Blog](recipes/blog.md): posts, a post list, tags, pagination, sitemap
+- [Portfolio](recipes/portfolio.md): project pages with responsive images
+- [Contact form](recipes/contact-form.md): a `mailto:` form, no backend
+- [Search](recipes/search.md): client-side search over the site
+- [Images](recipes/images.md): responsive AVIF/WebP images
+- [Multilingual site](recipes/multilingual.md): a second language
+- [Custom domain](recipes/custom-domain.md): DNS, GitHub Pages `CNAME`,
+  `base_path`
+
+## Docs
+
+The docs on https://nera.js.org are the truth; this skill only points to
+them. For AI assistants, in English:
+
+- Index: https://nera.js.org/llms.txt
+- Everything in one file: https://nera.js.org/llms-full.txt
+- Single pages as Markdown:
+  [getting started](https://nera.js.org/docs/getting-started.md),
+  [core concepts](https://nera.js.org/docs/core-concepts.md),
+  [writing content](https://nera.js.org/docs/writing-content.md),
+  [plugins](https://nera.js.org/docs/plugins.md),
+  [deployment](https://nera.js.org/docs/deployment.md),
+  [CLI](https://nera.js.org/docs/cli.md),
+  [using AI](https://nera.js.org/docs/using-ai.md)
+- Tutorials: [build a blog](https://nera.js.org/tutorials/build-a-blog.md),
+  [custom navigation](https://nera.js.org/tutorials/custom-navigation.md),
+  [tag your content](https://nera.js.org/tutorials/tag-your-content.md),
+  [add search](https://nera.js.org/tutorials/add-search.md),
+  [prev/next pagination](https://nera.js.org/tutorials/prev-next-pagination.md),
+  [canonical links](https://nera.js.org/tutorials/canonical-links-seo.md),
+  [how nera.js.org is built](https://nera.js.org/tutorials/how-this-site-is-built.md)

package/skills/nera/recipes/blog.md

@@ -0,0 +1,48 @@
+# Recipe: blog
+
+Posts in a folder, a list of posts on the home page, tags, previous/next
+links and a sitemap.
+
+## Steps
+
+1. Scaffold: `npx @nera-static/nera new my-blog`, then read its `AGENTS.md`.
+2. One Markdown file per post in `pages/posts/`, e.g.
+   `pages/posts/first-post.md`, each with `layout`, `title`, `description`,
+   `date` (`2026-10-12`) and `tags` (`tags: travel, food` or a YAML list).
+   A post is served at `/posts/first-post.html`.
+3. Post list: `npm install @nera-static/plugin-simple-page-list`, set
+   `page_path: /posts`, `sortBy: date` and `sortOrder: descending` in
+   `config/simple-page-list.yaml`, run
+   `npx nera-simple-page-list`, and include the list in the template of the
+   home page (data: `app.pageList`).
+4. Tags: `npm install @nera-static/plugin-tags`. It builds a page per tag
+   at `/tags/<tag>.html`. Run `npx nera-tags` and include
+   `partials/tag-links` in the post template and `partials/tag-cloud` where
+   you want all tags.
+5. Previous/next: `npm install @nera-static/plugin-page-pagination`, give
+   each post a `pagination_order` number, run `npx nera-page-pagination`
+   and include it in the post template. It links pages of the same folder.
+6. A post template of its own: `theme/views/pages/post.pug`, extending
+   `../layouts/layout` like `pages/default.pug`, with exactly one `main`.
+   Posts then use `layout: pages/post.pug`.
+7. Sitemap: `npm install @nera-static/plugin-sitemap` and set `origin` in
+   `config/app.yaml`. It also writes `robots.txt`.
+8. Menu: `@nera-static/plugin-navigation`, as in
+   [business-site](business-site.md).
+9. `npx nera validate`, then `npx nera build --check`; fix what they report.
+
+Each plugin's README names its config keys and include paths; read it
+before step 3, 4 or 5.
+
+## Files touched
+
+`pages/posts/*.md`, `pages/index.md`, `config/app.yaml`,
+`config/simple-page-list.yaml`, `config/tags.yaml` (optional),
+`theme/views/pages/post.pug`, `theme/views/vendor/plugin-*/`,
+`package.json`.
+
+## Read next
+
+- https://nera.js.org/tutorials/build-a-blog.md
+- https://nera.js.org/tutorials/tag-your-content.md
+- https://nera.js.org/tutorials/prev-next-pagination.md

package/skills/nera/recipes/business-site.md

@@ -0,0 +1,46 @@
+# Recipe: business site
+
+A small business presence: home, about, services, opening hours, contact,
+imprint and privacy, with a menu on every page.
+
+## Steps
+
+1. Scaffold: `npx @nera-static/nera new my-business`, then read its
+   `AGENTS.md`.
+2. Set the site in `config/app.yaml`: `name`, `lang`, and `origin` (the
+   live URL, e.g. `https://example.com`) once the domain is known.
+3. Write one Markdown page per topic, each with `layout: pages/default.pug`,
+   a `title` and a `description`: `pages/index.md`, `pages/about.md`,
+   `pages/services.md`, `pages/opening-hours.md`, `pages/contact.md`,
+   `pages/imprint.md`, `pages/privacy.md`. Opening hours fit a Markdown
+   table.
+4. Menu: `npm install @nera-static/plugin-navigation`, list the pages in
+   `config/navigation.yaml` (`href` ending in `.html`, `name`; groups such
+   as `main:` and `footer:` for a footer menu with imprint and privacy), run
+   `npx nera-navigation` and include a menu in
+   `theme/views/layouts/layout.pug` (see the plugin README for the mixins).
+5. Contact form: follow [contact-form](contact-form.md).
+6. Optional, for search engines: `@nera-static/plugin-sitemap` (needs
+   `origin`) and `@nera-static/plugin-canonical-links`. Social profiles:
+   `@nera-static/plugin-social-media-links`.
+7. Styles: a CSS file in `theme/assets/css/`, linked from the layout's
+   `head` (`link(rel="stylesheet" href="/css/main.css")`).
+8. `npx nera validate`, then `npx nera build --check`; fix what they report.
+   The legal hints from the check matter here: a business site usually
+   needs an imprint and a privacy page.
+9. Deploy `public/` (see [custom-domain](custom-domain.md)).
+
+Mark invented details (address, hours, prices, legal texts) as placeholders
+for the owner to replace, and say that legal pages need checking.
+
+## Files touched
+
+`config/app.yaml`, `config/navigation.yaml`, `pages/*.md`,
+`theme/views/layouts/layout.pug`, `theme/views/vendor/plugin-navigation/`,
+`theme/assets/css/`, `package.json`.
+
+## Read next
+
+- https://nera.js.org/docs/writing-content.md
+- https://nera.js.org/tutorials/custom-navigation.md
+- https://nera.js.org/docs/deployment.md

package/skills/nera/recipes/contact-form.md

@@ -0,0 +1,63 @@
+# Recipe: contact form
+
+A contact form with `@nera-static/plugin-contact-form`. It opens the
+visitor's mail client (`mailto:`): no backend, no form service, no account.
+Do not hand-write a `<form>` or post to a third-party service.
+
+## Steps
+
+1. `npm install @nera-static/plugin-contact-form`
+2. Create `config/contact-form.yaml`. `recipient` and at least one field
+   are required; without them the form does not render and the build only
+   warns:
+
+   ```yaml
+   recipient: hello@example.com
+   fields:
+       - name: name
+         label: Your name
+         type: text
+         required: true
+       - name: email
+         label: Your email
+         type: email
+         required: true
+       - name: message
+         label: Message
+         type: textarea
+         required: true
+   ```
+
+   Field types: `text`, `email`, `tel`, `textarea`, `select`, `checkbox`,
+   `radio`. The README lists the optional keys (subject, labels, honeypot,
+   `consent_text` with a link to the privacy page).
+3. `npx nera-contact-form` copies the form to
+   `theme/views/vendor/plugin-contact-form/` and its script to
+   `theme/assets/js/contact-form.js`.
+4. A page template for the contact page, `theme/views/pages/contact.pug`:
+
+   ```pug
+   extends ../layouts/layout
+
+   block content
+     main
+       | !{ content }
+       include /vendor/plugin-contact-form/contact-form
+   ```
+
+5. `pages/contact.md` with `layout: pages/contact.pug`, a `title` and a
+   short text above the form.
+6. `npx nera validate`, then `npx nera build --check`. Open
+   `/contact.html` with `npm run dev` and submit once: the mail client
+   should open with the message filled in.
+
+## Files touched
+
+`package.json`, `config/contact-form.yaml`, `pages/contact.md`,
+`theme/views/pages/contact.pug`, `theme/views/vendor/plugin-contact-form/`,
+`theme/assets/js/contact-form.js`.
+
+## Read next
+
+- Plugin README: https://github.com/seebaermichi/nera-plugin-contact-form
+- https://nera.js.org/docs/plugins.md

package/skills/nera/recipes/custom-domain.md

@@ -0,0 +1,38 @@
+# Recipe: custom domain
+
+Serve the built site under a domain of your own. Nera builds static files;
+the domain is set at the host and at the domain registrar.
+
+## Steps
+
+1. Build: `npm run build`. Deploy the contents of `public/` to the host
+   (GitHub Pages, Netlify, any static host). Set the host to build with
+   `npm run build` and publish `public/`, or upload `public/` yourself.
+2. At the host, add the custom domain in its site settings.
+3. At the registrar, set the DNS records the host names for that domain,
+   usually a `CNAME` record for `www` pointing at the host and `A`/`AAAA`
+   records (or `ALIAS`) for the bare domain. Copy them from the host's own
+   docs; they differ per host. DNS can take hours to spread.
+4. **GitHub Pages:** it needs a file named `CNAME` (no extension) at the
+   root of the deployed site, holding only the domain (`www.example.com`).
+   Never write it into `public/`, which every build deletes. Put it in
+   `theme/assets/CNAME`: every file in `theme/assets/` is copied to the root
+   of `public/` on each build, so it ends up at `public/CNAME`.
+5. **`base_path`:** leave it unset for a custom domain or any site served
+   from the root. Set `base_path: /<repo>` in `config/app.yaml` only for a
+   site served under a sub-path, such as a GitHub project page at
+   `https://<user>.github.io/<repo>/`; Nera then prefixes every root-absolute
+   link and asset URL. Remove it again when the custom domain takes over.
+6. Set `origin: https://www.example.com` in `config/app.yaml`, so the
+   sitemap and canonical links use the real domain.
+7. Turn on HTTPS at the host once the domain resolves.
+8. `npx nera validate`, then `npx nera build --check`, then deploy again.
+
+## Files touched
+
+`theme/assets/CNAME` (GitHub Pages), `config/app.yaml` (`origin`,
+`base_path`), DNS settings outside the site.
+
+## Read next
+
+- https://nera.js.org/docs/deployment.md

package/skills/nera/recipes/images.md

@@ -0,0 +1,45 @@
+# Recipe: images
+
+Responsive images with `@nera-static/plugin-images`: each picture becomes a
+`<picture>` with AVIF and WebP in several widths, plus a fallback. Needs
+`@nera-static/core` 4.13.0 or later (`npx nera update` brings it).
+
+## Steps
+
+1. `npm install @nera-static/plugin-images`
+2. Put the originals in the assets folder, e.g. `theme/assets/images/`.
+   They are referenced without `theme/assets`: `/images/photo.jpg`.
+3. In Markdown, write images as usual; the plugin rewrites them:
+   `![A pier at dusk](/images/pier.jpg)`. A title becomes a caption
+   (`![Alt](/images/pier.jpg "Caption")`), and query parameters crop or
+   size one image (`?w=800&ratio=16:9`, see the README).
+4. In frontmatter, `image: /images/hero.jpg` gets precomputed variants for
+   templates. Run `npx nera-images` to copy the `picture` mixin to
+   `theme/views/vendor/plugin-images/`, then in a template:
+
+   ```pug
+   include /vendor/plugin-images/picture
+   +picture(meta.images && meta.images.image, { alt: meta.image_alt })
+   ```
+
+   Images written directly in Pug (`img(src=…)`) are not processed.
+5. Optional `config/images.yaml`: `formats`, `widths`, `sizes`, `quality`.
+6. Variants are cached in `.nera-cache/images/`; the scaffold's
+   `.gitignore` already ignores `.nera-cache`.
+7. Originals with location data? List their folder (e.g. `images`) in a
+   `.neraignore` file at the site root; its paths are relative to the
+   assets folder. Only the processed variants, without metadata, are then
+   published.
+8. `npx nera validate`, then `npx nera build --check`; every image needs
+   alt text.
+
+## Files touched
+
+`package.json`, `theme/assets/images/`, `pages/*.md`,
+`config/images.yaml` (optional), `theme/views/vendor/plugin-images/`,
+`.neraignore` (optional).
+
+## Read next
+
+- Plugin README: https://github.com/seebaermichi/nera-plugin-images
+- https://nera.js.org/docs/writing-content.md

package/skills/nera/recipes/multilingual.md

@@ -0,0 +1,50 @@
+# Recipe: multilingual site
+
+A second language beside the first, e.g. English at `/` and German at
+`/de/`.
+
+## Steps
+
+1. Keep the default language at the root of `pages/` and put each other
+   language in its own folder: `pages/de/index.md` becomes `/de/index.html`.
+2. Give every page in another language `lang` in its frontmatter
+   (`lang: de`). Pages without it use `lang` from `config/app.yaml`.
+3. Pair the versions of a page with the same `slug` in their frontmatter
+   (`slug: about` on `pages/about.md` and `pages/de/ueber-uns.md`).
+4. Template texts: write `t('key')` in Pug and add the texts per language
+   under `translations:` in `config/app.yaml`:
+
+   ```yaml
+   lang: en
+   translations:
+     en:
+       read_more: Read more
+     de:
+       read_more: Weiterlesen
+   ```
+
+   `t()` uses the page's `lang`, else the site's.
+5. In `theme/views/layouts/layout.pug`, set the document language from the
+   page: `html(lang=meta.lang || app.lang)`.
+6. Menus: one group per language in `config/navigation.yaml` (`main:` and
+   `main_de:`), each rendered with the menu mixin and the language root,
+   e.g. `+linkListNav(app.nav.main_de.elements, 'nav--main', '/de')`.
+   Add a link to the other language's version of the page.
+7. Search engines: `@nera-static/plugin-canonical-links` with
+   `available_languages` in `config/canonical-links.yaml` adds `hreflang`
+   links; `@nera-static/plugin-sitemap` lists the pairs too. Both use
+   `lang` and `slug`.
+8. Search and tags can keep one index or tag list per language
+   (`group_by_lang` in `config/search.yaml` or `config/tags.yaml`).
+9. `npx nera validate`, then `npx nera build --check`.
+
+## Files touched
+
+`pages/<lang>/*.md`, `config/app.yaml`, `config/navigation.yaml`,
+`config/canonical-links.yaml`, `theme/views/layouts/layout.pug`.
+
+## Read next
+
+- https://nera.js.org/docs/core-concepts.md
+- https://nera.js.org/tutorials/canonical-links-seo.md
+- https://nera.js.org/tutorials/custom-navigation.md

package/skills/nera/recipes/portfolio.md

@@ -0,0 +1,41 @@
+# Recipe: portfolio
+
+A home page with a grid of projects, one page per project, large responsive
+images.
+
+## Steps
+
+1. Scaffold: `npx @nera-static/nera new my-portfolio`, then read its
+   `AGENTS.md`.
+2. Images: put originals in `theme/assets/images/` and set up
+   [images](images.md) first, so every photo is served as AVIF/WebP in
+   several widths.
+3. One Markdown file per project in `pages/projects/`, each with `layout`,
+   `title`, `description`, `date` and `image: /images/<file>.jpg` (the cover
+   picture). Show more photos in the body with
+   `![Alt text](/images/<file>.jpg "Caption")`.
+4. Project list: `npm install @nera-static/plugin-simple-page-list`, set
+   `page_path: /projects` in `config/simple-page-list.yaml`, run
+   `npx nera-simple-page-list`, and render `app.pageList` on the home page.
+   For a grid with cover images, loop over `app.pageList` in your own Pug
+   template instead of the published one.
+5. A project template, `theme/views/pages/project.pug`, extending
+   `../layouts/layout`, that shows the cover with the images plugin's
+   `+picture` mixin and then `content`, with exactly one `main`.
+6. Optional: `@nera-static/plugin-tags` to group projects by kind,
+   `@nera-static/plugin-page-pagination` for previous/next project,
+   `@nera-static/plugin-social-media-links`, `@nera-static/plugin-sitemap`.
+7. `npx nera validate`, then `npx nera build --check`. The check reports
+   images without alt text; describe what each picture shows.
+
+## Files touched
+
+`theme/assets/images/`, `pages/projects/*.md`, `pages/index.md`,
+`config/images.yaml` (optional), `config/simple-page-list.yaml`,
+`theme/views/pages/project.pug`, `theme/views/vendor/plugin-*/`,
+`package.json`.
+
+## Read next
+
+- https://nera.js.org/docs/writing-content.md
+- https://nera.js.org/docs/plugins.md

package/skills/nera/recipes/search.md

@@ -0,0 +1,48 @@
+# Recipe: search
+
+Client-side search with `@nera-static/plugin-search`: the build writes a
+JSON index, a small script searches it in the browser. No backend.
+
+## Steps
+
+1. `npm install @nera-static/plugin-search`. It works without config;
+   `config/search.yaml` can change the indexed `fields` or set
+   `group_by_lang: true` for one index per language.
+2. `npx nera-search` copies the search template to
+   `theme/views/vendor/plugin-search/` and its script to
+   `theme/assets/js/search.js`.
+3. A page template for the search page, `theme/views/pages/search.pug`:
+
+   ```pug
+   extends ../layouts/layout
+
+   block content
+     main
+       | !{ content }
+       include /vendor/plugin-search/search.pug
+   ```
+
+4. `pages/search.md` with `layout: pages/search.pug` and a `title`, and no
+   `#` heading: the copied template brings its own `h1`. Link the page from
+   the menu.
+5. The copy is the site's own: give its search input a label
+   (`aria-label="Search"`), or `nera build --check` warns
+   (`a11y-form-label`).
+6. The index is written to `theme/assets/search-index.json` on every build
+   and served as `/search-index.json`. It is generated: add
+   `theme/assets/search-index*.json` to `.gitignore`.
+7. Only pages with a `layout` are indexed. If other plugins add pages (tags),
+   run search last with `config/plugin-order.yaml` as the README shows.
+8. `npx nera validate`, then `npx nera build --check`; try a query with
+   `npm run dev`.
+
+## Files touched
+
+`package.json`, `config/search.yaml` (optional), `pages/search.md`,
+`theme/views/pages/search.pug`, `theme/views/vendor/plugin-search/`,
+`theme/assets/js/search.js`, `.gitignore`.
+
+## Read next
+
+- https://nera.js.org/tutorials/add-search.md
+- Plugin README: https://github.com/seebaermichi/nera-plugin-search

package/src/commands/update.js

@@ -4,6 +4,7 @@ import fssync from 'fs'
 import path from 'path'
 import { syncAgentFiles, SITE_NOTES_MARKER } from '../agent-files.js'
 import { templateDir as packageTemplateDir } from '../scaffold.js'
+import { installedSkillDir, skillSourceDir, syncSkill } from '../skill.js'
 
 const defaultRunNpm = (npmArgs, cwd) =>
     execFileSync('npm', npmArgs, { cwd, stdio: 'inherit' })
@@ -86,7 +87,22 @@ async function syncAndReportAgentFiles(cwd, fallbackDir) {
     }
 }
 
-async function migrateLegacy(cwd, pkg, runNpm, templateDir) {
+const SKILL_MESSAGES = {
+    created: (dir) => `  ✓ Added the Nera skill in ${dir}`,
+    updated: (dir) => `  ✓ Refreshed the Nera skill in ${dir}`,
+    unchanged: (dir) => `  ✓ ${dir} unchanged`,
+}
+
+// The skill folders are wholly Nera's, so they always follow the installed
+// version (see installedSkillDir).
+async function syncAndReportSkill(cwd, fallbackDir) {
+    const results = await syncSkill({ cwd, sourceDir: installedSkillDir(cwd, fallbackDir) })
+    for (const { path: dir, action } of results) {
+        console.log(SKILL_MESSAGES[action](dir))
+    }
+}
+
+async function migrateLegacy(cwd, pkg, runNpm, templateDir, skillDir) {
     console.log('🔧 Migrating this cloned site to the thin @nera-static/nera model...')
 
     pkg.dependencies = {
@@ -131,6 +147,7 @@ async function migrateLegacy(cwd, pkg, runNpm, templateDir) {
     console.log('📦 Installing...')
     runNpm(['install'], cwd)
     await syncAndReportAgentFiles(cwd, templateDir)
+    await syncAndReportSkill(cwd, skillDir)
 
     console.log('✅ Migrated. Run `nera dev` to start.')
     if (movedPlugins) {
@@ -143,11 +160,13 @@ async function migrateLegacy(cwd, pkg, runNpm, templateDir) {
 
 export async function runUpdate(args = [], options = {}) {
     // templateDir: the fallback scaffold template for AGENTS.md / CLAUDE.md
-    // (see agentTemplateDir); injectable so tests need no installed package.
+    // (see agentTemplateDir); skillDir: the fallback Nera skill (see
+    // installedSkillDir). Both injectable so tests need no installed package.
     const {
         cwd = process.cwd(),
         runNpm = defaultRunNpm,
         templateDir = packageTemplateDir(),
+        skillDir = skillSourceDir(),
     } = options
 
     const pkg = JSON.parse(
@@ -157,7 +176,7 @@ export async function runUpdate(args = [], options = {}) {
 
     if (kind === 'legacy') {
         if (args.includes('--migrate') || args.includes('--yes')) {
-            await migrateLegacy(cwd, pkg, runNpm, templateDir)
+            await migrateLegacy(cwd, pkg, runNpm, templateDir, skillDir)
         } else {
             printLegacyGuidance()
         }
@@ -175,5 +194,6 @@ export async function runUpdate(args = [], options = {}) {
     console.log(`🔄 Updating Nera packages: ${targets.join(', ')}`)
     runNpm(['update', ...targets], cwd)
     await syncAndReportAgentFiles(cwd, templateDir)
+    await syncAndReportSkill(cwd, skillDir)
     console.log('✅ Up to date.')
 }

package/src/scaffold.js

@@ -3,6 +3,7 @@ import fs from 'fs/promises'
 import fssync from 'fs'
 import path from 'path'
 import { fileURLToPath } from 'url'
+import { skillSourceDir, syncSkill } from './skill.js'
 
 // Directory-safe and npm-safe: no separators, no traversal, no leading dot or
 // dash, nothing the shell could reinterpret. Deliberately stricter than npm's
@@ -182,6 +183,16 @@ async function applyTheme(targetDir, theme) {
     console.log(`  ✓ Using theme "${theme}"${pkgName ? ` (${pkgName})` : ''}`)
 }
 
+// The Nera skill for AI assistants, in both folders the clients read
+// (.agents/skills/nera, .claude/skills/nera). Meant to be committed, and
+// refreshed by `nera update`.
+async function addSkill(targetDir) {
+    const results = await syncSkill({ cwd: targetDir, sourceDir: skillSourceDir() })
+    console.log(
+        `  ✓ Added the Nera skill for AI assistants (${results.map((r) => r.path).join(', ')})`
+    )
+}
+
 // Scaffold a thin Nera site: copy the template, name it, and (by default)
 // install its single dependency, @nera-static/nera. No git clone, no vendored
 // engine — the opposite of the old installer's clone-and-strip flow.
@@ -204,6 +215,7 @@ export async function scaffoldProject(projectName, options = {}) {
     await copyDir(templateDir(), targetDir, { skipStarters: Boolean(theme) })
     await personalize(targetDir, packageName)
     if (theme) await applyTheme(targetDir, theme)
+    await addSkill(targetDir)
 
     if (install) {
         console.log('📦 Installing dependencies...')

package/src/skill.js

@@ -0,0 +1,108 @@
+import fs from 'fs/promises'
+import fssync from 'fs'
+import path from 'path'
+import { fileURLToPath } from 'url'
+
+// The folders of a site the Nera skill is copied into: `.agents/skills/` is
+// read by Codex, Cursor, Copilot and Gemini CLI, `.claude/skills/` by Claude
+// Code. Each `nera/` folder is wholly Nera's; nothing beside it is touched.
+export const SKILL_TARGETS = [
+    path.join('.agents', 'skills', 'nera'),
+    path.join('.claude', 'skills', 'nera'),
+]
+
+// The skill's source ships inside this package (package.json `files`).
+export const skillSourceDir = () =>
+    path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'skills', 'nera')
+
+// The skill a site is synced to: the one in the site's installed
+// @nera-static/nera (read after npm has updated it), so it matches the Nera
+// version the site runs. Falls back to fallbackDir when nothing is installed
+// there or the installed version predates the skill.
+export function installedSkillDir(cwd, fallbackDir) {
+    const installed = path.join(cwd, 'node_modules', '@nera-static', 'nera', 'skills', 'nera')
+    return fssync.existsSync(path.join(installed, 'SKILL.md')) ? installed : fallbackDir
+}
+
+async function readIfExists(file) {
+    try {
+        return await fs.readFile(file)
+    } catch (err) {
+        if (err.code === 'ENOENT' || err.code === 'EISDIR') return null
+        throw err
+    }
+}
+
+async function entries(dir) {
+    try {
+        return await fs.readdir(dir, { withFileTypes: true })
+    } catch (err) {
+        if (err.code === 'ENOENT' || err.code === 'ENOTDIR') return []
+        throw err
+    }
+}
+
+// Make `target` an exact copy of `source`: copy what is missing, rewrite what
+// differs, remove what the source no longer has. Writes only on change.
+// Returns true when anything was written or removed.
+async function mirror(source, target) {
+    let changed = false
+    const stat = await fs.lstat(target).catch(() => null)
+    if (stat && !stat.isDirectory()) {
+        await fs.rm(target, { recursive: true, force: true })
+    }
+    if (!stat || !stat.isDirectory()) {
+        await fs.mkdir(target, { recursive: true })
+        changed = true
+    }
+
+    const wanted = new Set()
+    for (const entry of await entries(source)) {
+        wanted.add(entry.name)
+        const from = path.join(source, entry.name)
+        const to = path.join(target, entry.name)
+        if (entry.isDirectory()) {
+            if (await mirror(from, to)) changed = true
+            continue
+        }
+        const content = await fs.readFile(from)
+        const current = await readIfExists(to)
+        if (current !== null && current.equals(content)) continue
+        await fs.rm(to, { recursive: true, force: true })
+        await fs.writeFile(to, content)
+        changed = true
+    }
+
+    for (const entry of await entries(target)) {
+        if (wanted.has(entry.name)) continue
+        await fs.rm(path.join(target, entry.name), { recursive: true, force: true })
+        changed = true
+    }
+    return changed
+}
+
+// Bring a site's copies of the Nera skill in line with sourceDir: each of
+// SKILL_TARGETS becomes an exact mirror of it. Nothing outside those two
+// `nera/` folders is read or written. Returns one { path, action } per
+// folder (path relative to cwd, with `/`), action being `created`,
+// `updated` or `unchanged`; printing is the caller's job.
+export async function syncSkill({ cwd = process.cwd(), sourceDir }) {
+    if (!fssync.existsSync(path.join(sourceDir, 'SKILL.md'))) {
+        throw new Error(
+            `The Nera skill (${sourceDir}) has no SKILL.md. This is a packaging ` +
+                'bug in @nera-static/nera, not a problem with your site.'
+        )
+    }
+
+    const results = []
+    for (const target of SKILL_TARGETS) {
+        const dir = path.join(cwd, target)
+        const existed = fssync.existsSync(dir)
+        const changed = await mirror(sourceDir, dir)
+        results.push({
+            path: target.split(path.sep).join('/'),
+            action: !existed ? 'created' : changed ? 'updated' : 'unchanged',
+        })
+    }
+    return results
+}