Agent context — How stagewise agents understand your project - Docs - stagewise: The Agentic IDE for Open-Source Models

The agent doesn’t know about your project by magic — it builds understanding from several sources. Together, these form the agent’s context: everything the agent knows when processing your message. All sources feed into a single reasoning pass, so the agent understands both what you’re asking and why in the context of your project.

WORKSPACE.md

When you connect a workspace, stagewise generates a WORKSPACE.md file in .stagewise/. This is the primary way the agent understands your project at a high level:

Project type, languages, and runtime
Package structure and dependency graph
Build scripts and CI configuration
Key files and their architecture

The agent reads WORKSPACE.md automatically for every workspace. stagewise keeps it up to date across sessions.

Commit .stagewise/WORKSPACE.md to source control to share project analysis with your team, or add to .gitignore if you prefer.

Skills

Skills are SKILL.md files that give the agent structured instructions for specific tasks. They teach the agent project-specific patterns, workflows, and constraints. A skill lives in a folder:

.stagewise/skills/my-skill/
├── SKILL.md          # Instructions the agent follows
├── references/       # Reference files the agent can read
└── assets/           # Supporting files

Skills load from two locations in priority order:

.stagewise/skills/ — stagewise-specific (highest priority)
.agents/skills/ — Shared across AI tools

Learn more about creating skills →

AGENTS.md

An AGENTS.md file in your project root can provide custom instructions — coding conventions, style rules, or project-specific patterns.

AGENTS.md is opt-in and disabled by default. It can get outdated and mislead the agent. Use WORKSPACE.md and skills instead.

@mentions

In the chat, type @ to give the agent precise, immediate context:

@mention files — Attach a workspace file so the agent reads it immediately
@mention tabs — Attach a browser tab so the agent sees what you’re looking at

Chat input with multiple context attachments including an image, a browser tab, and a selected DOM element

Context attachments make the prompt specific without forcing you to describe every detail in text.

DOM context

When you select an element in the browser viewport, the agent receives:

The element’s HTML structure and DOM position
Computed CSS styles
Bounding box and dimensions
A unique CSS selector path

Point at anything in the browser and say “change this” — the agent knows exactly what you mean. Learn how →

Example: context in action

Say you type: “Refactor the Button component to use the new design tokens.”

Source	What the agent learns
`WORKSPACE.md`	It’s a React + Tailwind project with a design token system
`@mention Button.tsx`	Sees the current component code
`SKILL.md` (design tokens)	Knows the token naming conventions and migration rules
DOM context (the button)	Sees what the button currently looks like

All of this feeds into one reasoning pass. The more relevant context you provide, the more predictable the output.

What’s next

Workspaces

Connect multiple project folders for full-stack agent workflows.

Skills & plugins

Create custom skills and use built-in plugins to extend your agents.

Skills & context reference

Step-by-step guide to generating WORKSPACE.md and configuring skills.

​WORKSPACE.md

​Skills

​AGENTS.md

​@mentions

​DOM context

​Example: context in action

​What’s next

Workspaces

Skills & plugins

Skills & context reference

WORKSPACE.md

Skills

AGENTS.md

@mentions

DOM context

Example: context in action

What’s next