Skip to main content

​
Overview

This repo includes a .cursor/ directory that configures Cursor + AI agents to work effectively across Omi’s codebase. It contains:
  • Rules that apply based on file patterns (backend/flutter/web/etc.)
  • Reusable “skills” and slash commands
  • Specialized agents (e.g. backend API, Flutter, firmware)
  • Internal reference docs for agents (not the same as the public docs/ site)
If you’re contributing to Omi and using Cursor, understanding .cursor/ makes it much easier to add consistent automation and avoid common mistakes.

​
.cursor/ vs docs/ (important)

  • docs/ is the public Mintlify site at docs.omi.me. What belongs there is defined in docs/AGENTS.md: how to use the app, hardware/DIY, and how to build on Omi. Unlisted MDX or MD under docs/ is still a public URL.
  • .cursor/ is editor/agent configuration for contributors and AI tooling inside this repo.
Do not dump a runbook, flag table, invariant, or agent-only rule into docs/ “temporarily.” Those live next to the owning code (backend/docs/, desktop/macos/docs/, .github/agent-docs/, product/invariants/) or in a private tracker. We document .cursor/ publicly here so contributors can use it; .cursor/docs/ is not the public site.

​
What’s inside .cursor/

​
Rules (.cursor/rules/)

Rules are small, focused guidance files (typically *.mdc) that apply automatically based on globs (e.g. backend/**/*.py, app/**/*.dart, web/**/*.ts(x)). Typical rule topics:
  • Architecture: module boundaries + import hierarchy
  • Testing & verification: what to run before merging
  • Style and conventions: formatting, localization requirements, common mistakes

​
Skills (.cursor/skills/)

Skills are reusable “playbooks” for recurring workflows. A skill folder typically contains:
  • SKILL.md: the skill’s instructions and checklists
  • commands/: slash commands (e.g. /backend-test, /pr)
  • agents/: specialized agents that focus on specific domains

​
Commands (.cursor/commands/)

Legacy / general commands that show up in Cursor when you type /. (Many commands also live under skills/*/commands/.)

​
Agents (.cursor/agents/)

Legacy / compatibility agent definitions. Most agents live under skills/*/agents/.

​
Internal agent docs (.cursor/docs/)

Internal reference docs used by agents (architecture maps, component indexes, internal guidance). Note: These are for agent operation and contributor context, not for end users.

​
Hooks (.cursor/hooks/ and .cursor/hooks.json)

Optional hook scripts/config to observe and extend the agent loop. Useful for enforcing workflows, validation, and automation.

​
MCP config (.cursor/mcp.json)

Configuration for MCP servers that provide external tools (e.g. browser testing, Notion/Figma integration if enabled).

​
Common contributor workflows

​
Add a new rule

  1. Add a focused rule file under .cursor/rules/ (e.g. backend-foo.mdc)
  2. Ensure it targets the correct file glob(s)
  3. Keep it actionable: conventions + “how to verify”

​
Add a new skill

  1. Create .cursor/skills/<skill-name>/SKILL.md
  2. Put any related slash commands under .cursor/skills/<skill-name>/commands/
  3. Put any related agents under .cursor/skills/<skill-name>/agents/

​
Update public documentation

If your change affects how people use the app, hardware, or public developer APIs:
  • Read docs/AGENTS.md first. Only then update docs/ and docs/docs.json.
  • Operator runbooks, flags, and invariants do not go on the public site.

​
Safety & maintenance notes

  • Don’t put secrets (tokens, keys, credentials) in .cursor/ files.
  • Keep rules layer-aware (e.g. don’t encourage importing from routers/ inside utils/).
  • Prefer linking to public docs in docs/ only when the page fits docs/AGENTS.md. Keep .cursor/docs/ for internal agent context.