Public schema
The complete machine-readable contract is published at a permanent URL and can be validated with ordinary JSON Schema tooling.
CursorBuddy Guide Standard
A small, portable JSON document that teaches a compatible assistant what matters on a website, what to avoid, and how to guide a person through it.
Why it is open
Portable by design.
Portable JSON
A guide is a file, not an opaque database object. Any compatible assistant can read it and any tool can produce it.
Versioned
Readers use the explicit version field. A future revision cannot silently change what a 1.0 document means.
Safe boundary
The shared format carries guidance, page selectors, and same-site actions. It never carries API keys, provider credentials, or local file access.
The document
One exact host. One clear purpose.
match declares the exact hostname and path pattern. The most specific approved match wins. Wildcard hosts are deliberately excluded, and paths can only use one trailing *.
skills, important, and avoid supply concise context. actions offer safe prompts, same-site links, or a tour. pages can refine the guidance for an exact path.
{
"$schema": "https://cursorbuddy.app/standards/cursorbuddy-guide/1.0/schema.json",
"version": "1.0",
"name": "Example docs helper",
"summary": "Help someone complete the first setup.",
"match": {
"hosts": ["docs.example.com"],
"paths": ["/getting-started*"]
},
"appearance": {
"activation": "immediate",
"greeting": "Need a hand here?"
},
"skills": ["Explain installation in plain language"],
"important": ["Use the command for the visitor's platform"],
"avoid": ["Never ask for or enter a secret"],
"actions": [
{ "label": "Show me around", "tour": true }
],
"tour": [
{
"selector": "#install",
"text": "Choose your platform, then copy this command."
}
],
"pages": {}
}Discovery
Site-owned or community-published.
A website can publish its own CursorBuddy manifest. A browser extension can also resolve an approved community guide when a person reaches a matching site. A site-owned guide always takes priority.
Community publication is moderated. Saving a personal guide does not expose it; submission creates a review request, and only an approved document reaches public discovery.
1Author and validate
2Keep private or submit
3Review the exact document
4Resolve on a matching site
Implement it
Compatibility requirements
A 1.0 reader must validate the document, use exact hostname matching, honor the declared path, ignore guides that do not validate, and keep credentials outside the guide. It should ask before consequential page actions.
A 1.0 writer should keep the document under 24 KB, use stable selectors, write short guidance, and include a clear avoid list.