BxSites AI Features

Four independent, AI-facing features. Two help an AI coding assistant author a bx-sites project: short always-present instruction files (AGENTS.md and friends) and the on-demand skill pack (this repository). Two expose a published site's own content to AI agents: llms.txt + published Markdown source (always on) and the MCP index (mcp: true).

Agent instruction files (AGENTS.md, CLAUDE.md, .cursorrules)

bxSites new my-docs --agents=agents,claude,cursor   # pick the files (default: agents only)
bxSites new my-docs --agents=none                   # or --no-agents: skip them
bxSites agents:sync [--agents=agents,claude,cursor] # retrofit/refresh an existing project

new writes AGENTS.md by default; claude adds CLAUDE.md and cursor adds .cursorrules. Each holds the same short content-authoring cheat sheet (frontmatter keys, content-block directives, reserved folders, the page:new -> serve -> lint -> build workflow), generated from the project's real theme and source folder, inside a marked block:

<!-- bxsites:agents:start -->
...generated cheat sheet...
<!-- bxsites:agents:end -->

• Only the text between the markers is ever replaced; anything written above or below survives every agents:sync (run it after a bx-sites upgrade).
• A target file that exists without the markers is skipped and reported, never overwritten - delete the markers on purpose to opt a file out.
• A missing target file is created; .markdownlint.json is always (re)written, by both new and agents:sync, even with --agents=none.
• An unknown --agents target throws BxSites.UnknownAgentTarget.

Instruction file vs skill pack: the instruction file is a short, always-loaded cheat sheet covering what most content edits need; the skills below are 16 detailed guides an assistant loads on demand for a specific task (theming, deployment, i18n, ...). Most projects benefit from both. Not to be confused with the AGENTS.md in the bx-sites repo itself, which is about working on bx-sites' own source.

llms.txt and published Markdown source

No config needed. Every build:

• writes site/llms.txt - a Markdown index listing every non-hidden page (absolute URLs when baseURL is a full URL, else base-path relative). Each page's title links to its published raw .md source, with a separate [HTML] link to the rendered page;
• publishes each page's original .md next to its HTML (site/guides/deployment.md beside site/guides/deployment/index.html), with a "Download Markdown" link on the page.

An LLM can fetch clean Markdown directly instead of scraping rendered HTML. This is separate from mcp: true, which adds a structured index for MCP clients.

MCP server (mcp: true)

mcp: true

Every build then writes three files alongside the rendered pages, which bxSites Cloud reads to expose a public, read-only MCP server for the published site (the same idea as GitBook's "MCP servers for published docs") - so Claude, ChatGPT, or any other MCP-aware client can search/browse/retrieve content directly instead of scraping rendered HTML. Building the files is free with bxSites build alone; actually serving them over the network as a live MCP server needs a paid bxSites Cloud plan. false (default) skips the whole step - no extra cost, nothing written.

Independent of search/searchProvider - unrelated switches. mcp never touches the visitor-facing search box, and turning search off never disables mcp-index.json. This is also why it can't reuse search-index.json: that file only exists for the "local" provider and is deliberately truncated (400 chars/entry, shipped to every visitor's browser); mcp-index.json is fetched server-side by bxSites Cloud and keeps the complete, untruncated page body.

The three files

• site/mcp-index.json - one entry per non-hidden page/post: title, url, tags, headings (every h1-h6, in order), body (complete plain text, HTML stripped, never truncated), type ("page"/"post"), categories (post only, [] for a page), updatedAt. For a blog post updatedAt is its raw frontmatter date; for a docs page it is the frontmatter date if set, else the source file's last-modified time as ISO-8601, else "".
• site/mcp-manifest.json - one per build (site root only): every tree that got its own index/nav (path, label, version, locale, default), so bxSites Cloud's MCP server can offer version/locale-aware tools without guessing bx-sites' own directory conventions.
• site/mcp-nav.json - one per tree (main, /next/, each /versions/<name>/, each locale sub-tree): that tree's own nav, the exact same nested { title, url, order, icon, children } shape the theme's sidebar renders from. A group heading with no index.md of its own has an empty url.

mcp-index.json and mcp-nav.json are written once per rendered tree; mcp-manifest.json once per build, at the site root - same "once per tree vs. once per build" split search-index.json and the version/locale system already use (see bx-sites-blog-versioning-i18n).

Installing this skill pack in a project

ortus-boxlang/bx-sites-skills (this repository) is the official skill pack - every skill is a single self-contained SKILL.md, so any install path below installs it correctly. Works with any assistant supporting the Agent Skills format (Claude Code, Cursor, Codex, and others).

npx skills add (any project, needs only Node.js)

npx skills add ortus-boxlang/bx-sites-skills           # whole pack
npx -y skills add ortus-boxlang/bx-sites-skills -y     # non-interactive (CI/scripts)
npx skills add ortus-boxlang/bx-sites-skills/skills/bx-sites-deployment   # one skill

coldbox ai skills install (ColdBox CLI)

coldbox ai skills install ortus-boxlang/bx-sites-skills/bx-sites-deployment

See the BoxLang Skills Directory for the catalog this pulls from.

bxSites skills:install (bx-sites' own wrapper)

A thin wrapper that installs straight into the current project (or --projectRoot, which must exist) - handy right after scaffolding, so the assistant knows bx-sites from the very first prompt. It runs npx -y skills add ortus-boxlang/bx-sites-skills[/skills/<name>] -y in the project root: non-interactive, installing into every AI assistant it detects there:

bxSites skills install
bxSites skills:install --skill=bx-sites-deployment   # one skill

Requires Node.js/npx on PATH, the same requirement npx skills add has on its own. A failure (no npx, network error, ...) throws BxSites.SkillsInstallFailed and exits 1; on success it tells you to restart or reload any AI assistant open on the project to pick up the new skills.

Verifying an install

Look for a new SKILL.md under the assistant's own skills directory (e.g. .claude/skills/bx-sites-getting-started/SKILL.md for Claude Code), or just ask the assistant something a skill covers and check the answer matches this pack's own documentation.