How-to

How to use and manage context prompts

Use context prompts to change how the Buffaly agent behaves in a specific situation without changing the entire baseline personality or adding a new executable capability.

Who this is for

Use this article when you want a situational behavior overlay for coding discipline, browser or UI automation, email-writing style, realtime-call or SMS responses, or wiki and documentation editing rules.

Do not start with a context prompt when you need a new tool, service, provider, durable memory, or one repeatable task workflow. Those belong in capabilities, memory, or prompt actions.

Quick answer

A context prompt is a trusted prompt file that Buffaly applies as a behavioral overlay for a situation. Source defines ContextPrompt as an ontology prototype with a ContextPhrase and PromptPath.

The master prompt remains the baseline contract for the agent.
A context prompt narrows behavior for one situation.
Buffaly can load a context prompt by prototype name with ToLoadContextPrompt.
Runtime session profiles can also name a default PromptContext.
The active runtime composes the system prompt from the master prompt, context prompt, and runtime sections.

Context prompts versus nearby concepts

Concept	What it controls	Use it when
Master prompt	Baseline role and operating contract.	The agent's default behavior should change broadly.
Context prompt	Situational behavior overlay.	The agent is in a mode such as coding, browser use, email writing, calls, SMS, or wiki editing.
Prompt skill/action	Discoverable text-backed task instruction.	You need a repeatable task workflow that can be loaded as an action.
ProtoScript action	Structured executable action.	You need typed parameters, action discovery, and executable logic.
Task artifact	Durable work record.	You need requirements, evidence, decisions, and acceptance criteria.
Memory	Structured long-term facts and workflows.	Buffaly should remember something for future discovery.

The verified distinction is important: a prompt action returns task workflow instructions, while ToLoadContextPrompt returns a header that says to apply the prompt as a behavioral overlay for the current turn.

Where context prompts live

Context prompt files live under the active project ContextPrompts folder, and matching ontology prototypes are declared in that folder's index file. Verify the active project root before editing because installations can use different project roots.

Prompt filescontent/projects/<ProjectName>/ContextPrompts/*.prompt.md

Prototype indexcontent/projects/<ProjectName>/ContextPrompts/index.pts

Common context prompt examples

CodingContextPromptFor writing or modifying computer code.

BrowserContextPromptFor browser navigation and UI automation.

EmailWritingContextPromptFor composing or editing email.

RealtimeCallContextPromptFor responding to realtime calls.

How Buffaly loads a context prompt

Runtime session composition loads the session profile's PromptContext by name and resolves it to ContextPrompts/<PromptContext>.prompt.md under the active project root. Names, not paths, are expected.
The explicit ToLoadContextPrompt action resolves a ContextPrompt prototype by name, reads its PromptPath, and returns trusted context prompt text with a behavioral-overlay header.
Users can ask Buffaly to apply a context prompt for the current work even when it is not the session default.

The easiest way: ask Buffaly to use one

Coding: Use the coding context for this source edit. Inspect relevant files first, keep the change small, validate it, and commit only intended files.

Documentation: Apply the wiki context before editing this article. Use the checked-in wiki as source of truth and avoid changing unrelated pages.

Email: Before drafting the reply, load the email-writing context prompt if it is available.

Browser: This task involves browser UI automation. Use the browser context prompt if it matches the available context prompts.

Expected behavior: recognize the relevant situation, bind to a context prompt prototype when available, load it, treat the result as behavior guidance rather than completion, then continue normal verified work.

Inspect, create, edit, and set defaults

Inspect available prompts

Ask Buffaly to list context prompts in the active project with names, context phrases, and prompt paths. Manual checks include the context prompt index, prompt files, active agent profile PromptContext, and prompt-context catalog.

Create or edit

Inspect existing examples first. Add or update the prompt file plus matching ContextPrompt prototype with stable name, entity name, context phrase, project-relative prompt path, and definition prompt path when following the existing pattern.

Set a default

Agent profiles can include PromptContext. Source resolves it as a name and looks for ContextPrompts/<PromptContext>.prompt.md. Change a default only when it should apply broadly to new sessions for that profile.

Validate

Load the prototype, show the prompt path and a short excerpt, confirm the prompt file exists, and check whether the active session or agent profile is already using it.

Validation checklist

The context prompt prototype exists in the project context prompt index.
The prototype PromptPath points at an existing prompt file.
ToLoadContextPrompt("<PrototypeName>") returns context-prompt instructions, not an error.
The active agent profile's PromptContext matches an existing prompt file when you expect it to be default.
The prompt-context catalog lists the prompt and marks the profile default where applicable.

Common mistakes and troubleshooting

Treating load as completion. ToLoadContextPrompt returns guidance text. Buffaly should continue the task after loading it.

Using a path where a name is required. Runtime PromptContext expects a name such as CodingContext, not a path.

Forgetting the ontology prototype. Keep the prompt file and .pts prototype aligned for explicit loading and discovery.

Editing the master prompt instead. If only one situation needs different behavior, prefer a context prompt.

Putting secrets in prompt text. Use Buffaly secrets and credential handling instead of API keys, tokens, or passwords in prompts.

Assuming existing sessions changed. Start a fresh test session or verify the active session context before assuming a new default is active.

Master prompts Create a Buffaly agent Skills, services, and tools Memory and skills Back to docs