AI Agent Instructions
Every new project gets an AGENTS.md content-authoring cheat sheet automatically - frontmatter keys, content block directives, and the page-authoring workflow, generated from your project's real theme and source folder.
AI Agent Instructions
bxSites new writes an AGENTS.md at your project's root by default - a
compact cheat sheet covering what most AI coding-agent edits to your content
actually need: recognized frontmatter keys, every ::: name ::: content
block directive with its syntax, the reserved folders, and the basic
page:new -> serve -> lint -> build workflow. It's generated from
your project's real theme and source folder, not a generic template, and
it's the content-authoring counterpart to the deeper
AI Agent Skills pack - a quick reference an assistant
can read in one pass, versus skills it loads on demand for a specific task.
This is a different audience than AGENTS.md at the root of the bx-sites
repository itself - that one teaches an assistant how to work on bx-sites'
own source code. This guide is about the file scaffolded into your
generated site project, to help an assistant edit your content correctly.
What gets written
bxSites new my-docs
my-docs/
├── AGENTS.md
├── .markdownlint.json
├── bxsites.yaml
└── docs/
├── assets/
└── index.md
.markdownlint.json is always written alongside it - a ruleset tuned for
bx-sites content (relaxes line-length, hard-tab, and bare-URL rules that
would otherwise flag ordinary bx-sites Markdown, like a long content-block
directive line or a code fence with no language tag).
Choosing which file(s)
Not every project uses Claude Code specifically, so CLAUDE.md/.cursorrules
are opt-in via --agents:
bxSites new my-docs --agents=agents,claude
bxSites new my-docs --agents=none
# .markdownlint.json is still written either way
| Target | File |
|---|---|
agents (default) | AGENTS.md |
claude | CLAUDE.md |
cursor | .cursorrules |
Keeping it fresh: agents:sync
The generated content sits inside a marked block:
<!-- bxsites:agents:start -->
...generated cheat sheet...
<!-- bxsites:agents:end -->
Edit freely above or below the markers - your own project notes, team
conventions, links to an internal style guide, whatever you want. Run
agents:sync anytime (after a bx-sites upgrade adds new directives or
frontmatter keys, or to retrofit a project scaffolded before this feature
existed) and only the marked block gets refreshed:
bxSites agents:sync
Three outcomes per target file, reported back:
- Created - the file didn't exist yet.
- Updated - markers found, the block between them refreshed, everything outside them left untouched.
- Skipped - the file exists but has no markers. Nothing is overwritten; this is either a file you hand-wrote before this feature existed, or one whose markers you removed on purpose to opt it out of future syncs.
agents:sync also always (re)writes .markdownlint.json to the current
canonical ruleset, and takes the same --agents= flag as new to target
specific file(s).
FAQ
No - only the text between <!-- bxsites:agents:start --> and
<!-- bxsites:agents:end --> is ever replaced. Content you add outside
those markers, in the same file, is preserved across every sync.
Delete (or never add back) the bxsites:agents:start/end markers.
agents:sync treats a markerless file as hand-authored and reports it
as skipped rather than overwriting it.
No - they cover different scopes. This is a single, always-present
cheat sheet for content authoring; AI Agent Skills
(bxSites skills:install) is a much deeper, thirteen-skill pack an
assistant loads on demand, covering everything from theming to
deployment. Most projects benefit from both.
Reader comments aren't a bx-sites feature yet - the generated file says so explicitly, so an assistant doesn't invent syntax that doesn't exist.
Source
- Generator:
models/build/AgentsFileGenerator.bx - CLI verbs:
models/cli/New.bx(new's--agentsflag),models/cli/AgentsSync.bx - See CLI Reference and CLI Reference for the full flag reference.