Agent Guide
How to implement OpenContext in your AI agents.
System Prompt Instructions
Add these instructions to your agent's system prompt to enable OpenContext usage:
Always use read_context before making code changes.
First list available topics, then read any topic
relevant to the task.
Use save_context whenever you learn a durable
project rule, architectural decision, convention,
API contract, or debugging note that future agents
should know.
Prefer small, focused context topics in snake_case
or kebab-case. Keep the content concise, factual,
and written in markdown.Recommended Workflow
Analyze & Save Context
Ask an architect agent to analyze the project and save durable decisions with save_context.
Read Before Coding
Ask build agents to call read_context before making changes.
Update When Learning
Let agents update context when they discover something that should survive the current chat.
Review Like Docs
Review .opencontext/ files like normal project documentation.
Common Patterns
Architecture Decisions
Topic: architecture Content: "We use Next.js App Router with server components by default. Client components only when interactions require useState/useEffect."
API Contracts
Topic: api-contracts
Content: "All API routes return { data, error } format.
Use 400 for validation, 401 for auth, 500 for server
errors. Pagination uses cursor-based approach."Coding Rules
Topic: coding_rules Content: "- Use const over let when possible - Prefer early returns over nested ifs - Name booleans with is/has/can prefix - Keep functions under 30 lines"
Pre-built Agents
We provide ready-to-use agent prompts for common workflows:
Topic Lifecycle & ADR-Style Frontmatter
Topics support optional YAML frontmatter to track their lifecycle status — useful when decisions evolve over time and old context should be visible but clearly flagged as outdated.
Frontmatter Fields
| Field | Type | Description |
|---|---|---|
| description | string | Short summary used in the auto-generated index |
| status | active | deprecated | superseded | Lifecycle status. Defaults to active when omitted. |
| supersedes | string | Topic name this topic replaces (used by the newer topic) |
| superseded_by | string | Topic name that replaced this one (used by the older topic) |
Example
---
description: OAuth2 + PKCE authentication flow
status: active
supersedes: auth-legacy
---
# Authentication v2
Migrated from JWT to OAuth2 with PKCE.---
description: JWT-based authentication (no longer used)
status: superseded
superseded_by: auth-v2
---
# Legacy Auth
Deprecated in favor of auth-v2.The auto-generated index.md will display badges like [DEPRECATED] and [SUPERSEDED] next to non-active topics, along with cross-references showing which topic replaced or was replaced.