AI Agent Skills
Give Claude Code, Cursor, Codex, and other AI coding assistants deep, structured knowledge of bx-sites - install the official skill pack via npx, the ColdBox CLI, or bxSites' own skills:install verb.
On this page
AI Agent Skills
An Agent Skill is a small,
self-contained SKILL.md file that teaches an AI coding assistant how to do
one specific thing well - the assistant loads it automatically, on demand,
whenever a task matches what the skill describes. Instead of re-explaining
bx-sites' own conventions to your assistant in every conversation (how
::: card ::: blocks work, what bxsites.yaml's redirects key expects,
how page:new differs from a hand-written file), a skill hands it that
knowledge up front, written the way bx-sites itself works.
ortus-boxlang/bx-sites-skills
is the official skill pack for this project - thirteen skills covering
everything from scaffolding a new project to troubleshooting this
repository's own GitHub Actions. They work with any assistant that supports
the Agent Skills format (Claude Code, Cursor, Codex, and others).
Install
Three ways to install the pack - pick whichever fits your workflow:
npx skills add
The skills CLI works with any
project, regardless of language or runtime, and needs nothing but Node.js:
npx skills add ortus-boxlang/bx-sites-skills
npx -y skills add ortus-boxlang/bx-sites-skills -y
Install a single skill instead of the whole set by pointing at it directly:
npx skills add ortus-boxlang/bx-sites-skills/skills/bx-sites-deployment
coldbox ai skills install
If you already have the ColdBox CLI, it can install straight from the same GitHub source - see the BoxLang Skills Directory:
coldbox ai skills install ortus-boxlang/bx-sites-skills/bx-sites-deployment
bxSites skills:install
bx-sites also ships its own one-shot verb - a thin wrapper over npx skills add that installs the whole pack straight into the current project, so a
freshly-scaffolded project's AI assistant knows bx-sites from the very first
prompt:
bxSites skills install
# or, equivalently:
bxSites skills:install
bxSites skills:install --skill=bx-sites-deployment
Requires Node.js/npx on PATH (the same requirement npx skills add has
on its own) - see CLI Reference for the
full flag reference.
Available skills
Each skill is a single, self-contained SKILL.md (no bundled resource
files), so it installs correctly through every path above:
| Skill | Description |
|---|---|
bx-sites-getting-started | Install bx-sites, scaffold a new project (or migrate an existing GitBook/mkdocs/Notion one in), project layout, page frontmatter, linking, build/serve/clean. |
bx-sites-content-blocks | GitBook-style ::: name ::: blocks - cards, columns, stepper, buttons, embeds, page-link/link-preview, prompt, updates, includes, conditional content, OpenAPI widget. |
bx-sites-markdown | Admonitions, footnotes, definition lists, content tabs, code-block annotations, Mermaid, math, tables, icons, responsive images, Alpine.js interactivity. |
bx-sites-variables-functions | Reusable {{ variables }} and BoxLang magic functions (docs/functions.bxs), including status-badge/rating/progress-bar visualizer recipes. |
bx-sites-blog-versioning-i18n | The blog (docs/blog/posts/), versioned docs (docs/versions/), translated locales (docs/i18n/), and redirects. |
bx-sites-content-quality | Pre-build content checks without a full build - lint, blog:drafts, blog:find, search:query. |
bx-sites-build | build/serve/clean/search-index, plus doctor/stats/check diagnostics on a built site. |
bx-sites-configuration | The full bxsites.yaml/bxsites.json key reference - baseURL, nav, redirects, markdown, assets, and more. |
bx-sites-themes | Choosing, customizing, overriding, installing, or writing a theme; the ThemeProvider contract. |
bx-sites-search | Search providers - local (MiniSearch), Algolia DocSearch, Pagefind, and wiring up a custom provider. |
bx-sites-plugins | Writing/installing a bx-sites plugin (build-lifecycle hooks) or a CLI provider (new bxSites verbs). |
bx-sites-deployment | Deploy targets (S3/Azure/GCS/Firebase/FTP/SFTP/rsync/Netlify/Vercel/Cloudflare Pages/GitHub Pages), package, and the GitHub Actions publishing workflow. |
bx-sites-actions | Operate and troubleshoot bx-sites' own GitHub Actions workflows (tests, snapshot, release, docs, pages). |
Example prompts
Once installed, just describe what you want - your assistant picks the matching skill on its own:
Scaffold a new bx-sites project called "acme-docs" using the gitbook
theme, add a Getting Started page, and start the dev server.
Add a three-step ::: stepper ::: block to docs/getting-started.md walking
through install, scaffold, and build - and a ::: cards ::: grid linking
to the three main guides.
Add a Netlify deploy target to bxsites.yaml and explain which
environment variable it expects for the auth token.
FAQ
A short YAML frontmatter block (name, description - the trigger an
assistant matches against) followed by plain Markdown instructions,
conventions, and examples for that one topic. No bundled scripts or
resource files - every skill in this pack is a single file, by design,
so it installs the same way through npx skills add, coldbox ai skills install, and bxSites skills:install alike.
No - every install path supports installing just one skill by name (see Install above). Most projects are fine installing the whole pack, though: an assistant only loads a skill's content when a task actually matches it, so unused skills cost nothing at prompt time.
Any assistant that supports the Agent Skills format - Claude Code,
Cursor, Codex, and others. npx skills add/coldbox ai skills install
detect which assistant(s) your project already has configured and
install into each one automatically.
Check for a new SKILL.md under your assistant's own skills directory
(e.g. .claude/skills/bx-sites-getting-started/SKILL.md for Claude
Code) - or just ask your assistant something the skill covers (e.g.
"how do I add a Netlify deploy target?") and see whether its answer
matches this documentation.
It shells out to the real npx skills add under the hood, so it needs
Node.js on PATH the same way that command does on its own - install
Node.js from nodejs.org and try again. Or skip
bxSites's own wrapper entirely and run npx skills add ortus-boxlang/bx-sites-skills directly.
Yes - npx skills add/coldbox ai skills install work in any
directory. bxSites skills:install specifically needs an existing
--projectRoot (the current directory by default), same as every
other bxSites verb, but that project doesn't need to be built yet -
installing skills before you've written a single page is exactly the
point, so your assistant already knows bx-sites for the very first
prompt.
Source
- Skills repository: ortus-boxlang/bx-sites-skills
- bx-sites repository: ortus-boxlang/bx-sites
- BoxLang Skills Directory: skills.boxlang.io