Agent Onboarding

Every AI coding agent that opens a sitemd project gets taught the full system — file structure, markdown syntax, MCP tools, 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 calls one MCP tool 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 a context file at the project root. sitemd ships three variants — one per agent platform — containing identical information in platform-native formats:

Each file covers:

• First steps — the five-call workflow to go from zero to a published page
• File structure — what lives in pages/, settings/, theme/, engine/
• Page format — frontmatter fields and their purpose
• Settings format — YAML-only files with inline comments
• MCP tools — every tool name, 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.

Codex CLI

Codex uses a different discovery mechanism — it reads SKILL.md from the plugin bundle. This file contains the same information in a more compact format: project structure, MCP tools table, first steps workflow, and a syntax reference listing.

The first steps workflow

Every context file begins with the same ordered workflow:

1. Call 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. Call sitemd_site_context — get a writing brief with site identity, conventions, and full syntax reference
4. Call sitemd_pages_create — create a page using rich components
5. Call sitemd_content_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 tool calls. The agent learns the site's name, existing content, title convention, and available syntax before writing anything.

Syntax reference in MCP

The sitemd_site_context tool 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 calls sitemd_site_context, 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 twelve agent skills — structured task definitions that encode multi-step workflows beyond what context files cover. Skills handle content generation, dev server management, deployment, site scaffolding, website cloning, markdown importing, SEO audits, OG image generation, and feedback reporting.

See Agent Skills for the complete reference with usage syntax and behavior for all twelve skills.

Skills ship in two formats for cross-agent compatibility:

Both directories contain identical skill files. GitHub Copilot discovers skills via .github/skills/ (populated from the same source).

Platform-specific configs

Each agent platform has its own manifest format for plugin/extension discovery. These live in the engine alongside the MCP server:

All three platforms use the same MCP server underneath. The manifests differ only in format — the tools, parameters, 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 context file):

• File structure and page format
• All 35 MCP tool names and descriptions
• Full markdown syntax with examples
• Writing conventions by content type
• The five-step workflow to follow

On first tool call (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_site_context):

• 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_content_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.