Introducing operate.txt: A YAML spec for AI agents navigating SaaS products

A developer has created operate.txt, a specification for documenting how AI agents should interact with web applications. The file addresses issues encountered when using Claude's computer use feature to navigate a SaaS product, where the AI agent repeatedly questioned whether loading screens indicated broken functionality.

Problem and solution

While using Claude Code + computer use to navigate BrandyBee (a SaaS product) as a first-time user, the developer identified specific pain points where Claude struggled:

• During a brand analysis that takes 90-120 seconds, Claude asked "Is this a loading state or is something wrong?" at 28% completion
• An "Approve" button that triggers paid API calls without confirmation UI
• A Language dropdown that only populates after Country is selected
• Async processes taking 2-5 minutes that appear stalled

Each time, the response was "no, that's normal, just wait." This led to the creation of operate.txt as an equivalent to robots.txt for crawlers or sitemap.xml for search engines, but specifically for AI agents operating products.

operate.txt specification

The operate.txt file is a YAML file hosted at yourdomain.com/operate.txt that documents:

• What each screen is
• What loading states look like and how long they take
• Which actions are irreversible
• The step-by-step path for common tasks
• What agents should never do

The most useful section is async_actions, which tells agents details like "this process takes 90-120 seconds, don't refresh, don't navigate away, here are the stages it goes through."

Creation process and examples

The developer open-sourced the spec with real examples including their own SaaS, an e-commerce template, and a SaaS dashboard template at https://github.com/serdem1/operate.txt.

The creation process involves having Claude navigate your product, watching where it hesitates, then having Claude draft the operate.txt file. The developer corrects what Claude gets wrong, creating a feedback loop where the AI finds gaps and the human fills them.