Skip to main content

​
How Workshop knows your project

Every conversation starts fresh in terms of the AI context window — but Workshop doesn’t start from zero. It reads project context files at the beginning of each conversation, giving it persistent knowledge about your project’s architecture, conventions, and current state. This context lives in the .workshop/ directory at your project root.

​
The .workshop/ directory

your-project/
├── .workshop/
│   ├── context.md      # Project context — what Workshop should know
│   ├── rules.md        # Project rules — how Workshop should behave
│   └── skills/         # Custom skills for specialized tasks
├── src/
├── README.md
└── ...

​
context.md

The primary project context file. Workshop reads this at the start of every conversation to understand your project’s architecture, current state, and conventions. How to update it:
  • Using /context: Type /context in any conversation. Workshop analyzes your project files and conversation history, then updates context.md with an intelligent summary.
  • With custom focus: Type /context focus on API patterns to steer what gets emphasized.
  • Manually: Edit .workshop/context.md directly to add or correct information.
When to update:
  • After completing a major feature or milestone
  • Before starting a new conversation in an existing project
  • When Workshop seems to have forgotten important project details

​
rules.md

Project-specific rules that guide Workshop’s behavior. Use this for coding standards, naming conventions, framework preferences, and any guidelines Workshop should follow consistently. 
# Project Rules

- Use TypeScript for all new files
- Follow BEM naming for CSS classes
- All API endpoints must include input validation
- Write tests for every new utility function
Rules are different from context: context describes what your project is, rules describe how Workshop should behave when working on it.

​
skills/ directory

Custom skills are reusable instruction sets for specialized tasks. They extend Workshop’s capabilities for project-specific workflows like deployment, testing patterns, or domain operations.

​
Context file precedence

Workshop checks for context files in a specific order, using the first one found:
PriorityFileDescription
1 (highest).workshop/context.mdWorkshop’s native context format
2.workshop/rules.mdWorkshop’s rules file
3.cursor/rules/*.mdcCursor-compatible rules (all .mdc files concatenated)
4 (lowest).cursorrulesLegacy Cursor rules file
Only the highest-priority file found is loaded — they are not merged. If you have both .workshop/context.md and .cursorrules, only context.md is used.
If you’re migrating from another AI coding tool, Workshop automatically picks up your existing .cursorrules or .cursor/rules/ files — no changes needed.

​
Custom instructions

Custom Instructions are global preferences set in Settings (wrench icon) that Workshop follows across all conversations and projects. Think of them as your personal defaults. 
Every visualization should have a transparent background and white labels.

When building web applications, prioritize clean, accessible design and responsive layouts.

Always commit working code after each major milestone.
Custom Instructions differ from rules.md in scope: custom instructions apply everywhere, rules apply to a specific project. For details on where to set them, see Settings.

​
Context window management

AI models have limited context windows — the amount of information they can process at once. As you use more of the window, costs increase, latency increases, and response quality can degrade.

​
Keep conversations focused

Each conversation should have a clear purpose — one feature, one bug fix, one exploration thread. Starting new conversations for different tasks keeps context clean and relevant.

​
Use /compact proactively

Don’t wait for Workshop to warn you. If a conversation has been going for a while and you’ve completed a logical milestone, compact and continue. See Working with the Agent for details on the /compact command.

​
Maintain your context.md

A well-maintained context.md means Workshop starts every conversation with a solid understanding of your project. This reduces the need to re-explain architecture, conventions, and current state.

​
Provide files strategically

When giving Workshop files for context:
  • Drag and drop files into the chat (Desktop) to include their path
  • Use the file upload feature (Cloud) to add files to your project
  • Specify whether the file is for Workshop to read and understand (context) or to include in what it builds (content)

​
Long Context Mode

For extended sessions on large projects, enable Long Context Mode in Settings. This uses an expanded context window, allowing much longer conversations before needing to compact.
Usage beyond the standard context window may result in higher credit usage per turn.