# Context Awareness

How the agent knows what the user is looking at.

- Repository: https://github.com/BuilderIO/agent-native (7579 stars)
- Category: Design
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add BuilderIO/agent-native --skill context-awareness -g -a claude-code -y`
Codex: `npx skills add BuilderIO/agent-native --skill context-awareness -g -a codex -y`
Cursor: `npx skills add BuilderIO/agent-native --skill context-awareness -g -a cursor -y`
Gemini CLI: `npx skills add BuilderIO/agent-native --skill context-awareness -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add BuilderIO/agent-native`

## Description

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.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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.

```tsx
// app/hooks/use-navigation-state.ts
import { useAgentRouteState } from "@agent-native/core/client/navigation";
import { TAB_ID } from "@/lib/tab-id";

The rest: https://github.com/BuilderIO/agent-native/blob/HEAD/.agents/skills/context-awareness/SKILL.md