Agent Onboarding

Every AI coding agent that opens a sitemd project gets taught the full system — file structure, markdown syntax, CLI commands, and writing conventions — without reading documentation pages or source code. The onboarding happens through three layers that activate automatically.

How it works

sitemd delivers context through three channels, each reaching agents at a different point:

An agent that reads the context file and runs one CLI command has everything it needs to create pages with buttons, cards, galleries, embeds, modals, and forms — without ever visiting a docs page.

Context files

When an agent opens a sitemd project, it reads site.md at the project root. This single file covers:

• First steps — the five-step workflow to go from zero to a published page
• File structure — what lives in pages/, settings/, theme/
• Page format — frontmatter fields and their purpose
• Settings format — YAML-only files with inline comments
• CLI commands — every command, what it does, and when to use it
• Writing conventions — voice rules and structure by content type (docs, blog, changelog, roadmap)
• Groups system — how pages join navigable collections
• Markdown extensions — full syntax reference with examples for every component

The context file is self-contained. An agent that reads only this file can create correct sitemd pages with rich components.

The first steps workflow

The context file begins with the same ordered workflow:

1. Run sitemd status — understand the project state (page count, auth, deploy config, available actions)
2. List pages by reading the pages/ directory — see existing content with titles, slugs, and group membership
3. Run sitemd status --json — get a writing brief with site identity, conventions, and full syntax reference
4. Run sitemd pages create — create a page using rich components
5. Run sitemd validate — check the result against quality rules

This sequence takes an agent from "never heard of sitemd" to "created and validated a page" in five steps. The agent learns the site's name, existing content, title convention, and available syntax before writing anything.

Syntax reference

The sitemd status --json command returns a syntax field containing structured examples for every markdown component. Each entry has three parts:

The syntax reference covers 13 components:

The syntax is returned every time an agent runs sitemd status --json, right before writing. The agent gets exact patterns at the moment it needs them.

Page comment blocks

Every .md file in a sitemd project contains a syntax cheat sheet in its frontmatter comments:

---
# How to write in sitemd:
# Buttons: button: Label: /slug (see docs/buttons-and-links)
# Cards: card: Title, card-text: Text, card-image: URL, card-link: Label: /slug
# Embeds: embed: URL (YouTube, Vimeo, Spotify, CodePen, tweets, any URL)
# Gallery: gallery: with indented ![alt](url) lines (grid + lightbox)
# ...
#
title: My Page
---

This block is auto-injected by the build system on the first build. It serves two audiences:

• Human authors editing markdown files directly get an inline reference without leaving their editor
• Agents reading page files see the syntax alongside the content they're about to edit

The comment block is regenerated if deleted, keeping the reference in sync with the current engine version.

Skills

sitemd ships a single consolidated skill at .claude/skills/sitemd/ that encodes multi-step workflows for content generation, dev server management, deployment, site scaffolding, website cloning, markdown importing, SEO audits, OG image generation, release management, and feedback reporting.

See Agent Skills for the complete reference.

Platform-specific configs

Each agent platform has its own manifest format for plugin/extension discovery:

All platforms use the same sitemd CLI underneath. The manifests differ only in format — the commands and responses are identical across agents.

What agents learn and when

Here is the full sequence of what an agent knows at each stage:

On project open (reads site.md):

• File structure and page format
• The full suite of CLI commands and descriptions
• Full markdown syntax with examples
• Writing conventions by content type
• The five-step workflow to follow

On first command (sitemd status):

• Site name, page count, domain
• Auth state and license info
• Which services are configured (deploy, email, analytics)
• Suggested next actions based on current state

Before writing (sitemd status --json):

• Site identity (name, description, URL)
• Existing pages in the target group
• Title suffix convention
• Copy-pasteable syntax examples for every component
• Type-specific state (current changelog version, roadmap sections)

After writing (sitemd validate):

• Whether the description is under 160 characters
• Whether required frontmatter is present
• Whether internal links resolve
• Type-specific checks (blog has date line, docs has sidebar config)

The agent never needs to read source code, visit documentation, or ask the user how things work. The system teaches itself.