Brainstorming
xpinjection/test-driven-spring-boot
You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior.
How to build, preview, and verify Quarkus documentation locally: root Maven build, docs rebuild, Roq dev server preview.
Apache-2.0Auto-check passed
Install Building Docs
$ npx skills add quarkusio/quarkus --skill building-docs -a claude-codeProject install by default; add -g for ~/.claude/skills/.
$ gh skill install quarkusio/quarkus building-docs --agent claude-codeProject scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).
$ git clone --depth 1 https://github.com/quarkusio/quarkus.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/building-docs .claude/skills/building-docs && rm -rf skills-srcUse ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.
Claude Code skills documentation · loads skills from .claude/skills/
Install the "building-docs" agent skill from https://github.com/quarkusio/quarkus/tree/main/.agents/skills/building-docs into .claude/skills/building-docs/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "building-docs", then confirm the skill loads.Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$skill-installer install https://github.com/quarkusio/quarkus/tree/main/.agents/skills/building-docsType this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.
$ npx skills add quarkusio/quarkus --skill building-docs -a codexProject install goes to .agents/skills/; add -g for ~/.codex/skills/.
$ gh skill install quarkusio/quarkus building-docs --agent codexProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/quarkusio/quarkus.git skills-src && mkdir -p .agents/skills && cp -r skills-src/.agents/skills/building-docs .agents/skills/building-docs && rm -rf skills-srcUse ~/.agents/skills/ instead of .agents/skills for a personal install.
Codex skills documentation · loads skills from .agents/skills/
Install the "building-docs" agent skill from https://github.com/quarkusio/quarkus/tree/main/.agents/skills/building-docs into .agents/skills/building-docs/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "building-docs", then confirm the skill loads.Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add quarkusio/quarkus --skill building-docs -a cursorProject install goes to .agents/skills/; add -g for ~/.cursor/skills/.
$ gh skill install quarkusio/quarkus building-docs --agent cursorProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/quarkusio/quarkus.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/.agents/skills/building-docs .cursor/skills/building-docs && rm -rf skills-srcUse ~/.cursor/skills/ instead of .cursor/skills for a personal install.
Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/
Install the "building-docs" agent skill from https://github.com/quarkusio/quarkus/tree/main/.agents/skills/building-docs into .cursor/skills/building-docs/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "building-docs", then confirm the skill loads.Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gemini skills install https://github.com/quarkusio/quarkus.git --path .agents/skills/building-docs--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.
$ npx skills add quarkusio/quarkus --skill building-docs -a gemini-cliProject install goes to .agents/skills/; add -g for ~/.gemini/skills/.
$ gh skill install quarkusio/quarkus building-docs --agent gemini-cliProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/quarkusio/quarkus.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/.agents/skills/building-docs .gemini/skills/building-docs && rm -rf skills-srcUse ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.
Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/
Install the "building-docs" agent skill from https://github.com/quarkusio/quarkus/tree/main/.agents/skills/building-docs into .gemini/skills/building-docs/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "building-docs", then confirm the skill loads.Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gh skill install quarkusio/quarkus building-docsInstalls for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).
$ npx skills add quarkusio/quarkus --skill building-docs -a github-copilotProject install goes to .agents/skills/; add -g for ~/.copilot/skills/.
$ git clone --depth 1 https://github.com/quarkusio/quarkus.git skills-src && mkdir -p .github/skills && cp -r skills-src/.agents/skills/building-docs .github/skills/building-docs && rm -rf skills-srcUse ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.
GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/
Install the "building-docs" agent skill from https://github.com/quarkusio/quarkus/tree/main/.agents/skills/building-docs into .github/skills/building-docs/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "building-docs", then confirm the skill loads.GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add quarkusio/quarkus --skill building-docs -a opencodeOpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.
$ gh skill install quarkusio/quarkus building-docs --agent opencodeProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/quarkusio/quarkus.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/.agents/skills/building-docs .opencode/skills/building-docs && rm -rf skills-srcUse ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.
OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/
Install the "building-docs" agent skill from https://github.com/quarkusio/quarkus/tree/main/.agents/skills/building-docs into .opencode/skills/building-docs/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "building-docs", then confirm the skill loads.OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
Facts
- Skill name
building-docs- GitHub stars
- 16k
- Token cost
- ~1.8k tokens
- SKILL.md length
- 865 words
- Files
- 1
- Skills in repo
- 12
- Repo updated
- First seen
- Licence
- Apache-2.0
At a glance
How to build, preview, and verify Quarkus documentation locally: root Maven build, docs rebuild, Roq dev server preview.
- Works in 6 steps: Environment Setup → Root Build (from repo root) → Quick Docs Rebuild (from docs/) → …
- SKILL.md covers Supported Platforms, Quick Start, How It Works and Step 0 — Environment Setup, plus 8 more sections
- Calls just, bash and git
What it does
Building Docs is an agent skill from quarkusio/quarkus. How to build, preview, and verify Quarkus documentation locally: root Maven build, docs rebuild, Roq dev server preview.
Its SKILL.md is about 1.8k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.
It works with Java. The repository describes itself as: Quarkus: Supersonic Subatomic Java. The licence is Apache-2.0.
Example prompts
- “/building-docs”
Workflow steps
6 steps, taken from the step headings in SKILL.md.
What it can do on your machine
Read from SKILL.md and the folder at commit 31ef64b. It shows what the files ask for, not the result of running them.
Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
Shell commands in SKILL.md call:
justbashgit
From the folder's file list and the shell code blocks in SKILL.md.
Network
Links to these hosts (documentation or services it may open):
docs.quarkiverse.io
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.
Context cost
Building Docs loads about 1.8k tokens when it runs. Until then it costs about 34 tokens; SKILL.md has 865 words of instructions outside code blocks.
Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.
Safety
Auto-check passed
The automated check found no risky patterns in SKILL.md.
Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.
SKILL.md
The full file from quarkusio/quarkus at commit 31ef64b, republished under its Apache-2.0 licence (© quarkusio). 865 words, ~1,848 tokens.
Download SKILL.mdSave it as
.claude/skills/building-docs/SKILL.md (or your agent's skills folder).- name
- building-docs
- description
- How to build, preview, and verify Quarkus documentation locally: root Maven build, docs rebuild, Roq dev server preview.
Building Documentation
Supported Platforms
This workflow is supported on Linux, macOS, and Windows through WSL2.
Native Windows shells (PowerShell, CMD, Git Bash) are not supported.
Java 21+ is required. The repository includes a ./mvnw wrapper — no
separate Maven install is needed.
Quick Start
Run the full pipeline in one command:
just docs-previewHow It Works
The script uses local marker files to keep the preview workflow fast:
docs/.docs-preview-root-build-last-run— last successful root build. Used to decide whether Step 1 can be skipped.docs/.docs-preview-root-build-head— Git HEAD at last root build. Detects branch switches, checkouts, and pulls.docs/.docs-preview-docs-build-last-run— last successful docs rebuild. Used to decide whether Step 2 can be skipped.docs/.docs-preview-last-run— last preview run. Used to detect recently changed files and open the right preview URL.docs/.docs-preview-times— cached execution times for progress estimates.
All marker files are gitignored. Delete them to force a full rebuild.
Caveat: The script detects changes to docs sources and pom.xml files,
but does not detect uncommitted changes outside docs/ (e.g., new config
properties, extension metadata, or generated-doc producers). If you modify
code that affects generated documentation, force a root build manually:
QUARKUS_DOCS_PREVIEW_FULL=1 just docs-preview
Step 0 — Environment Setup
Source detect-env.sh to set $MVN_THREADS, $MAVEN_OPTS, and
$BROWSER_CMD:
. docs/detect-env.shThe script computes Maven heap, thread count, and browser automatically based on your machine.
Step 1 — Root Build (from repo root)
Run once, then re-run roughly once a week, after pulling significant upstream changes, or when Step 2 fails.
Use -DquicklyDocs, not -Dquickly (which sets skipDocs=true).
The extra flags are not covered by the profile and are needed to skip
integration-test modules, Gradle plugin build, and javadoc generation.
./mvnw $MVN_THREADS clean install -DquicklyDocs \
-Dno-test-modules -Dskip.gradle.build=true -Dmaven.javadoc.skip=trueFallback (single-threaded) if the parallel build fails:
./mvnw clean install -DquicklyDocs \
-Dno-test-modules -Dskip.gradle.build=true -Dmaven.javadoc.skip=trueStep 2 — Quick Docs Rebuild (from docs/)
cd docs
../mvnw -ntp package -Dasciidoctor.fail-if=ERROR # quick rebuild (~1 min)
../mvnw -ntp clean package -Dasciidoctor.fail-if=ERROR # if output looks staleThe -Dasciidoctor.fail-if=ERROR override lets the build succeed despite
AsciiDoctor warnings (the default WARN level fails on cross-reference
or attribute warnings that are harmless for local preview).
Step 3 — Sync (from docs/)
First time: ./sync-web-site.sh
Subsequent iterations — fast re-sync (<1 second). The script invokes
sync-web-site.sh with the existing website checkout as the target
directory, skipping the rm -rf + git clone (~4 min) but running
all post-processing (asset moves, link rewrites, index.html creation,
and Qute escaping) through the same code path as a full sync.
To re-sync manually while the Roq dev server is still running (e.g.
after just docs-preview is done and you are iterating), run from
the docs/ directory:
cd docs
./sync-web-site.sh main "$(pwd)/target/web-site"Do not re-run docs-preview.sh while the server is still up — the
port check will reject it. Use the command above instead.
Step 4 — Serve (from docs/target/web-site)
The site is built with Quarkus Roq,
a Quarkus-based static site generator. ./mvnw quarkus:dev starts a
live-reload dev server — edits to content files are picked up
automatically without a server restart.
cd target/web-site
./mvnw quarkus:dev -DskipTestsThe server starts on port 8042 by default (set in config/application.properties). To use a different port:
QUARKUS_HTTP_PORT=8081 ./mvnw quarkus:dev -DskipTestsStop: Ctrl-C in the terminal running the dev server, or kill the background
process printed at the end of just docs-preview.
Step 5 — Verify
The script auto-detects what you were working on and opens the right page:
| Content type | How detected | Preview URL |
|---|---|---|
| 1 guide | Recently modified .adoc in docs/src/main/asciidoc/ | /version/main/guides/<name>.html (direct) |
| 2-4 guides | Multiple .adoc files modified | Opens a tab for each guide |
| 5+ guides | Many files modified | /version/main/guides/ (listing) |
| Blog post | Recently modified .adoc in content/posts/ | /blog/<slug>/ (deep-link) |
| No changes | No recent .adoc changes found | / (homepage) |
Show full SKILL.md (316 more words)Show less
Iteration Loop
Edit .adoc → save → Step 2 (~1 min) → Step 3 re-sync (<1s) → browser auto-refreshesRoq dev mode watches for file changes and triggers an incremental rebuild automatically. Escalate to Step 1 when Step 2 fails or after significant upstream changes.
When to escalate to a root build
| Symptom | Action |
|---|---|
| Quick rebuild succeeds but content looks stale | Try ../mvnw -ntp clean package -Dasciidoctor.fail-if=ERROR in docs/ |
clean package still broken or fails | Root build (Step 1) |
Pulled new upstream changes to main | Root build (Step 1) |
| Root build is roughly a week old | Root build (Step 1) |
| New config properties or extensions added | Root build (Step 1) |
Troubleshooting
Port 8042 already in use — Another process is using port 8042.
First, check whether it is a leftover preview from a previous run
(e.g. a java process launched by mvnw). If so, kill it and retry.
Always tell the user before using a different port — do not
silently switch ports without informing them. If the conflict cannot
be resolved, ask the user which port to use, then set the environment
variable:
QUARKUS_HTTP_PORT=8081 bash docs/docs-preview.shServer process exited unexpectedly — Maven started but then died. Scroll up in the terminal to find the build error, or check the log printed at the end of the run. Common causes: corrupted local Maven repository, a missing or broken dependency, or a compile error.
Changes not appearing — Roq dev mode watches source files. If a change is not picked up, stop and restart the dev server.
Preview shows stale content after full sync — Delete
docs/target/web-site and re-run just docs-preview to force a fresh
clone and sync.
./mvnw not executable — The Maven wrapper exists in the website
checkout but lacks the execute bit:
chmod +x docs/target/web-site/mvnwDo not install Maven system-wide as a workaround. The repository-provided wrapper pins the correct Maven version.
./mvnw missing — The website checkout inside docs/target/web-site
is incomplete or corrupted. Delete it and re-run to force a fresh clone:
rm -rf docs/target/web-site
just docs-previewForce a full root build — Set QUARKUS_DOCS_PREVIEW_FULL=1 before
running: QUARKUS_DOCS_PREVIEW_FULL=1 just docs-preview
© quarkusio, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file
Files
Just SKILL.md in .agents/skills/building-docs of quarkusio/quarkus.
Open the folder on GitHubat commit 31ef64b
Compare with similar skills
Building Docs next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.
| Skill | Stars | Used in | Tokens | Auto-check | Licence | Repo updated |
|---|---|---|---|---|---|---|
| Building Docs this skillquarkusio/quarkus | 16k | — | ~1.8k | Automated safety check: Pass | Apache-2.0 | |
| Brainstormingxpinjection/test-driven-spring-boot | 112 | 54 repos | ~2.6k | Automated safety check: Pass | MIT | |
| Android API Diffgkd-kit/gkd | 43k | — | ~796 | Automated safety check: Pass | GPL-3.0 | |
| Video Cover Imageitwanger/toBeBetterJavaer | 18k | — | ~3.3k | Automated safety check: Pass | None | |
| Lancedb Update Lance Dependencylancedb/lancedb | 12k | — | ~1.1k | Automated safety check: Pass | Apache-2.0 | |
| Java SDK E2E Test with Replay Snapshotgithub/copilot-sdk | 11k | — | ~1.8k | Automated safety check: Pass | MIT |
Similar skills
Android API Diff
gkd-kit/gkd
Looks up Android framework Java and AIDL APIs across versions with the android-api-diff CLI: signatures, availability, source files and hidden-API access code.
Video Cover Image
itwanger/toBeBetterJavaer
Generate matched 3:4, 16:9, and 4:3 short-video cover images from toBeBetterJavaer video scripts or AI/Java technical topics.
Lancedb Update Lance Dependency
lancedb/lancedb
Update LanceDB to a specific Lance release or tag. An agent skill from lancedb/lancedb.
- Official
Java SDK E2E Test with Replay Snapshot
github/copilot-sdk
Creates a Java SDK end-to-end test for the Copilot SDK that runs against a recorded YAML snapshot through a replay proxy, so CI needs no real authentication.
Fory Release
apache/fory
Prepare an Apache Fory release candidate from a clean release branch, including the version bump, RC tag, JVM staging, ASF source artifacts, SVN upload, and vote email.
More from quarkusio/quarkus
All 12 skills in this repoManage Deprecations
quarkusio/quarkus
Maintain @Deprecated code in the Quarkus codebase: remove code that has been deprecated for more than 12 months, add the @Deprecated annotations that were missed when a related element was…
Building And Testing
quarkusio/quarkus
How to build and test Quarkus: Maven commands, build flags, incremental builds, justfile aliases, and important build rules.
Classloading And Runtime Dev
quarkusio/quarkus
Quarkus split classloading model, runtime-dev module wiring, conditional dependencies, and common classloading mistakes.
Converting Recorders To Services
quarkusio/quarkus
Step-by-step guide for converting Quarkus extensions from the legacy @Record/@Recorder pattern to the ServiceRegistrar service system.
Creating Extensions
quarkusio/quarkus
How to create a new Quarkus extension: full module layout, package naming, artifact naming, dependency rules, and Dev UI setup.
Pull Requests
quarkusio/quarkus
Rules for preparing pull requests and commits in the Quarkus project: title conventions, description format, commit hygiene, labels, and contribution policies.
Related
Works with
Questions about Building Docs
What does Building Docs do?
How to build, preview, and verify Quarkus documentation locally: root Maven build, docs rebuild, Roq dev server preview. Building Docs is an agent skill from quarkusio/quarkus. How to build, preview, and verify Quarkus documentation locally: root Maven build, docs rebuild, Roq dev server preview.
How do I install Building Docs in Claude Code?
Run `npx skills add quarkusio/quarkus --skill building-docs -a claude-code`. Or copy the skill folder (.agents/skills/building-docs in quarkusio/quarkus) into .claude/skills/building-docs in your project. Claude Code loads it when a task matches its description.
How do I install Building Docs in Codex?
Run `npx skills add quarkusio/quarkus --skill building-docs -a codex`. Or copy the skill folder (.agents/skills/building-docs in quarkusio/quarkus) into .agents/skills/building-docs in your project. Codex loads it when a task matches its description.
Can I use Building Docs in Cursor, Gemini CLI or GitHub Copilot?
Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add quarkusio/quarkus --skill building-docs -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/building-docs, .gemini/skills/building-docs, .github/skills/building-docs and .opencode/skills/building-docs in your project.
What does Building Docs need to run?
Going by SKILL.md and its folder, Building Docs needs the command-line tools its instructions call (just, bash and git).
Does Building Docs access the network?
SKILL.md names 1 domain. As links in the text: docs.quarkiverse.io. This is read from the text; nothing was executed.
Is Building Docs safe to install?
Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.
What licence does Building Docs use?
Building Docs is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.
How many tokens does Building Docs use?
About 1.8k tokens (SKILL.md is roughly 7.4k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.
What are the alternatives to Building Docs?
Skills that share tags, products or a category with Building Docs: Brainstorming (xpinjection/test-driven-spring-boot, 112 stars), Android API Diff (gkd-kit/gkd, 43k stars), Video Cover Image (itwanger/toBeBetterJavaer, 18k stars) and Lancedb Update Lance Dependency (lancedb/lancedb, 12k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.
Who maintains Building Docs?
quarkusio (a GitHub organization) maintains it in quarkusio/quarkus, which has 15,931 GitHub stars. The repository holds 12 skills in this directory. The repository was last updated on October 7, 2026.
Source: quarkusio/quarkus on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.