Context Awareness
How the agent knows what the user is looking at.
Install
npx skills add BuilderIO/agent-native --skill context-awareness -g -a claude-code -y- Repository
- BuilderIO/agent-native7.6k
- Category
- Design
- Updated
- 3d ago
- License
- MIT
- Context cost
- Mediumabout 3,000 tokens
- Runs scripts
- No, instructions only
What it does
How the agent knows what the user is looking at. Use when exposing UI state to the agent, implementing view-screen or navigate actions, wiring navigation state, or debugging agent context issues.
Context Awareness
Rule
Apps can sync semantic navigation state when the route changes by using the
shared route-state hook. When screen context is available, Core includes a
<current-screen> snapshot in each agent turn, so the agent can get basic
route context without first calling another tool. Apps can add concise
visible-record details to that snapshot and expose selection in tab-scoped
state.
Why
Without context awareness, the agent is blind. It asks "which email?" when the user is staring at one. It cannot act on the current selection, cannot provide relevant suggestions, and cannot modify what the user sees. Context awareness is what makes the agent feel like a collaborator rather than a disconnected chatbot.
The Core Patterns
1. Navigation State (navigation key)
Use the shared route-state hook to write a tab-scoped navigation key as the
route changes. Include semantic screen state such as the view, open IDs, active
tab, and focused object.
UI side, use useAgentRouteState in the app's route-state hook. The app
can wrap it in an app-owned useNavigationState hook to map route paths to
semantic views and consume the agent's navigate command.
// app/hooks/use-navigation-state.ts
import { useAgentRouteState } from "@agent-native/core/client/navigation";
import { TAB_ID } from "@/lib/tab-id";
