prompts/

Prompt contributions — optional content appended to every chat system prompt for every user with the realm installed. Currently supports examples.md.

⚠️ Tax on every chat turn. Bytes you add here are paid by every user, every turn, even when they’re not invoking your realm. Hosts enforce a soft size ceiling (Embabel’s reference host: 1024 bytes/realm, configurable via assistant.realm-loader.prompt-max-bytes); over-budget realms still load but the host surfaces a warning in the world problems list.

Treat prompts/ as a pointer, not a manual. Tell the LLM the capability exists and where to find the routing detail. Put the actual workflow examples in a Skill, which the LLM activates on demand only when relevant — paid only when used.

Recommended shape

A one-or-two-sentence pointer is the canonical pattern:

HubSpot CRM is available — contacts, companies, deals, tickets, owners,
pipelines, associations. Activate the **`hubspot-crm`** skill via the
skill tool before making any HubSpot call; the skill carries the
workflow patterns, namespace conventions, and required-field details.

The substantive routing content (tool names, code-mode call shapes, edge cases, idiomatic patterns) goes into skills/<realm>-skill/SKILL.md. The skill loader makes it activatable; the LLM pulls it in only when it decides the user’s intent matches.

Anti-pattern

User: "Show me the open issues in embabel/agent"
→ Call github tool → list_issues (GitHub issues, not world tasks)

User: "Create a GitHub issue for the memory leak bug"
→ Call github tool → issue_write (NOT world task creation)

[… ten more examples, code-mode call sketches, edge cases …]

This was the original convention and is being deprecated. Bulk routing examples in prompts/ cost every user on every turn; the same examples in a Skill cost only users actively asking about that capability. Migrate existing realms by trimming prompts/examples.md to a pointer and moving the body into the realm’s Skill.