Documentation building skill

Author: jmartisk

.agents/skills/documentation-build/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: documentation-build
+description: >
+  How to build, preview, and incrementally rebuild the Quarkus documentation
+  site locally using Maven, sync scripts, and a containerized Jekyll server.
+---
+
+# Documentation Build
+
+## Full Build
+
+Build the entire documentation (from the repository root):
+
+```bash
+mvn clean install -DskipTests -Denforcer.skip -Dcheckstyle.skip -DskipITs=true -Dmaven.javadoc.skip=true
+```
+
+## Preview
+
+From the `docs/` directory, sync the generated site:
+
+```bash
+cd docs/
+./sync-web-site.sh
+```
+
+Then start a local Jekyll server with Podman:
+
+```bash
+podman run -p 4000:4000 -v "$(pwd)/target/web-site:/site:z" bretfisher/jekyll-serve
+```
+
+The site is available at `http://localhost:4000`.
+
+## Incremental Rebuild
+
+While the preview container is running, rebuild changed docs without a full
+clean build:
+
+```bash
+mvn package -Dno-build-cache
+```
+
+Then re-run `./sync-web-site.sh` in `docs/` to pick up the changes. The Jekyll
+server auto-reloads updated files.

AGENTS.md

@@ -98,3 +98,4 @@ Consult the relevant skill when you are about to do that type of work:
 | `coding-style` | Code formatting, visibility, naming conventions, and logging |
 | `building-and-testing` | Maven build commands, flags, incremental builds, and build rules |
 | `pull-requests` | PR title/description conventions, commit hygiene, labels, and contribution rules |
+| `documentation-build` | Building, previewing, and incrementally rebuilding the documentation site locally |

CLAUDE.md

@@ -23,3 +23,5 @@ guidance before starting work:
   when building, testing, or understanding Maven flags and build commands.
 - **Pull requests** — Read `.agents/skills/pull-requests/SKILL.md`
   when preparing a pull request, writing commit messages, or choosing labels.
+- **Documentation build** — Read `.agents/skills/documentation-build/SKILL.md`
+  when building, previewing, or rebuilding the documentation site locally.